1 .. include:: docs/header0.txt
3 ========================
5 ========================
7 :Contact: grubert@users.sourceforge.net
8 :Maintainer: docutils-develop@lists.sourceforge.net
11 :Web site: https://docutils.sourceforge.io/
12 :Copyright: This document has been placed in the public domain.
15 This document summarizes the major changes in previous and upcoming releases.
16 For a more detailed list of changes, please see the Docutils `HISTORY`_.
23 Command line interface
24 ----------------------
26 * The _`command-line usage pattern` will change:
30 - COMMAND [OPTIONS] [SOURCE [DESTINATION]]
31 + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]] [>DESTINATION]
33 * Remove short options ``-i`` and ``-o`` in Docutils 0.22.
34 Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
36 * Stop accepting the DESTINATION positional argument in Docutils 1.0.
37 Use output redirection or the option ``--output=DESTINATION``
38 (available since Docutils 0.20).
40 * Accept more than one source document and the short option
41 ``-o`` for ``--output`` in Docutils 2.0
43 For the rationale, see https://clig.dev/#arguments-and-flags.
46 https://packaging.python.org/en/latest/specifications/entry-points/
49 Document Tree / Docutils DTD
50 ----------------------------
52 * Do not lowercase reference names in the `refname attribute`_
53 (matching hyperlinks, footnotes, and citations remains case insensitive),
54 and drop the ``name`` attribute from <reference> nodes
57 .. _refname attribute: docs/ref/doctree.html#refname
62 * Change the default input encoding from ``None`` (auto-detect) to
63 "utf-8" in Docutils 0.22.
65 * Remove the input encoding auto-detection code in Docutils 1.0 or later.
70 * The `default HTML writer`__ will change in Docutils 2.0:
72 The rst2html_ front end and ``get_writer_by_name('html')`` select
73 "html4css1" now and will select "html5" in Docutils 2.0 and later.
75 - Use rst2html4_, ``docutils --writer=html4``, or
76 ``get_writer_by_name('html4')`` if you depend on stability of the
77 generated HTML code, e.g. because you use a custom style sheet or
78 post-processing that may break otherwise.
79 - Use rst2html5_, ``docutils`` or ``get_writer_by_name('html5')``
80 if you want a HTML5 document.
82 __ docs/user/html.html#html
86 - Move attribution behind the blockquote to comply with the `"living
87 standard"`__. (HTML5__ allows <cite> elements inside a blockquote.)
89 __ https://html.spec.whatwg.org/#the-blockquote-element
90 __ https://www.w3.org/TR/2014/REC-html5-20141028/grouping-content.html
91 #the-blockquote-element
93 - Change the default value for math_output_ to "MathML"
96 - Unitless image_ :width: and :hight: values and dimensions
97 read from the image due to a :scale: option will be written as
98 "width" and "hight" attributes instead of "style" rules to allow
99 specification of the aspect ratio to `prevent jank when loading
100 images`__ without overwriting an image size set in a CSS stylesheet
101 in Docutils 0.22 (cf. `feature-requests:102`__).
102 The current behaviour is kept for dimensions with value, so
103 users may specify, e.g. ``:width: 50px`` instead of ``:width: 50``
104 to override CSS stylesheet rules.
106 __ https://developer.mozilla.org/en-US/docs/Learn/Performance/Multimedia
107 #rendering_strategy_preventing_jank_when_loading_images
108 __ https://sourceforge.net/p/docutils/feature-requests/102/
110 - Change the default value of the initial_header_level_ setting to None
111 (<h2> if there is a document title, else <h1>) in Docutils 1.0.
113 - Remove option ``--embed-images`` (obsoleted by "image_loading_")
118 - Change default of use_latex_citations_ setting to True
121 - Change default of legacy_column_widths_ setting to False
124 - Remove ``use_verbatim_when_possible`` setting
125 (use literal_block_env_: verbatim) in Docutils 2.0.
127 - Don't wrap references with custom reference-label_ in
128 a ``\hyperref`` command in Docutils 0.22.
129 Specify, e.g., "ref" instead of "ref*" to keep generating hyperlinks.
131 .. _reference-label: docs/user/config.html#reference-label
133 * "null" writer: output will change to the empty string
138 - No more changing case in to uppercase, leave it to the source.
145 Allow multiple <term> elements in a <definition_list_item>
146 in Docutils 0.22 (cf. `feature-requests:60`__).
147 Third-party writers may need adaption.
149 __ https://sourceforge.net/p/docutils/feature-requests/60/
151 * Remove `parsers.rst.directives.CSVTable.HeaderDialect`
154 * Remove the "rawsource" argument from `nodes.Text.__init__()`
157 * Drop support for `old-format configuration files`_ in Docutils 2.0.
159 * Remove the ``--html-writer`` option of the `buildhtml.py`_ application
160 (obsoleted by the `"writer" setting`_ since Docutils 0.18)
163 * Revise the `String I/O`__ interface used by the `publish_string()`
164 and `publish_from_doctree()` publisher convenience functions.
165 (In Python 3, name and behaviour no longer match.)
167 __ docs/api/publisher.html#string-i-o
169 * Move math format conversion from docutils/utils/math (called from
170 docutils/writers/_html_base.py) to a transform__.
172 __ docs/ref/transforms.html
174 * Remove mistranslated localizations of the "admonition" directive name in
177 Use the English term, matching translations introduced in Docutils 0.21,
178 or specific admonitions instead of "aanmaning" (nl),
179 "admonition" (fr), "ammonizione" (it), "ermahnung" (de),
180 "exhortación" (es), "formaning" (da), "sciigo" (eo),
181 "upomnienie" (pl), "vermaning" (af),
182 to avoid errors in future conversions.
184 .. _front end tools: docs/user/tools.html
185 .. _input_encoding: docs/user/config.html#input-encoding
186 .. _math_output: docs/user/config.html#math-output
187 .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
188 .. _image_loading: docs/user/config.html#image-loading
189 .. _old-format configuration files:
190 docs/user/config.html#old-format-configuration-files
192 .. _rst2html: docs/user/tools.html#rst2html
193 .. _rst2html4: docs/user/tools.html#rst2html4
194 .. _rst2html5: docs/user/tools.html#rst2html5
195 .. _reference name: docs/ref/rst/restructuredtext.html#reference-names
196 .. _literal_block_env: docs/user/config.html#literal-block-env
197 .. _use_latex_citations: docs/user/config.html#use-latex-citations
198 .. _buildhtml.py: docs/user/tools.html#buildhtml-py
200 Release 0.21.2b.dev (unpublished)
201 =================================
203 Post-release waiting.
206 Release 0.21.1 (2024-04-10)
207 ===========================
209 The sdist in 0.21 was incomplete
211 - pypi allows no file replacing
212 - adding a postrelease suffix "post1": docutils-0.21.post1.tar.gz
213 works on pypi, but fails with pip because the metadata differs.
215 But if the metadata is 0.21.post1 pypi makes it a new release.
217 0.21.1 is the same code except for the version number.
220 Release 0.21 (2024-04-09)
221 =========================
225 - Drop support for Python 3.7 and 3.8.
227 - Provide ``rst2*`` "console_scripts" `entry points`_
228 (without the ``.py`` extension) instead of installing the
229 ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
231 Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:
233 - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
234 - Use ``python -m docutils.writers.odf_odt.prepstyles``
235 to `strip the page size`__ from an ODT writer stylesheet.
237 __ docs/user/odt.html#page-size
239 .. [#] Some Linux distributions already use the short names.
240 .. [#] The final rendering is done by a Sphinx-based build system
245 - Use the same CSV format for the ``:header:`` option and the main data
246 of the "csv-table_" directive.
248 - New option "loading" for the `"image" directive`_.
249 Sets the new attribute loading__ of the <image> doctree element.
251 __ docs/ref/doctree.html#loading
253 * Configuration changes:
255 - New configuration setting root_prefix_.
256 Configurable root directory for included files.
258 - New configuration setting sources_ for the "buildhtml.py" application.
260 - Simpler and more secure `input encoding`_ default behaviour:
262 Do not use the locale encoding as fallback if Python is started in
263 `UTF-8 mode`_. Stop using "latin1" as second fallback.
265 Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
266 configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
267 Do not remove other ZWNBSPs.
272 Stop setting the "footnote-reference" class value for footnote
273 references. Use the CSS selector ``[role="doc-noteref"]``
274 (works since Docutils 0.18, see minimal.css for examples).
276 Fix MathML rendering problems in Chrome/Chromium based browsers.
278 Embed SVG images as ``<svg>`` instead of data-URI.
281 Use .EE/.EX macros for literal blocks.
283 Render URI references (do not use .UR/.UE).
285 Use box option for tables.
289 `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
290 Python 2 compatibility hacks
291 `docutils.utils.Reporter.set_conditions()`
293 `docutils.core.Publisher.setup_option_parser()`
298 ``docutils/writers/html5_polyglot/italic-field-names.css``
299 Alternative style for Docutils field-lists.
303 ``install.py``, ``setup.py``
304 Metadata is now stored in ``pyproject.toml``,
305 supported by pip_ since version 19.0 (2019-01-22).
306 See README__ for installation alternatives.
308 __ README.html#installation
310 * Bugfixes and improvements (see HISTORY_).
312 .. _input encoding: docs/api/publisher.html#encodings
313 .. _csv-table: docs/ref/rst/directives.html#csv-table
314 .. _"image" directive: docs/ref/rst/directives.html#image
315 .. _root_prefix: docs/user/config.html#root-prefix
316 .. _sources: docs/user/config.html#sources
319 Release 0.20.1 (2023-05-17)
320 ===========================
322 Bugfix release. See HISTORY_ for details.
325 Release 0.20 (2023-05-04)
326 =========================
330 Docutils 0.20 is the last version supporting Python 3.7 and 3.8.
334 - Support Python 3.11 (patch #198 by Hugo van Kemenade).
339 Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note")
343 Do not load the `inputenc` package in UTF-8 encoded LaTeX sources.
344 (UTF-8 is the default encoding for LaTeX2e since 2018).
346 * Configuration changes:
348 - Settings in the [latex2e writer] configuration file section
349 are now ignored by the "xetex" writer.
350 Place common settings in section `[latex writers]`_.
352 - New command line setting output_. Obsoletes the ``<destination>``
353 positional argument (cf. `future changes`__).
355 __ `command-line usage pattern`_
357 * `utils.find_file_in_dirs()` now returns a POSIX path also on Windows;
358 `utils.get_stylesheet_list()` no longer converts ``\`` to ``/``.
360 * docutils/languages/
361 docutils/parsers/rst/languages/
363 - Support Ukrainian. Patch by Dmytro Kazanzhy.
367 - Removed. Use the coverage.py_ project instead,
368 ``coverage run test/alltests.py`` and ``coverage report``.
372 - Moved ``quicktest.py`` to ``tools/dev/``.
374 * Bugfixes and improvements (see HISTORY_).
376 .. _[latex writers]: docs/user/config.html#latex-writers
377 .. _output: docs/user/config.html#output
378 .. _coverage.py: https://pypi.org/project/coverage/
381 Release 0.19 (2022-07-05)
382 =========================
384 (Release 0.19b1 (2022-06-21))
386 * Drop support for Python 2.7, 3.5, and 3.6.
391 Wrap groups of footnotes in an ``<aside>`` for easier styling.
393 The CSS rule ``.footnote-list { display: contents; }`` can be used to
394 restore the behaviour of custom CSS styles.
396 * After package installation, the CLI commands ``python -m docutils`` and
397 ``docutils`` start the `generic command line front end tool`_.
399 * Support parsing "Markdown" input with 3rd party parsers
400 myst_, pycmark_, or recommonmark_.
402 * The default values for the "pep-references", "rfc-base-url",
403 and "python-home" `configuration settings`_ now use the "https:" scheme.
404 The PEP-writer template's header is updated to fix links and
405 resemble the header of official PEPs.
407 * Various bugfixes and improvements (see HISTORY_).
409 .. _generic command line front end tool:
410 docs/user/tools.html#generic-command-line-front-end
411 .. _myst: https://pypi.org/project/myst-docutils
412 .. _pycmark: https://pypi.org/project/pycmark/
413 .. _recommonmark: https://pypi.org/project/recommonmark/
414 .. _configuration settings: docs/user/config.html
417 Release 0.18.1 (2021-12-23)
418 ===========================
422 Docutils 0.18.1 is the last version supporting Python 2.7, 3.5, and 3.6.
424 * ``nodes.Node.traverse()`` returns a list again to restore backwards
425 compatibility (fixes bug #431).
426 Use ``nodes.Node.findall()`` to get an iterator.
428 * re-add module ``parsers.rst.directives.html``
429 (stub, emits deprecation warning and loads
430 "Meta" directive from its new place at ``parsers.rst.directives.misc``.)
432 * Small bugfixes (see HISTORY_).
435 Release 0.18 (2021-10-26)
436 =========================
441 - During `identifier normalization`_, leading number and hyphen
442 characters are no longer stripped from a `reference name`_, if the
443 id_prefix_ setting is non-empty.
446 with ``--id-prefix="DU-"``, a section with title "34. May"
447 currently gets the identifier key ``DU-may`` and after the
448 change the identifier key ``DU-34-may``.
450 - The default value for the auto_id_prefix_ setting changed to ``%``:
451 "use the tag name as prefix for auto-generated IDs".
452 Set auto_id_prefix_ to ``id`` for unchanged auto-IDs.
455 - Use the semantic tag <aside> for footnote text and citations, topics
456 (except abstract and toc), admonitions, and system messages.
457 Use <nav> for the Table of Contents.
459 - Make "auto" table column widths the default: Only specify column
460 widths, if the `"widths" option`_ is set and not "auto".
461 The table-style__ setting "colwidths-grid" restores the current default.
463 __ docs/user/config.html#table-style
465 - Items of a definition list with class argument "details" are
466 converted to `details disclosure elements`_. Example::
471 This additional information should be hidden.
473 - Do not add "compound-first", "compound-middle", or "compound-last" to
474 elements nested in a compound. Use child selector and ":first-child",
475 ":last-child" pseudo classes instead.
477 - Use class value "backrefs" instead of "fn-backref" for a span of
480 - Write footnote brackets and field term colons to HTML, so that they
481 are present also without CSS and when copying text.
483 - Move space character between section number and heading into
487 - Support more commands, fix mapping of commands to Unicode characters.
488 - Scale variable sized operators and big delimiters with CSS.
489 - Don't use <tt> element (deprecated in HTML5).
490 - Use STIX fonts if available.
493 `legacy_class_functions`_ setting default changed to "False",
494 admonitions are now environments.
496 * New standard Docutils doctree node: <meta__>.
498 __ docs/ref/doctree.html#meta
500 * New configuration settings:
502 - [latex writers] legacy_column_widths_ and
503 - [html5 writer] image_loading_.
506 ``iepngfix.htc`` and ``blank.gif`` (IE 6 workaround for `s5_html`).
508 * Removed sub-module:
509 ``parsers.rst.directives.html``
510 (reversed in release 0.18.1).
512 * Removed function: utils.unique_combinations()
513 (obsoleted by itertools.combinations()).
515 * Removed attributes:
517 - ``HTMLTranslator.topic_classes``: check ``node.parent.classes`` instead.
518 - ``nodes.Text.rawsource``: we store the null-escaped text in Text
519 nodes since 0.16 so there is no additional information in the
522 * Major refactoring and fixes/additions in
523 ``docutils/utils/math/math2html.py`` and
524 ``docutils/utils/math/latex2mathml.py``
525 (mathematical notation in HTML, cf. `LaTeX syntax for mathematics`_).
527 * nodes.Node.traverse() returns an iterator instead of a list
528 (reversed in release 0.18.1).
530 * Various bugfixes and improvements (see HISTORY_).
532 Fix spelling errors in documentation and docstrings.
533 Thanks to Dimitri Papadopoulos.
535 .. _"widths" option: __ docs/ref/rst/directives.html#table
536 .. _identifier normalization:
537 docs/ref/rst/directives.html#identifier-normalization
538 .. _id_prefix: docs/user/config.html#id-prefix
539 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
540 .. _details disclosure elements:
541 https://www.w3.org/TR/html52/interactive-elements.html#the-details-element
542 .. _LaTeX syntax for mathematics: docs/ref/rst/mathematics.html
543 .. _legacy_column_widths: docs/user/config.html#legacy-column-widths
546 Release 0.17.1 (2021-04-16)
547 ===========================
549 * Bug fixes (for details see the Docutils `HISTORY`_).
551 Release 0.17 (2021-04-03)
552 =========================
554 * Numerous bug fixes and improvements
555 (for details see the Docutils `HISTORY`_).
557 * Installing with ``setup.py`` now requires setuptools_.
558 Alternatively, install with pip_.
560 * The generic command line front end tool docutils-cli.py_ allows
561 the free selection of reader, parser, and writer components.
563 * Support Arabic language.
565 * New, **experimental** wrapper to integrate the `recommonmark`__
566 Markdown parser for use with Docutils.
567 Currently only tested with recommonmark version 0.4.0.
569 __ https://pypi.org/project/recommonmark/
573 - New option embed_images_.
575 - Use semantic tags (for details see the Docutils `HISTORY`_).
577 - Change the `initial_header_level`_ setting's default to "2", as browsers
578 use the `same style for <h1> and <h2> when nested in a section`__.
580 - New optional style ``responsive.css``, adapts to different screen
583 - Move non-essential styling from ``minimal.css`` to ``plain.css``
584 rsp. ``responsive.css``.
586 - Show code line numbers as pseudo-elements so they are skipped when
587 copying the code block from the page.
589 .. _initial_header_level: docs/user/config.html#initial-header-level
590 __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
591 .. _embed_images: docs/user/config.html#embed-images
595 - New configuration setting `legacy_class_functions`_.
597 - The special value "auto" for the `graphicx_option`_ setting
598 is no longer supported (it never worked for xetex/luatex).
600 - `Styling commands`__ using the legacy ``\docutilsrole`` prefix are
601 now ignored. Use ``\DUrole``.
603 __ docs/user/latex.html#classes
605 - Most helper commands and element definitions are now defined in the
606 LaTeX package `docutils.sty`_ and only inserted in the document
607 preamble if the stylesheet__ setting does not lists "docutils".
609 __ docs/user/config.html#stylesheet-latex-writers
611 - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.
613 .. _setuptools: https://pypi.org/project/setuptools/
614 .. _pip: https://pypi.org/project/pip/
615 .. _docutils-cli.py: docs/user/tools.html#docutils-cli-py
616 .. _legacy_class_functions: docs/user/config.html#legacy-class-functions
617 .. _graphicx_option: docs/user/config.html#graphicx-option
618 .. _docutils.sty: https://ctan.org/pkg/docutils
621 Release 0.16 (2020-01-12)
622 =========================
624 Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
625 without the use of the ``2to3`` tool.
629 - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
630 escaping of author-separators in `bibliographic fields`__.
632 __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
633 __ docs/ref/rst/restructuredtext.html#bibliographic-fields
637 - Informal titles of type "rubric" default to bold-italic and left aligned.
638 - Deprecate ``\docutilsrole`` prefix for styling commands:
639 use ``\DUrole`` instead.
640 - Fix topic subtitle.
641 - Add "latex writers" to the `config_section_dependencies`.
642 - Ignore classes for `rubric` elements
643 (class wrapper interferes with LaTeX formatting).
647 - New option ``--html-writer`` allows to select "html" (default),
648 "html4" or "html5" (deprecated in favour of the `"writer" setting`_
653 - Remove the `handle_io_errors` argument from io.FileInput/Output.
657 - If `auto_id_prefix`_ ends with "%", this is replaced with the tag name.
659 * Various bugfixes and improvements (see HISTORY_).
661 .. _"writer" setting: docs/user/config.html#writer-buildhtml-application
662 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
665 Release 0.15 (2019-07-20)
666 =========================
668 Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5.
672 Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
676 - Allow embedded colons in field list field names (before, tokens like
677 ``:this:example:`` were considered ordinary text).
679 - Fixed a bug with the "trim" options of the "unicode" directive.
681 * languages: Added Korean localisation (ko).
684 Release 0.14 (2017-08-03)
685 =========================
689 Docutils 0.14.x is the last version supporting Python 2.4, 2.5,
692 * docutils/docs/ref/docutils.dtd:
694 - Enable validation of Docutils XML documents against the DTD:
696 * docutils/parsers/rst/:
698 - Added functionality: escaped whitespace in URI contexts.
699 - Consistent handling of all whitespace characters in inline markup
700 recognition. (May break documents that relied on some whitespace
701 characters (NBSP, ...) *not* to be recognized as whitespace.)
703 * docutils/utils/smartquotes.py:
705 - Update quote definitions for et, fi, fr, ro, sv, tr, uk.
706 - Add quote definitions for hr, hsb, hu, lv, sh, sl, sr.
707 - Differentiate apostrophe from closing single quote (if possible).
708 - Add command line interface for stand-alone use (requires 2.7).
710 * docutils/writers/_html_base:
712 - Provide default title in metadata.
713 - The MathJax CDN shut down on April 30, 2017. For security reasons, we
714 don't use a third party public installation as default but warn
715 if `math-output` is set to MathJax without specifying a URL.
716 See math-output_ for details.
718 * docutils/writers/html4css1:
720 - Respect automatic table column sizing.
722 * docutils/writers/latex2e/__init__.py
724 - Handle class arguments for block-level elements by wrapping them
725 in a "DUclass" environment. This replaces the special handling for
726 "epigraph" and "topic" elements.
728 * docutils/writers/odf_odt:
730 - Language option sets ODF document's default language
731 - Image width, scale, ... set image size in generated ODF.
735 - New front-end ``rst2html4.py``.
738 Release 0.13.1 (2016-12-09)
739 ===========================
741 * docutils/writers/html5_polyglot
743 - New HTML writer generating `HTML 5`_.
747 - New front-end ``rst2html5.py``.
749 * languages: persian/farsi (fa) and latvian (la) mappings.
751 * change default base url for :rfc: to http://tools.ietf.org/html/
753 * tables accept widths, a list and align
755 * latex2e: Fix admonition width, remove deprecated options,
756 better tablewidth auto, ...
758 * rst.el: The problem with ``electric-indent-mode`` has been fixed.
760 .. _HTML 5: https://www.w3.org/TR/html5/
763 Release 0.12 (2014-07-06)
764 =========================
766 Small changes only, release current state
769 Release 0.11 (2013-07-22)
770 =========================
774 - Apply [ 2714873 ] Fix for the overwriting of document attributes.
775 - Support embedded aliases within hyperlink references.
776 - Fix [ 228 ] try local import of docutils components (reader, writer, parser,
777 language module) before global search.
779 * docutils/parsers/rst/directives/tables.py
781 - Fix [ 210 ] Python 3.3 checks CVS syntax only if "strict" is True.
783 * docutils/writers/html4css1/__init__.py
784 - Fix [ 3600051 ] for tables in a list, table cells are not compacted.
785 - New setting `stylesheet_dirs` (see above).
787 Now, it is easy to add a custom stylesheet to Docutils' default
788 stylesheet with, e.g., ``--stylesheet_path='html4css1.css, mystyle.css'``
790 Changed behaviour of the default settings:
791 if there is a file ``html4css1.css`` in the working directory of the
792 process at launch, it is used instead of the one provided by Docutils
793 in the writer source directory.
795 - New default for math-output_: ``HTML math.css``.
796 - Avoid repeated class declarations in html4css1 writer
797 (modified version of patch [ 104 ]).
799 * docutils/writers/latex2e/__init__.py
801 - Drop the simple algorithm replacing straight double quotes with
802 English typographic ones.
803 Activate the SmartQuotes_ transform if you want this feature.
804 - New setting `stylesheet_dirs`: Comma-separated list of directories
805 where stylesheets are found. Used by `stylesheet_path` when expanding
806 relative path arguments.
808 * docutils/writers/manpage.py
810 - Fix [3607063] handle lines starting with a period.
811 - Fix option separating comma was bold (thanks to Bill Morris).
813 .. _math-output: docs/user/config.html#math-output
814 .. _SmartQuotes: docs/user/config.html#smart-quotes
817 Release 0.10 (2012-12-16)
818 =========================
820 Docutils 0.10 is compatible with Python versions from 2.4 to 3.2.
824 - SmartQuotes transform for typographic quotes and dashes.
826 - ``docutils/math``, ``docutils/error_reporting.py``, and
827 ``docutils/urischemes.py`` moved to the utils package.
828 Code importing these modules needs to adapt, e.g.::
831 import docutils.math as math
833 import docutils.utils.math as math
835 - enhanced math and error handling.
839 - FileInput/FileOutput: no system-exit on IOError.
840 The `handle_io_errors` argument is ignored.
842 * docutils/writers/html4css1/__init__.py
844 - Use ``<code>`` tag for inline "code",
845 do not drop nested inline nodes (syntax highlight tokens).
846 - Customizable MathJax URL (based on patch by Dmitry Shachnev).
847 - No line break after opening inline math tag.
849 * docutils/writers/latex2e/__init__.py, docutils/writers/xetex/__init__.py
851 - Fix section numbering by LaTeX.
853 * docutils/writers/s5_html/__init__.py
855 - Fix [ 3556388 ] Mathjax does not work with rst2s5.
858 Release 0.9.1 (2012-06-17)
859 ==========================
863 Docutils 0.9.1 is the last version supporting Python 2.3.
867 Several fixes for Python 3 usage.
871 - Fix [ 3527842 ]. Under Python 3, converted tests and tools were
872 installed in the PYTHONPATH. Converted tests are now
873 stored in ``docutils/test3/``, tools no longer need conversion.
875 If you installed one of Docutils versions 0.7 ... 0.9 with
876 ``setup.py install`` under Python 3, remove the spurious
877 ``test/`` and ``tools/`` directories in the site library root.
880 Release 0.9 (2012-05-02)
881 =========================
885 - reStructuredText "code" role and directive with syntax highlighting
887 - "code" option of the "include" directive.
889 .. _Pygments: https://pygments.org/
891 - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation
892 characters and "international" quotes around inline markup.
894 - Fix handling of missing stylesheets.
898 - Fix [ 2971827 ] and [ 3442827 ]
899 extras/roman.py moved to docutils/utils/roman.py
901 * docutils/utils.py -> docutils/utils/__init__.py
903 - docutils.utils is now a package (providing a place for sub-modules)
905 * docutils/writers/html4css1/__init__.py
907 - change default for `math-output` setting to MathJax
909 * docutils/writers/latex2e/__init__.py
911 - Support the `abbreviation` and `acronym` standard roles.
912 - Record only files required to generate the LaTeX source as dependencies.
913 - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions
914 when suppressing LaTeX section numbering.
917 Release 0.8.1 (2011-08-30)
918 ==========================
922 - Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause)
923 and [ 3395920 ] (correct copyright info for rst.el).
925 * docutils/writers/latex2e/__init__.py
927 - Clean up Babel language setting. Restores Sphinx compatibility.
930 Release 0.8 (2011-07-07)
931 ========================
935 - Some additions to the Docutils core are released under the 2-Clause BSD
940 - Handle language codes according to `BCP 47`_.
941 - If the specified language is not supported by Docutils,
942 warn and fall back to English.
943 - Math support: reStructuredText "math" role and directive,
944 ``math`` and ``math_block`` doctree elements.
945 - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox.
947 .. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
951 - most directives now support a "name" option that attaches a
952 reference name. So you can write ::
954 .. figure:: image.png
957 as a short form of ::
961 .. figure:: image.png
963 Internationalization:
965 * Added lithuanian mappings.
971 - New setting "math-output" with support for HTML, MathML, and LaTeX.
975 - Convert image URI to a local file path.
976 - Apply [ 3148141 ] fix multicolumn support when a colspanning cell
977 has more than one paragraph (Wolfgang Scherer).
981 - New writer generating LaTeX code for compiling with ``xelatex``.
983 XeTeX uses unicode and modern font technologies.
985 * and fixes and enhancements here and there.
988 Release 0.7 (2010-07-07)
989 ========================
995 - Support SVG and SWF images (thanks to Stefan Rank).
996 - Generate valid XHTML for centered images with targets.
997 Use CSS classes instead of "align" tags for image alignment.
1001 - Use the ``\url`` command for URLs (breaks long URLs instead of writing
1003 - Preserve runs of spaces in 'inline literals'.
1004 - Deprecate ``figure_footnotes`` setting.
1005 - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__.
1006 - New ``latex_preamble`` setting.
1007 - Use PDF standard fonts (Times/Helvetica/Courier) as default.
1008 - `hyperref` package called with ``unicode`` option (see the
1009 `hyperref config tips`__ for how to override).
1010 - Drop the special `output_encoding`__ default ("latin-1").
1011 The Docutils wide default (usually "UTF-8") is used instead.
1013 __ docs/user/config.html#docutils-footnotes
1014 __ docs/user/latex.html#hyperlinks
1015 __ docs/user/latex.html#output-encoding
1019 - Titles level 1, that is ``.SH``, always uppercase.
1020 - Apply patch from mg: literal text should be bold in man-pages.
1024 * io.FileInput opens files as text files with universal newline support
1025 (mode "rU", configurable with the new optional argument "mode").
1029 - Python 3 support: copy test/ and tools/ to the build-dir
1030 and convert Python sources with 2to3.
1033 Release 0.6 (2009-10-11)
1034 ========================
1036 Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6
1037 and convertible to 3.1 code.
1041 The "newlatex" writer is orphaned.
1043 The recommended way to generate PDF output is to use either the
1044 LaTeX2e writer or one of the alternatives listed at
1045 https://docutils.sourceforge.io/docs/user/links.html#pdf.
1049 - Allow length units for all length specifications.
1050 - Allow percent sign in "scale" argument of "figure" and "image" directives.
1051 - Bugfix: The "figalign" argument of a figure now works as intended
1052 (aligning the figure not its contents).
1053 - Align images with class "align-[right|center|left]"
1054 (allows setting the alignment of an image in a figure).
1055 - Hard tabs **in literal inclusions** are replaced by spaces.
1056 This is configurable via the new ``:tab-width:`` option of the
1057 `"include" directive`_ (a negative tab-width prevents tab expansion).
1061 - ``--stylesheet`` and ``--stylesheet-path`` options now support a comma
1062 separated list of stylesheets.
1067 - font-encoding: "T1" (formerly implicitly set by 'ae').
1068 - use-latex-toc: true (ToC with page numbers).
1069 - use-latex-footnotes: true (no mixup with figures).
1070 - Float placement defaults to "here definitely" (configurable).
1071 - Align of image in a figure defaults to 'center'.
1072 - Use class defaults for page margins ('typearea' now optional).
1073 - Support LaTeX packages as ``--stylesheet`` arguments.
1074 - Use ``bp`` for lengths without unit or unit ``pt``,
1075 do not convert ``px`` to ``pt``.
1076 - Do not use 'ae' and 'aeguill' packages if font-encoding is set to ''.
1077 - Set sub- and superscript role argument as text not math.
1078 - Support custom roles based on standard roles.
1079 - Load packages and define macros only if required in the document.
1080 - All Docutils specific LaTeX macros are prefixed with ``DU``.
1081 - Better conformance to Docutils specifications with "use_latex_toc".
1082 - If 'sectnum_xform' is False, the 'sectnum' directive triggers
1083 section numbering by LaTeX.
1084 - Use default font in admonitions and sidebar.
1085 - Typeset generic topic as "quote with title".
1086 - Use template (file and configuration option).
1087 - Render doctest blocks as literal blocks (indented).
1091 - moved from sandbox to Doctutils core.
1095 - moved from sandbox to Doctutils core.
1097 .. _"include" directive:
1098 docs/ref/rst/directives.html#including-an-external-document-fragment
1101 Release 0.5 (2008-06-25)
1102 ========================
1106 Docutils 0.5 is the last version supporting Python 2.2.
1112 - Dropped all ``name`` attributes of ``a`` elements (``id`` is
1113 universally supported now).
1117 - Better bibTeX citation support.
1118 - Add ``--literal-block-env``
1122 - Changed to support new python.org website structure and
1127 * Changed the directive API to a new object-oriented system.
1128 (Compatibility for the old, functional-style directive interface is
1129 retained.) See the updated `Creating reStructuredText Directives`__
1132 __ docs/howto/rst-directives.html
1134 * Allow ``+`` and ``:`` in reference names requested for citations.
1138 * Added `Deploying Docutils Securely`__
1140 __ docs/howto/security.txt
1142 Internationalization:
1144 * Added hebrew mappings.
1148 * Configuration files are now assumed and required to be
1151 * Added docutils/writers/html4css1/template.txt.
1153 * Enhance emacs support.
1156 Release 0.4 (2006-01-09)
1157 ========================
1161 Docutils 0.4 is the last version supporting Python 2.1.
1163 It is also the last version that will make compromises in
1164 its HTML output for Netscape Navigator 4. Docutils 0.5 will
1165 require more up-to-date browsers (the exact definition is to be
1170 * Added an `S5/HTML writer`__ and the rst2s5.py__ front end:
1171 multi-platform, multi-browser HTML slide shows.
1173 __ docs/user/slide-shows.html
1174 __ docs/user/tools.html#rst2s5
1176 * The newlatex2e writer is nearing completion.
1178 * Added a DocTree reader, ``publish_doctree`` and
1179 ``publish_from_doctree`` convenience functions, for document tree
1180 extraction and reprocessing.
1184 * Added directives: "container__" (generic block-level container),
1185 "default-role__" (role used for \`backtick\` syntax), "title__"
1186 (document title metadata), and "date__" (generate the current local
1187 date, for substitution definitions).
1189 __ docs/ref/rst/directives.html#container
1190 __ docs/ref/rst/directives.html#default-role
1191 __ docs/ref/rst/directives.html#title
1192 __ docs/ref/rst/directives.html#date
1194 * Length units are now supported for image_ sizes.
1196 .. _image: docs/ref/rst/directives.html#image
1198 * Added `standard definition files`__ for special characters etc.
1200 __ docs/ref/rst/definitions.html
1202 Internationalization:
1204 * Added Japanese and Simplified Chinese language mappings, and support
1205 for double-width CJK-characters in tables and section titles.
1209 * Added a `guide for distributors`__ (package maintainers) and a
1210 `guide for developers`__.
1212 __ docs/dev/distributing.html
1213 __ docs/dev/hacking.html
1217 * Added significant `Emacs support for reST`__.
1219 __ docs/user/emacs.html
1221 * Added a `--strip-comments`__ option.
1223 __ docs/user/config.html#strip-comments
1225 * `--embed-stylesheet`__ is now the default for the HTML writer
1226 (rather than --link-stylesheet).
1228 __ docs/user/config.html#embed-stylesheet
1231 Release 0.3.9 (2005-05-26)
1232 ==========================
1234 * Added "file_insertion_enabled__" and "raw_enabled__" settings.
1236 __ docs/user/config.html#file-insertion-enabled
1237 __ docs/user/config.html#raw-enabled
1239 * Added `auto-enumerated lists`__.
1241 __ docs/ref/rst/restructuredtext.html#enumerated-lists
1243 * Added `"header" and "footer"`__ directives.
1245 __ docs/ref/rst/directives.html#document-header-footer
1247 * Added "list-table__" directive.
1249 __ docs/ref/rst/directives.html#list-table
1251 * Added support for `section subtitles`__.
1253 __ docs/user/config.html#sectsubtitle-xform
1255 * Added "field_name_limit__" and "option_limit__" settings to HTML writer.
1257 __ docs/user/config.html#field-name-limit
1258 __ docs/user/config.html#option-limit
1260 * Added "cloak_email_addresses__" setting to HTML writer.
1262 __ docs/user/config.html#cloak-email-addresses
1264 * UTF-8 BOMs are now removed from the input stream.
1267 Release 0.3.7 (2004-12-24)
1268 ==========================
1270 * A special "`line block`__" syntax has been added. (Also see the
1271 `quick reference`__.)
1273 __ docs/ref/rst/restructuredtext.html#line-blocks
1274 __ docs/user/rst/quickref.html#line-blocks
1276 * Empty sections are now allowed.
1278 * A "raw__" role has been added.
1280 __ docs/ref/rst/roles.html#raw
1282 * The LaTeX writer now escapes consecutive dashes (like "--" or "---")
1283 so that they are no longer transformed by LaTeX to en or em dashes.
1284 (Please see the FAQ__ for how to represent such dashes.)
1286 __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document
1288 * A `dependency recorder`__ has been added.
1290 __ docs/user/config.html#record-dependencies
1292 * A directive has been added for `compound paragraphs`__.
1294 __ docs/ref/rst/directives.html#compound-paragraph
1297 Release 0.3.5 (2004-07-29)
1298 ==========================
1300 * Improved, extended and reorganized the documentation__.
1304 * Added "csv-table__" directive.
1306 __ docs/ref/rst/directives.html#csv-table
1308 .. _HISTORY: HISTORY.html
1309 .. _Python 3 compatibility: README.html#python-3-compatibility