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/
52 * Change the default input encoding from ``None`` (auto-detect) to
53 "utf-8" in Docutils 0.22.
55 * Remove the input encoding auto-detection code in Docutils 1.0 or later.
60 * The `default HTML writer`__ will change in Docutils 2.0:
62 The rst2html_ front end and ``get_writer_by_name('html')`` select
63 "html4css1" now and will select "html5" in Docutils 2.0 and later.
65 - Use rst2html4_, ``docutils --writer=html4``, or
66 ``get_writer_by_name('html4')`` if you depend on stability of the
67 generated HTML code, e.g. because you use a custom style sheet or
68 post-processing that may break otherwise.
69 - Use rst2html5_, ``docutils`` or ``get_writer_by_name('html5')``
70 if you want a HTML5 document.
72 __ docs/user/html.html#html
76 - Move attribution behind the blockquote to comply with the `"living
77 standard"`__. (HTML5__ allows <cite> elements inside a blockquote.)
79 __ https://html.spec.whatwg.org/#the-blockquote-element
80 __ https://www.w3.org/TR/2014/REC-html5-20141028/grouping-content.html
81 #the-blockquote-element
83 - Change the default value for math_output_ to "MathML"
86 - Change the default value of the initial_header_level_ setting to None
87 (<h2> if there is a document title, else <h1>) in Docutils 1.0.
89 - Remove option ``--embed-images`` (obsoleted by "image_loading_")
94 - Change default of use_latex_citations_ setting to True
97 - Change default of legacy_column_widths_ setting to False
100 - Remove ``use_verbatim_when_possible`` setting
101 (use literal_block_env_: verbatim) in Docutils 2.0.
103 - Don't wrap references with custom reference-label_ in
104 a ``\hyperref`` command in Docutils 0.22.
105 Specify, e.g., "ref" instead of "ref*" to keep generating hyperlinks.
107 .. _reference-label: docs/user/config.html#reference-label
109 * "null" writer: output will change to the empty string
117 Allow multiple <term> elements in a <definition_list_item>
118 in Docutils 0.22 (cf. `feature-requests:60`__).
119 Third-party writers may need adaption.
121 __ https://sourceforge.net/p/docutils/feature-requests/60/
123 * Remove `parsers.rst.directives.CSVTable.HeaderDialect`
126 * Remove the "rawsource" argument from `nodes.Text.__init__()`
129 * Drop support for `old-format configuration files`_ in Docutils 2.0.
131 * Remove the ``--html-writer`` option of the `buildhtml.py`_ application
132 (obsoleted by the `"writer" setting`_ since Docutils 0.18)
135 * Revise the `String I/O`__ interface used by the `publish_string()`
136 and `publish_from_doctree()` publisher convenience functions.
137 (In Python 3, name and behaviour no longer match.)
139 __ docs/api/publisher.html#string-i-o
141 * Move math format conversion from docutils/utils/math (called from
142 docutils/writers/_html_base.py) to a transform__.
144 __ docs/ref/transforms.html
146 * Remove mistranslated localizations of the "admonition" directive name in
149 Use the English term, matching translations introduced in Docutils 0.21,
150 or specific admonitions instead of "aanmaning" (nl),
151 "admonition" (fr), "ammonizione" (it), "ermahnung" (de),
152 "exhortación" (es), "formaning" (da), "sciigo" (eo),
153 "upomnienie" (pl), "vermaning" (af),
154 to avoid errors in future conversions.
156 .. _front end tools: docs/user/tools.html
157 .. _input_encoding: docs/user/config.html#input-encoding
158 .. _math_output: docs/user/config.html#math-output
159 .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
160 .. _image_loading: docs/user/config.html#image-loading
161 .. _old-format configuration files:
162 docs/user/config.html#old-format-configuration-files
164 .. _rst2html: docs/user/tools.html#rst2html
165 .. _rst2html4: docs/user/tools.html#rst2html4
166 .. _rst2html5: docs/user/tools.html#rst2html5
167 .. _reference name: docs/ref/rst/restructuredtext.html#reference-names
168 .. _literal_block_env: docs/user/config.html#literal-block-env
169 .. _use_latex_citations: docs/user/config.html#use-latex-citations
170 .. _buildhtml.py: docs/user/tools.html#buildhtml-py
173 Release 0.21.rc1 (unpublished)
174 ==============================
178 - Drop support for Python 3.7 and 3.8.
180 - Provide ``rst2*`` "console_scripts" `entry points`_
181 (without the ``.py`` extension) instead of installing the
182 ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
184 Exceptions: ``rstpep2html.py`` and ``rst2odt_prepstyles.py``:
186 - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
187 - Use ``python -m docutils.writers.odf_odt.prepstyles``
188 to `strip the page size`__ from an ODT writer stylesheet.
190 __ docs/user/odt.html#page-size
192 .. [#] Some Linux distributions already use the short names.
193 .. [#] The final rendering is done by a Sphinx-based build system
198 - Use the same CSV format for the ``:header:`` option and the main data
199 of the "csv-table_" directive.
201 - New option "loading" for the `"image" directive`_.
202 Sets the new attribute loading__ of the <image> doctree element.
204 __ docs/ref/doctree.html#loading
206 * Configuration changes:
208 - New configuration setting root_prefix_.
209 Configurable root directory for included files.
211 - New configuration setting sources_ for the "buildhtml.py" application.
213 - Simpler and more secure `input encoding`_ default behaviour:
215 Do not use the locale encoding as fallback if Python is started in
216 `UTF-8 mode`_. Stop using "latin1" as second fallback.
218 Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
219 configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
220 Do not remove other ZWNBSPs.
225 Stop setting the "footnote-reference" class value for footnote
226 references. Use the CSS selector ``[role="doc-noteref"]``
227 (works since Docutils 0.18, see minimal.css for examples).
229 Fix MathML rendering problems in Chrome/Chromium based browsers.
231 Embed SVG images as ``<svg>`` instead of data-URI.
235 `docutils.nodes.reprunicode`, `docutils.nodes.ensure_str()`
236 Python 2 compatibility hacks
237 `docutils.utils.Reporter.set_conditions()`
239 `docutils.core.Publisher.setup_option_parser()`
244 ``docutils/writers/html5_polyglot/italic-field-names.css``
245 Alternative style for Docutils field-lists.
249 ``install.py``, ``setup.py``
250 Metadata is now stored in ``pyproject.toml``,
251 supported by pip_ since version 19.0 (2019-01-22).
252 See README__ for installation alternatives.
254 __ README.html#installation
256 * Bugfixes and improvements (see HISTORY_).
258 .. _input encoding: docs/api/publisher.html#encodings
259 .. _csv-table: docs/ref/rst/directives.html#csv-table
260 .. _"image" directive: docs/ref/rst/directives.html#image
261 .. _root_prefix: docs/user/config.html#root-prefix
262 .. _sources: docs/user/config.html#sources
265 Release 0.20.1 (2023-05-17)
266 ===========================
268 Bugfix release. See HISTORY_ for details.
271 Release 0.20 (2023-05-04)
272 =========================
276 Docutils 0.20 is the last version supporting Python 3.7 and 3.8.
280 - Support Python 3.11 (patch #198 by Hugo van Kemenade).
285 Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note")
289 Do not load the `inputenc` package in UTF-8 encoded LaTeX sources.
290 (UTF-8 is the default encoding for LaTeX2e since 2018).
292 * Configuration changes:
294 - Settings in the [latex2e writer] configuration file section
295 are now ignored by the "xetex" writer.
296 Place common settings in section `[latex writers]`_.
298 - New command line setting output_. Obsoletes the ``<destination>``
299 positional argument (cf. `future changes`__).
301 __ `command-line usage pattern`_
303 * `utils.find_file_in_dirs()` now returns a POSIX path also on Windows;
304 `utils.get_stylesheet_list()` no longer converts ``\`` to ``/``.
306 * docutils/languages/
307 docutils/parsers/rst/languages/
309 - Support Ukrainian. Patch by Dmytro Kazanzhy.
313 - Removed. Use the coverage.py_ project instead,
314 ``coverage run test/alltests.py`` and ``coverage report``.
318 - Moved ``quicktest.py`` to ``tools/dev/``.
320 * Bugfixes and improvements (see HISTORY_).
322 .. _[latex writers]: docs/user/config.html#latex-writers
323 .. _output: docs/user/config.html#output
324 .. _coverage.py: https://pypi.org/project/coverage/
327 Release 0.19 (2022-07-05)
328 =========================
330 (Release 0.19b1 (2022-06-21))
332 * Drop support for Python 2.7, 3.5, and 3.6.
337 Wrap groups of footnotes in an ``<aside>`` for easier styling.
339 The CSS rule ``.footnote-list { display: contents; }`` can be used to
340 restore the behaviour of custom CSS styles.
342 * After package installation, the CLI commands ``python -m docutils`` and
343 ``docutils`` start the `generic command line front end tool`_.
345 * Support parsing "Markdown" input with 3rd party parsers
346 myst_, pycmark_, or recommonmark_.
348 * The default values for the "pep-references", "rfc-base-url",
349 and "python-home" `configuration settings`_ now use the "https:" scheme.
350 The PEP-writer template's header is updated to fix links and
351 resemble the header of official PEPs.
353 * Various bugfixes and improvements (see HISTORY_).
355 .. _generic command line front end tool:
356 docs/user/tools.html#generic-command-line-front-end
357 .. _myst: https://pypi.org/project/myst-docutils
358 .. _pycmark: https://pypi.org/project/pycmark/
359 .. _recommonmark: https://pypi.org/project/recommonmark/
360 .. _configuration settings: docs/user/config.html
363 Release 0.18.1 (2021-12-23)
364 ===========================
368 Docutils 0.18.1 is the last version supporting Python 2.7, 3.5, and 3.6.
370 * ``nodes.Node.traverse()`` returns a list again to restore backwards
371 compatibility (fixes bug #431).
372 Use ``nodes.Node.findall()`` to get an iterator.
374 * re-add module ``parsers.rst.directives.html``
375 (stub, emits deprecation warning and loads
376 "Meta" directive from its new place at ``parsers.rst.directives.misc``.)
378 * Small bugfixes (see HISTORY_).
381 Release 0.18 (2021-10-26)
382 =========================
387 - During `identifier normalization`_, leading number and hyphen
388 characters are no longer stripped from a `reference name`_, if the
389 id_prefix_ setting is non-empty.
392 with ``--id-prefix="DU-"``, a section with title "34. May"
393 currently gets the identifier key ``DU-may`` and after the
394 change the identifier key ``DU-34-may``.
396 - The default value for the auto_id_prefix_ setting changed to ``%``:
397 "use the tag name as prefix for auto-generated IDs".
398 Set auto_id_prefix_ to ``id`` for unchanged auto-IDs.
401 - Use the semantic tag <aside> for footnote text and citations, topics
402 (except abstract and toc), admonitions, and system messages.
403 Use <nav> for the Table of Contents.
405 - Make "auto" table column widths the default: Only specify column
406 widths, if the `"widths" option`_ is set and not "auto".
407 The table-style__ setting "colwidths-grid" restores the current default.
409 __ docs/user/config.html#table-style
411 - Items of a definition list with class argument "details" are
412 converted to `details disclosure elements`_. Example::
417 This additional information should be hidden.
419 - Do not add "compound-first", "compound-middle", or "compound-last" to
420 elements nested in a compound. Use child selector and ":first-child",
421 ":last-child" pseudo classes instead.
423 - Use class value "backrefs" instead of "fn-backref" for a span of
426 - Write footnote brackets and field term colons to HTML, so that they
427 are present also without CSS and when copying text.
429 - Move space character between section number and heading into
433 - Support more commands, fix mapping of commands to Unicode characters.
434 - Scale variable sized operators and big delimiters with CSS.
435 - Don't use <tt> element (deprecated in HTML5).
436 - Use STIX fonts if available.
439 `legacy_class_functions`_ setting default changed to "False",
440 admonitions are now environments.
442 * New standard Docutils doctree node: <meta__>.
444 __ docs/ref/doctree.html#meta
446 * New configuration settings:
448 - [latex writers] legacy_column_widths_ and
449 - [html5 writer] image_loading_.
452 ``iepngfix.htc`` and ``blank.gif`` (IE 6 workaround for `s5_html`).
454 * Removed sub-module:
455 ``parsers.rst.directives.html``
456 (reversed in release 0.18.1).
458 * Removed function: utils.unique_combinations()
459 (obsoleted by itertools.combinations()).
461 * Removed attributes:
463 - ``HTMLTranslator.topic_classes``: check ``node.parent.classes`` instead.
464 - ``nodes.Text.rawsource``: we store the null-escaped text in Text
465 nodes since 0.16 so there is no additional information in the
468 * Major refactoring and fixes/additions in
469 ``docutils/utils/math/math2html.py`` and
470 ``docutils/utils/math/latex2mathml.py``
471 (mathematical notation in HTML, cf. `LaTeX syntax for mathematics`_).
473 * nodes.Node.traverse() returns an iterator instead of a list
474 (reversed in release 0.18.1).
476 * Various bugfixes and improvements (see HISTORY_).
478 Fix spelling errors in documentation and docstrings.
479 Thanks to Dimitri Papadopoulos.
481 .. _"widths" option: __ docs/ref/rst/directives.html#table
482 .. _identifier normalization:
483 docs/ref/rst/directives.html#identifier-normalization
484 .. _id_prefix: docs/user/config.html#id-prefix
485 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
486 .. _details disclosure elements:
487 https://www.w3.org/TR/html52/interactive-elements.html#the-details-element
488 .. _LaTeX syntax for mathematics: docs/ref/rst/mathematics.html
489 .. _legacy_column_widths: docs/user/config.html#legacy-column-widths
492 Release 0.17.1 (2021-04-16)
493 ===========================
495 * Bug fixes (for details see the Docutils `HISTORY`_).
497 Release 0.17 (2021-04-03)
498 =========================
500 * Numerous bug fixes and improvements
501 (for details see the Docutils `HISTORY`_).
503 * Installing with ``setup.py`` now requires setuptools_.
504 Alternatively, install with pip_.
506 * The generic command line front end tool docutils-cli.py_ allows
507 the free selection of reader, parser, and writer components.
509 * Support Arabic language.
511 * New, **experimental** wrapper to integrate the `recommonmark`__
512 Markdown parser for use with Docutils.
513 Currently only tested with recommonmark version 0.4.0.
515 __ https://pypi.org/project/recommonmark/
519 - New option embed_images_.
521 - Use semantic tags (for details see the Docutils `HISTORY`_).
523 - Change the `initial_header_level`_ setting's default to "2", as browsers
524 use the `same style for <h1> and <h2> when nested in a section`__.
526 - New optional style ``responsive.css``, adapts to different screen
529 - Move non-essential styling from ``minimal.css`` to ``plain.css``
530 rsp. ``responsive.css``.
532 - Show code line numbers as pseudo-elements so they are skipped when
533 copying the code block from the page.
535 .. _initial_header_level: docs/user/config.html#initial-header-level
536 __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
537 .. _embed_images: docs/user/config.html#embed-images
541 - New configuration setting `legacy_class_functions`_.
543 - The special value "auto" for the `graphicx_option`_ setting
544 is no longer supported (it never worked for xetex/luatex).
546 - `Styling commands`__ using the legacy ``\docutilsrole`` prefix are
547 now ignored. Use ``\DUrole``.
549 __ docs/user/latex.html#classes
551 - Most helper commands and element definitions are now defined in the
552 LaTeX package `docutils.sty`_ and only inserted in the document
553 preamble if the stylesheet__ setting does not lists "docutils".
555 __ docs/user/config.html#stylesheet-latex-writers
557 - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.
559 .. _setuptools: https://pypi.org/project/setuptools/
560 .. _pip: https://pypi.org/project/pip/
561 .. _docutils-cli.py: docs/user/tools.html#docutils-cli-py
562 .. _legacy_class_functions: docs/user/config.html#legacy-class-functions
563 .. _graphicx_option: docs/user/config.html#graphicx-option
564 .. _docutils.sty: https://ctan.org/pkg/docutils
567 Release 0.16 (2020-01-12)
568 =========================
570 Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
571 without the use of the ``2to3`` tool.
575 - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
576 escaping of author-separators in `bibliographic fields`__.
578 __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
579 __ docs/ref/rst/restructuredtext.html#bibliographic-fields
583 - Informal titles of type "rubric" default to bold-italic and left aligned.
584 - Deprecate ``\docutilsrole`` prefix for styling commands:
585 use ``\DUrole`` instead.
586 - Fix topic subtitle.
587 - Add "latex writers" to the `config_section_dependencies`.
588 - Ignore classes for `rubric` elements
589 (class wrapper interferes with LaTeX formatting).
593 - New option ``--html-writer`` allows to select "html" (default),
594 "html4" or "html5" (deprecated in favour of the `"writer" setting`_
599 - Remove the `handle_io_errors` argument from io.FileInput/Output.
603 - If `auto_id_prefix`_ ends with "%", this is replaced with the tag name.
605 * Various bugfixes and improvements (see HISTORY_).
607 .. _"writer" setting: docs/user/config.html#writer-buildhtml-application
608 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
611 Release 0.15 (2019-07-20)
612 =========================
614 Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5.
618 Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
622 - Allow embedded colons in field list field names (before, tokens like
623 ``:this:example:`` were considered ordinary text).
625 - Fixed a bug with the "trim" options of the "unicode" directive.
627 * languages: Added Korean localisation (ko).
630 Release 0.14 (2017-08-03)
631 =========================
635 Docutils 0.14.x is the last version supporting Python 2.4, 2.5,
638 * docutils/docs/ref/docutils.dtd:
640 - Enable validation of Docutils XML documents against the DTD:
642 * docutils/parsers/rst/:
644 - Added functionality: escaped whitespace in URI contexts.
645 - Consistent handling of all whitespace characters in inline markup
646 recognition. (May break documents that relied on some whitespace
647 characters (NBSP, ...) *not* to be recognized as whitespace.)
649 * docutils/utils/smartquotes.py:
651 - Update quote definitions for et, fi, fr, ro, sv, tr, uk.
652 - Add quote definitions for hr, hsb, hu, lv, sh, sl, sr.
653 - Differentiate apostrophe from closing single quote (if possible).
654 - Add command line interface for stand-alone use (requires 2.7).
656 * docutils/writers/_html_base:
658 - Provide default title in metadata.
659 - The MathJax CDN shut down on April 30, 2017. For security reasons, we
660 don't use a third party public installation as default but warn
661 if `math-output` is set to MathJax without specifying a URL.
662 See math-output_ for details.
664 * docutils/writers/html4css1:
666 - Respect automatic table column sizing.
668 * docutils/writers/latex2e/__init__.py
670 - Handle class arguments for block-level elements by wrapping them
671 in a "DUclass" environment. This replaces the special handling for
672 "epigraph" and "topic" elements.
674 * docutils/writers/odf_odt:
676 - Language option sets ODF document's default language
677 - Image width, scale, ... set image size in generated ODF.
681 - New front-end ``rst2html4.py``.
684 Release 0.13.1 (2016-12-09)
685 ===========================
687 * docutils/writers/html5_polyglot
689 - New HTML writer generating `HTML 5`_.
693 - New front-end ``rst2html5.py``.
695 * languages: persian/farsi (fa) and latvian (la) mappings.
697 * change default base url for :rfc: to http://tools.ietf.org/html/
699 * tables accept widths, a list and align
701 * latex2e: Fix admonition width, remove deprecated options,
702 better tablewidth auto, ...
704 * rst.el: The problem with ``electric-indent-mode`` has been fixed.
706 .. _HTML 5: https://www.w3.org/TR/html5/
709 Release 0.12 (2014-07-06)
710 =========================
712 Small changes only, release current state
715 Release 0.11 (2013-07-22)
716 =========================
720 - Apply [ 2714873 ] Fix for the overwriting of document attributes.
721 - Support embedded aliases within hyperlink references.
722 - Fix [ 228 ] try local import of docutils components (reader, writer, parser,
723 language module) before global search.
725 * docutils/parsers/rst/directives/tables.py
727 - Fix [ 210 ] Python 3.3 checks CVS syntax only if "strict" is True.
729 * docutils/writers/html4css1/__init__.py
730 - Fix [ 3600051 ] for tables in a list, table cells are not compacted.
731 - New setting `stylesheet_dirs` (see above).
733 Now, it is easy to add a custom stylesheet to Docutils' default
734 stylesheet with, e.g., ``--stylesheet_path='html4css1.css, mystyle.css'``
736 Changed behaviour of the default settings:
737 if there is a file ``html4css1.css`` in the working directory of the
738 process at launch, it is used instead of the one provided by Docutils
739 in the writer source directory.
741 - New default for math-output_: ``HTML math.css``.
742 - Avoid repeated class declarations in html4css1 writer
743 (modified version of patch [ 104 ]).
745 * docutils/writers/latex2e/__init__.py
747 - Drop the simple algorithm replacing straight double quotes with
748 English typographic ones.
749 Activate the SmartQuotes_ transform if you want this feature.
750 - New setting `stylesheet_dirs`: Comma-separated list of directories
751 where stylesheets are found. Used by `stylesheet_path` when expanding
752 relative path arguments.
754 * docutils/writers/manpage.py
756 - Fix [3607063] handle lines starting with a period.
757 - Fix option separating comma was bold (thanks to Bill Morris).
759 .. _math-output: docs/user/config.html#math-output
760 .. _SmartQuotes: docs/user/config.html#smart-quotes
763 Release 0.10 (2012-12-16)
764 =========================
766 Docutils 0.10 is compatible with Python versions from 2.4 to 3.2.
770 - SmartQuotes transform for typographic quotes and dashes.
772 - ``docutils/math``, ``docutils/error_reporting.py``, and
773 ``docutils/urischemes.py`` moved to the utils package.
774 Code importing these modules needs to adapt, e.g.::
777 import docutils.math as math
779 import docutils.utils.math as math
781 - enhanced math and error handling.
785 - FileInput/FileOutput: no system-exit on IOError.
786 The `handle_io_errors` argument is ignored.
788 * docutils/writers/html4css1/__init__.py
790 - Use ``<code>`` tag for inline "code",
791 do not drop nested inline nodes (syntax highlight tokens).
792 - Customizable MathJax URL (based on patch by Dmitry Shachnev).
793 - No line break after opening inline math tag.
795 * docutils/writers/latex2e/__init__.py, docutils/writers/xetex/__init__.py
797 - Fix section numbering by LaTeX.
799 * docutils/writers/s5_html/__init__.py
801 - Fix [ 3556388 ] Mathjax does not work with rst2s5.
804 Release 0.9.1 (2012-06-17)
805 ==========================
809 Docutils 0.9.1 is the last version supporting Python 2.3.
813 Several fixes for Python 3 usage.
817 - Fix [ 3527842 ]. Under Python 3, converted tests and tools were
818 installed in the PYTHONPATH. Converted tests are now
819 stored in ``docutils/test3/``, tools no longer need conversion.
821 If you installed one of Docutils versions 0.7 ... 0.9 with
822 ``setup.py install`` under Python 3, remove the spurious
823 ``test/`` and ``tools/`` directories in the site library root.
826 Release 0.9 (2012-05-02)
827 =========================
831 - reStructuredText "code" role and directive with syntax highlighting
833 - "code" option of the "include" directive.
835 .. _Pygments: https://pygments.org/
837 - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation
838 characters and "international" quotes around inline markup.
840 - Fix handling of missing stylesheets.
844 - Fix [ 2971827 ] and [ 3442827 ]
845 extras/roman.py moved to docutils/utils/roman.py
847 * docutils/utils.py -> docutils/utils/__init__.py
849 - docutils.utils is now a package (providing a place for sub-modules)
851 * docutils/writers/html4css1/__init__.py
853 - change default for `math-output` setting to MathJax
855 * docutils/writers/latex2e/__init__.py
857 - Support the `abbreviation` and `acronym` standard roles.
858 - Record only files required to generate the LaTeX source as dependencies.
859 - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions
860 when suppressing LaTeX section numbering.
863 Release 0.8.1 (2011-08-30)
864 ==========================
868 - Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause)
869 and [ 3395920 ] (correct copyright info for rst.el).
871 * docutils/writers/latex2e/__init__.py
873 - Clean up Babel language setting. Restores Sphinx compatibility.
876 Release 0.8 (2011-07-07)
877 ========================
881 - Some additions to the Docutils core are released under the 2-Clause BSD
886 - Handle language codes according to `BCP 47`_.
887 - If the specified language is not supported by Docutils,
888 warn and fall back to English.
889 - Math support: reStructuredText "math" role and directive,
890 ``math`` and ``math_block`` doctree elements.
891 - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox.
893 .. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
897 - most directives now support a "name" option that attaches a
898 reference name. So you can write ::
900 .. figure:: image.png
903 as a short form of ::
907 .. figure:: image.png
909 Internationalization:
911 * Added lithuanian mappings.
917 - New setting "math-output" with support for HTML, MathML, and LaTeX.
921 - Convert image URI to a local file path.
922 - Apply [ 3148141 ] fix multicolumn support when a colspanning cell
923 has more than one paragraph (Wolfgang Scherer).
927 - New writer generating LaTeX code for compiling with ``xelatex``.
929 XeTeX uses unicode and modern font technologies.
931 * and fixes and enhancements here and there.
934 Release 0.7 (2010-07-07)
935 ========================
941 - Support SVG and SWF images (thanks to Stefan Rank).
942 - Generate valid XHTML for centered images with targets.
943 Use CSS classes instead of "align" tags for image alignment.
947 - Use the ``\url`` command for URLs (breaks long URLs instead of writing
949 - Preserve runs of spaces in 'inline literals'.
950 - Deprecate ``figure_footnotes`` setting.
951 - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__.
952 - New ``latex_preamble`` setting.
953 - Use PDF standard fonts (Times/Helvetica/Courier) as default.
954 - `hyperref` package called with ``unicode`` option (see the
955 `hyperref config tips`__ for how to override).
956 - Drop the special `output_encoding`__ default ("latin-1").
957 The Docutils wide default (usually "UTF-8") is used instead.
959 __ docs/user/config.html#docutils-footnotes
960 __ docs/user/latex.html#hyperlinks
961 __ docs/user/latex.html#output-encoding
965 - Titles level 1, that is ``.SH``, always uppercase.
966 - Apply patch from mg: literal text should be bold in man-pages.
970 * io.FileInput opens files as text files with universal newline support
971 (mode "rU", configurable with the new optional argument "mode").
975 - Python 3 support: copy test/ and tools/ to the build-dir
976 and convert Python sources with 2to3.
979 Release 0.6 (2009-10-11)
980 ========================
982 Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6
983 and convertible to 3.1 code.
987 The "newlatex" writer is orphaned.
989 The recommended way to generate PDF output is to use either the
990 LaTeX2e writer or one of the alternatives listed at
991 https://docutils.sourceforge.io/docs/user/links.html#pdf.
995 - Allow length units for all length specifications.
996 - Allow percent sign in "scale" argument of "figure" and "image" directives.
997 - Bugfix: The "figalign" argument of a figure now works as intended
998 (aligning the figure not its contents).
999 - Align images with class "align-[right|center|left]"
1000 (allows setting the alignment of an image in a figure).
1001 - Hard tabs **in literal inclusions** are replaced by spaces.
1002 This is configurable via the new ``:tab-width:`` option of the
1003 `"include" directive`_ (a negative tab-width prevents tab expansion).
1007 - ``--stylesheet`` and ``--stylesheet-path`` options now support a comma
1008 separated list of stylesheets.
1013 - font-encoding: "T1" (formerly implicitly set by 'ae').
1014 - use-latex-toc: true (ToC with page numbers).
1015 - use-latex-footnotes: true (no mixup with figures).
1016 - Float placement defaults to "here definitely" (configurable).
1017 - Align of image in a figure defaults to 'center'.
1018 - Use class defaults for page margins ('typearea' now optional).
1019 - Support LaTeX packages as ``--stylesheet`` arguments.
1020 - Use ``bp`` for lengths without unit or unit ``pt``,
1021 do not convert ``px`` to ``pt``.
1022 - Do not use 'ae' and 'aeguill' packages if font-encoding is set to ''.
1023 - Set sub- and superscript role argument as text not math.
1024 - Support custom roles based on standard roles.
1025 - Load packages and define macros only if required in the document.
1026 - All Docutils specific LaTeX macros are prefixed with ``DU``.
1027 - Better conformance to Docutils specifications with "use_latex_toc".
1028 - If 'sectnum_xform' is False, the 'sectnum' directive triggers
1029 section numbering by LaTeX.
1030 - Use default font in admonitions and sidebar.
1031 - Typeset generic topic as "quote with title".
1032 - Use template (file and configuration option).
1033 - Render doctest blocks as literal blocks (indented).
1037 - moved from sandbox to Doctutils core.
1041 - moved from sandbox to Doctutils core.
1043 .. _"include" directive:
1044 docs/ref/rst/directives.html#including-an-external-document-fragment
1047 Release 0.5 (2008-06-25)
1048 ========================
1052 Docutils 0.5 is the last version supporting Python 2.2.
1058 - Dropped all ``name`` attributes of ``a`` elements (``id`` is
1059 universally supported now).
1063 - Better bibTeX citation support.
1064 - Add ``--literal-block-env``
1068 - Changed to support new python.org website structure and
1073 * Changed the directive API to a new object-oriented system.
1074 (Compatibility for the old, functional-style directive interface is
1075 retained.) See the updated `Creating reStructuredText Directives`__
1078 __ docs/howto/rst-directives.html
1080 * Allow ``+`` and ``:`` in reference names requested for citations.
1084 * Added `Deploying Docutils Securely`__
1086 __ docs/howto/security.txt
1088 Internationalization:
1090 * Added hebrew mappings.
1094 * Configuration files are now assumed and required to be
1097 * Added docutils/writers/html4css1/template.txt.
1099 * Enhance emacs support.
1102 Release 0.4 (2006-01-09)
1103 ========================
1107 Docutils 0.4 is the last version supporting Python 2.1.
1109 It is also the last version that will make compromises in
1110 its HTML output for Netscape Navigator 4. Docutils 0.5 will
1111 require more up-to-date browsers (the exact definition is to be
1116 * Added an `S5/HTML writer`__ and the rst2s5.py__ front end:
1117 multi-platform, multi-browser HTML slide shows.
1119 __ docs/user/slide-shows.html
1120 __ docs/user/tools.html#rst2s5
1122 * The newlatex2e writer is nearing completion.
1124 * Added a DocTree reader, ``publish_doctree`` and
1125 ``publish_from_doctree`` convenience functions, for document tree
1126 extraction and reprocessing.
1130 * Added directives: "container__" (generic block-level container),
1131 "default-role__" (role used for \`backtick\` syntax), "title__"
1132 (document title metadata), and "date__" (generate the current local
1133 date, for substitution definitions).
1135 __ docs/ref/rst/directives.html#container
1136 __ docs/ref/rst/directives.html#default-role
1137 __ docs/ref/rst/directives.html#title
1138 __ docs/ref/rst/directives.html#date
1140 * Length units are now supported for image__ sizes.
1142 __ docs/ref/rst/directives.html#image
1144 * Added `standard definition files`__ for special characters etc.
1146 __ docs/ref/rst/definitions.html
1148 Internationalization:
1150 * Added Japanese and Simplified Chinese language mappings, and support
1151 for double-width CJK-characters in tables and section titles.
1155 * Added a `guide for distributors`__ (package maintainers) and a
1156 `guide for developers`__.
1158 __ docs/dev/distributing.html
1159 __ docs/dev/hacking.html
1163 * Added significant `Emacs support for reST`__.
1165 __ docs/user/emacs.html
1167 * Added a `--strip-comments`__ option.
1169 __ docs/user/config.html#strip-comments
1171 * `--embed-stylesheet`__ is now the default for the HTML writer
1172 (rather than --link-stylesheet).
1174 __ docs/user/config.html#embed-stylesheet
1177 Release 0.3.9 (2005-05-26)
1178 ==========================
1180 * Added "file_insertion_enabled__" and "raw_enabled__" settings.
1182 __ docs/user/config.html#file-insertion-enabled
1183 __ docs/user/config.html#raw-enabled
1185 * Added `auto-enumerated lists`__.
1187 __ docs/ref/rst/restructuredtext.html#enumerated-lists
1189 * Added `"header" and "footer"`__ directives.
1191 __ docs/ref/rst/directives.html#document-header-footer
1193 * Added "list-table__" directive.
1195 __ docs/ref/rst/directives.html#list-table
1197 * Added support for `section subtitles`__.
1199 __ docs/user/config.html#sectsubtitle-xform
1201 * Added "field_name_limit__" and "option_limit__" settings to HTML writer.
1203 __ docs/user/config.html#field-name-limit
1204 __ docs/user/config.html#option-limit
1206 * Added "cloak_email_addresses__" setting to HTML writer.
1208 __ docs/user/config.html#cloak-email-addresses
1210 * UTF-8 BOMs are now removed from the input stream.
1213 Release 0.3.7 (2004-12-24)
1214 ==========================
1216 * A special "`line block`__" syntax has been added. (Also see the
1217 `quick reference`__.)
1219 __ docs/ref/rst/restructuredtext.html#line-blocks
1220 __ docs/user/rst/quickref.html#line-blocks
1222 * Empty sections are now allowed.
1224 * A "raw__" role has been added.
1226 __ docs/ref/rst/roles.html#raw
1228 * The LaTeX writer now escapes consecutive dashes (like "--" or "---")
1229 so that they are no longer transformed by LaTeX to en or em dashes.
1230 (Please see the FAQ__ for how to represent such dashes.)
1232 __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document
1234 * A `dependency recorder`__ has been added.
1236 __ docs/user/config.html#record-dependencies
1238 * A directive has been added for `compound paragraphs`__.
1240 __ docs/ref/rst/directives.html#compound-paragraph
1243 Release 0.3.5 (2004-07-29)
1244 ==========================
1246 * Improved, extended and reorganized the documentation__.
1250 * Added "csv-table__" directive.
1252 __ docs/ref/rst/directives.html#csv-table
1254 .. _HISTORY: HISTORY.html
1255 .. _Python 3 compatibility: README.html#python-3-compatibility