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 Drop support for Python 3.7 and 3.8 in Docutils 0.21.
25 Command line interface
26 ----------------------
28 * Docutils 0.21 will provide ``rst2*`` "console_scripts" `entry points`_
29 (without the ``.py`` extension) instead of installing the
30 ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_
32 You may use the ``docutils`` `generic command line front end tool`_
33 as a future-proof command, for example:
37 - rst2latex.py --use-latex-abstract FAQ.txt > FAQ.tex
38 + docutils --writer=latex --use-latex-abstract FAQ.txt > FAQ.tex
41 The ``rstpep2html.py`` and ``rst2odt_prepstyles.py`` scripts
44 Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_
46 Use ``python -m docutils.writers.odf_odt.prepstyles``
47 to `strip the page size`__ from an ODT writer stylesheet.
49 __ docs/user/odt.html#page-size
51 .. [#] Some Linux distributions already use the short names.
52 .. [#] The final rendering is done by a Sphinx-based build system
56 * The _`command-line usage pattern` will change:
60 - COMMAND [OPTIONS] [SOURCE [DESTINATION]]
61 + COMMAND [OPTIONS] [SOURCE [SOURCE2 [...]]] [>DESTINATION]
63 * Remove short options ``-i`` and ``-o`` in Docutils 0.22.
64 Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
66 * Stop accepting the DESTINATION positional argument in Docutils 1.0.
67 Use output redirection or the option ``--output=DESTINATION``
68 (available since Docutils 0.20).
70 * Accept more than one source document and the short option
71 ``-o`` for ``--output`` in Docutils 2.0
73 For the rationale, see https://clig.dev/#arguments-and-flags.
76 https://packaging.python.org/en/latest/specifications/entry-points/
82 * Raise `UnicodeError` (instead of falling back to the locale encoding)
83 if decoding the source with the default encoding (UTF-8) fails and
84 Python is started in `UTF-8 mode`_. (Docutils 0.21)
86 Raise `UnicodeError` (instead of falling back to "latin1") if both,
87 default and locale encoding, fail. (Docutils 0.21)
89 * Only remove BOM (U+FEFF ZWNBSP at start of data), no other ZWNBSPs.
90 Only remove BOM with `input_encoding`_ values None, '', 'utf-8-sig',
91 'utf-16', and 'utf-32'. (Docutils 0.21)
93 * Change the default input encoding from ``None`` (auto-detect) to
94 "utf-8" in Docutils 0.22.
96 * Remove the input encoding auto-detection code in Docutils 1.0 or later.
101 * The `default HTML writer`__ will change in Docutils 2.0:
103 The rst2html_ front end and ``get_writer_by_name('html')`` select
104 "html4css1" now and will select "html5" in Docutils 2.0 and later.
106 - Use rst2html4_, ``docutils --writer=html4``, or
107 ``get_writer_by_name('html4')`` if you depend on stability of the
108 generated HTML code, e.g. because you use a custom style sheet or
109 post-processing that may break otherwise.
110 - Use rst2html5_, ``docutils`` or ``get_writer_by_name('html5')``
111 if you want a HTML5 document.
113 __ docs/user/html.html#html
117 - Stop setting the "footnote-reference" class value for footnote
118 references in Docutils 0.21.
119 Since 0.18, you can use the CSS selector
120 ``[role="doc-noteref"]`` instead of ``.footnote-reference``
121 (see minimal.css for examples).
123 - Move attribution behind the blockquote to comply with the `"living
124 standard"`__. (HTML5__ allows <cite> elements inside a blockquote.)
126 __ https://html.spec.whatwg.org/#the-blockquote-element
127 __ https://www.w3.org/TR/2014/REC-html5-20141028/grouping-content.html
128 #the-blockquote-element
130 - Change the default value for math_output_ to "MathML" in Docutils 0.22.
132 - Remove option ``--embed-images`` (obsoleted by "image_loading_")
137 - Change default of use_latex_citations_ setting to True
140 - Change default of legacy_column_widths_ setting to False
143 - Remove ``use_verbatim_when_possible`` setting
144 (use literal_block_env_: verbatim) in Docutils 2.0.
146 * "null" writer: output will change to the empty string in Docutils 0.22.
151 * "csv-table_" directive:
153 - Use the same CSV format for the main CSV data and the :header: option
154 (as specified in the documentation since addition of "csv-table_")
157 - Move `parsers.rst.directives.Table.process_header_option()` to
158 `parsers.rst.directives.CSVTable` in Docutils 0.21.
160 - Remove `parsers.rst.directives.CSVTable.HeaderDialect`
163 * Remove the compatibility hacks `nodes.reprunicode` and `nodes.ensure_str()`
164 in Docutils 0.21 or later. They are not required with Python 3.x.
166 * Remove file ``install.py`` in Docutils 0.21.
167 See README.txt__ for alternatives.
169 __ README.html#installation
171 * Remove the "rawsource" argument from `nodes.Text.__init__()`
174 * Drop support for `old-format configuration files`_ in Docutils 2.0.
176 * Remove the ``--html-writer`` option of the `buildhtml.py`_ application
177 (obsoleted by the `"writer" setting`_ since Docutils 0.18)
180 * Revise the `String I/O`__ interface used by the `publish_string()`
181 and `publish_from_doctree()` publisher convenience functions.
182 (In Python 3, name and behaviour no longer match.)
184 __ docs/api/publisher.html#string-i-o
186 * Move math format conversion from docutils/utils/math (called from
187 docutils/writers/_html_base.py) to a transform__.
189 __ docs/ref/transforms.html
191 * docutils/parsers/rst/languages/
193 Fix mistranslated localizations of the "admonition" directive name in
194 Docutils 0.21 (or later). In Docutils, "admonition" is used as a
195 generic term for "advice"/"caveat"/"remark", not a reprimand.
196 Use the English term (or specific admonitions) instead of "aanmaning",
197 "ammonizione", "Ermahnung", "exhortacion", "formaning", "upomnienie",
198 or "vermaning" to avoid errors in future conversions.
200 .. _front end tools: docs/user/tools.html
202 .. _input_encoding: docs/user/config.html#input-encoding
203 .. _math_output: docs/user/config.html#math-output
204 .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
205 .. _image_loading: docs/user/config.html#image-loading
206 .. _old-format configuration files:
207 docs/user/config.html#old-format-configuration-files
209 .. _rst2html: docs/user/tools.html#rst2html
210 .. _rst2html4: docs/user/tools.html#rst2html4
211 .. _rst2html5: docs/user/tools.html#rst2html5
212 .. _reference name: docs/ref/rst/restructuredtext.html#reference-names
213 .. _literal_block_env: docs/user/config.html#literal-block-env
214 .. _use_latex_citations: docs/user/config.html#use-latex-citations
215 .. _buildhtml.py: docs/user/tools.html#buildhtml-py
216 .. _csv-table: docs/ref/rst/directives.html#csv-table
219 Release 0.20.1 (2023-05-17)
220 ===========================
222 Bugfix release. See HISTORY_ for details.
225 Release 0.20 (2023-05-04)
226 =========================
230 Docutils 0.20 is the last version supporting Python 3.7 and 3.8.
234 - Support Python 3.11 (patch #198 by Hugo van Kemenade).
239 Use dpub-ARIA role "doc-footnote" (instead of ARIA role "note")
243 Do not load the `inputenc` package in UTF-8 encoded LaTeX sources.
244 (UTF-8 is the default encoding for LaTeX2e since 2018).
246 * Configuration changes:
248 - Settings in the [latex2e writer] configuration file section
249 are now ignored by the "xetex" writer.
250 Place common settings in section `[latex writers]`_.
252 .. _[latex writers]: docs/user/config.html#latex-writers
254 - New command line setting output_. Obsoletes the ``<destination>``
255 positional argument (cf. `future changes`__).
257 __ `command-line usage pattern`_
259 * `utils.find_file_in_dirs()` now returns a POSIX path also on Windows;
260 `utils.get_stylesheet_list()` no longer converts ``\`` to ``/``.
262 * docutils/languages/
263 docutils/parsers/rst/languages/
265 - Support Ukrainian. Patch by Dmytro Kazanzhy.
269 - Removed. Use the coverage.py_ project instead,
270 ``coverage run test/alltests.py`` and ``coverage report``.
272 .. _coverage.py: https://pypi.org/project/coverage/
276 - Moved ``quicktest.py`` to ``tools/dev/``.
278 * Bugfixes and improvements (see HISTORY_).
280 .. _output: docs/user/config.html#output
283 Release 0.19 (2022-07-05)
284 =========================
286 (Release 0.19b1 (2022-06-21))
288 * Drop support for Python 2.7, 3.5, and 3.6.
293 Wrap groups of footnotes in an ``<aside>`` for easier styling.
295 The CSS rule ``.footnote-list { display: contents; }`` can be used to
296 restore the behaviour of custom CSS styles.
298 * After package installation, the CLI commands ``python -m docutils`` and
299 ``docutils`` start the `generic command line front end tool`_.
301 .. _generic command line front end tool:
302 docs/user/tools.html#generic-command-line-front-end
304 * Support parsing "Markdown" input with 3rd party parsers
305 myst_, pycmark_, or recommonmark_.
307 * The default values for the "pep-references", "rfc-base-url",
308 and "python-home" `configuration settings`_ now use the "https:" scheme.
309 The PEP-writer template's header is updated to fix links and
310 resemble the header of official PEPs.
312 * Various bugfixes and improvements (see HISTORY_).
314 .. _myst: https://pypi.org/project/myst-docutils
315 .. _pycmark: https://pypi.org/project/pycmark/
316 .. _recommonmark: https://pypi.org/project/recommonmark/
317 .. _configuration settings: docs/user/config.html
320 Release 0.18.1 (2021-12-23)
321 ===========================
325 Docutils 0.18.1 is the last version supporting Python 2.7, 3.5, and 3.6.
327 * ``nodes.Node.traverse()`` returns a list again to restore backwards
328 compatibility (fixes bug #431).
329 Use ``nodes.Node.findall()`` to get an iterator.
331 * re-add module ``parsers.rst.directives.html``
332 (stub, emits deprecation warning and loads
333 "Meta" directive from its new place at ``parsers.rst.directives.misc``.)
335 * Small bugfixes (see HISTORY_).
338 Release 0.18 (2021-10-26)
339 =========================
344 - During `identifier normalization`_, leading number and hyphen
345 characters are no longer stripped from a `reference name`_, if the
346 id_prefix_ setting is non-empty.
349 with ``--id-prefix="DU-"``, a section with title "34. May"
350 currently gets the identifier key ``DU-may`` and after the
351 change the identifier key ``DU-34-may``.
353 - The default value for the auto_id_prefix_ setting changed to ``%``:
354 "use the tag name as prefix for auto-generated IDs".
355 Set auto_id_prefix_ to ``id`` for unchanged auto-IDs.
358 - Use the semantic tag <aside> for footnote text and citations, topics
359 (except abstract and toc), admonitions, and system messages.
360 Use <nav> for the Table of Contents.
362 - Make "auto" table column widths the default: Only specify column
363 widths, if the `"widths" option`_ is set and not "auto".
364 The table-style__ setting "colwidths-grid" restores the current default.
366 .. _"widths" option: __ docs/ref/rst/directives.html#table
367 __ docs/user/config.html#table-style
369 - Items of a definition list with class argument "details" are
370 converted to `details disclosure elements`_. Example::
375 This additional information should be hidden.
377 - Do not add "compound-first", "compound-middle", or "compound-last" to
378 elements nested in a compound. Use child selector and ":first-child",
379 ":last-child" pseudo classes instead.
381 - Use class value "backrefs" instead of "fn-backref" for a span of
384 - Write footnote brackets and field term colons to HTML, so that they
385 are present also without CSS and when copying text.
387 - Move space character between section number and heading into
391 - Support more commands, fix mapping of commands to Unicode characters.
392 - Scale variable sized operators and big delimiters with CSS.
393 - Don't use <tt> element (deprecated in HTML5).
394 - Use STIX fonts if available.
397 `legacy_class_functions`_ setting default changed to "False",
398 admonitions are now environments.
400 * New standard Docutils doctree node: <meta__>.
402 * New configuration settings:
404 - [latex writers] legacy_column_widths_ and
405 - [html5 writer] image_loading_.
408 ``iepngfix.htc`` and ``blank.gif`` (IE 6 workaround for `s5_html`).
410 * Removed sub-module:
411 ``parsers.rst.directives.html``
412 (reversed in release 0.18.1).
414 * Removed function: utils.unique_combinations()
415 (obsoleted by itertools.combinations()).
417 * Removed attributes:
419 - ``HTMLTranslator.topic_classes``: check ``node.parent.classes`` instead.
420 - ``nodes.Text.rawsource``: we store the null-escaped text in Text
421 nodes since 0.16 so there is no additional information in the
424 * Major refactoring and fixes/additions in
425 ``docutils/utils/math/math2html.py`` and
426 ``docutils/utils/math/latex2mathml.py``
427 (mathematical notation in HTML, cf. `LaTeX syntax for mathematics`_).
429 * nodes.Node.traverse() returns an iterator instead of a list
430 (reversed in release 0.18.1).
432 * Various bugfixes and improvements (see HISTORY_).
434 Fix spelling errors in documentation and docstrings.
435 Thanks to Dimitri Papadopoulos.
437 __ docs/ref/doctree.html#meta
438 .. _identifier normalization:
439 docs/ref/rst/directives.html#identifier-normalization
440 .. _id_prefix: docs/user/config.html#id-prefix
441 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
442 .. _details disclosure elements:
443 https://www.w3.org/TR/html52/interactive-elements.html#the-details-element
444 .. _LaTeX syntax for mathematics: docs/ref/rst/mathematics.html
445 .. _legacy_column_widths: docs/user/config.html#legacy-column-widths
448 Release 0.17.1 (2021-04-16)
449 ===========================
451 * Bug fixes (for details see the Docutils `HISTORY`_).
453 Release 0.17 (2021-04-03)
454 =========================
456 * Numerous bug fixes and improvements
457 (for details see the Docutils `HISTORY`_).
459 * Installing with ``setup.py`` now requires setuptools_.
460 Alternatively, install with pip_.
462 * The generic command line front end tool docutils-cli.py_ allows
463 the free selection of reader, parser, and writer components.
465 * Support Arabic language.
467 * New, **experimental** wrapper to integrate the `recommonmark`__
468 Markdown parser for use with Docutils.
469 Currently only tested with recommonmark version 0.4.0.
471 __ https://pypi.org/project/recommonmark/
475 - New option embed_images_.
477 - Use semantic tags (for details see the Docutils `HISTORY`_).
479 - Change the `initial_header_level`_ setting's default to "2", as browsers
480 use the `same style for <h1> and <h2> when nested in a section`__.
482 - New optional style ``responsive.css``, adapts to different screen
485 - Move non-essential styling from ``minimal.css`` to ``plain.css``
486 rsp. ``responsive.css``.
488 - Show code line numbers as pseudo-elements so they are skipped when
489 copying the code block from the page.
491 .. _initial_header_level: docs/user/config.html#initial-header-level
492 __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
493 .. _embed_images: docs/user/config.html#embed-images
497 - New configuration setting `legacy_class_functions`_.
499 - The special value "auto" for the `graphicx_option`_ setting
500 is no longer supported (it never worked for xetex/luatex).
502 - `Styling commands`__ using the legacy ``\docutilsrole`` prefix are
503 now ignored. Use ``\DUrole``.
505 __ docs/user/latex.html#classes
507 - Most helper commands and element definitions are now defined in the
508 LaTeX package `docutils.sty`_ and only inserted in the document
509 preamble if the stylesheet__ setting does not lists "docutils".
511 __ docs/user/config.html#stylesheet-latex-writers
513 - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.
515 .. _setuptools: https://pypi.org/project/setuptools/
516 .. _pip: https://pypi.org/project/pip/
517 .. _docutils-cli.py: docs/user/tools.html#docutils-cli-py
518 .. _legacy_class_functions: docs/user/config.html#legacy-class-functions
519 .. _graphicx_option: docs/user/config.html#graphicx-option
520 .. _docutils.sty: https://ctan.org/pkg/docutils
523 Release 0.16 (2020-01-12)
524 =========================
526 Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
527 without the use of the ``2to3`` tool.
531 - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
532 escaping of author-separators in `bibliographic fields`__.
534 __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
535 __ docs/ref/rst/restructuredtext.html#bibliographic-fields
539 - Informal titles of type "rubric" default to bold-italic and left aligned.
540 - Deprecate ``\docutilsrole`` prefix for styling commands:
541 use ``\DUrole`` instead.
542 - Fix topic subtitle.
543 - Add "latex writers" to the `config_section_dependencies`.
544 - Ignore classes for `rubric` elements
545 (class wrapper interferes with LaTeX formatting).
549 - New option ``--html-writer`` allows to select "html" (default),
550 "html4" or "html5" (deprecated in favour of the `"writer" setting`_
553 .. _"writer" setting:
554 docs/user/config.html#writer-buildhtml-application
558 - Remove the `handle_io_errors` argument from io.FileInput/Output.
562 - If `auto_id_prefix`_ ends with "%", this is replaced with the tag name.
564 .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
566 * Various bugfixes and improvements (see HISTORY_).
569 Release 0.15 (2019-07-20)
570 =========================
572 Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5.
576 Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
580 - Allow embedded colons in field list field names (before, tokens like
581 ``:this:example:`` were considered ordinary text).
583 - Fixed a bug with the "trim" options of the "unicode" directive.
585 * languages: Added Korean localisation (ko).
588 Release 0.14 (2017-08-03)
589 =========================
593 Docutils 0.14.x is the last version supporting Python 2.4, 2.5,
596 * docutils/docs/ref/docutils.dtd:
598 - Enable validation of Docutils XML documents against the DTD:
600 * docutils/parsers/rst/:
602 - Added functionality: escaped whitespace in URI contexts.
603 - Consistent handling of all whitespace characters in inline markup
604 recognition. (May break documents that relied on some whitespace
605 characters (NBSP, ...) *not* to be recognized as whitespace.)
607 * docutils/utils/smartquotes.py:
609 - Update quote definitions for et, fi, fr, ro, sv, tr, uk.
610 - Add quote definitions for hr, hsb, hu, lv, sh, sl, sr.
611 - Differentiate apostrophe from closing single quote (if possible).
612 - Add command line interface for stand-alone use (requires 2.7).
614 * docutils/writers/_html_base:
616 - Provide default title in metadata.
617 - The MathJax CDN shut down on April 30, 2017. For security reasons, we
618 don't use a third party public installation as default but warn
619 if `math-output` is set to MathJax without specifying a URL.
620 See math-output_ for details.
622 * docutils/writers/html4css1:
624 - Respect automatic table column sizing.
626 * docutils/writers/latex2e/__init__.py
628 - Handle class arguments for block-level elements by wrapping them
629 in a "DUclass" environment. This replaces the special handling for
630 "epigraph" and "topic" elements.
632 * docutils/writers/odf_odt:
634 - Language option sets ODF document's default language
635 - Image width, scale, ... set image size in generated ODF.
639 - New front-end ``rst2html4.py``.
642 Release 0.13.1 (2016-12-09)
643 ===========================
645 * docutils/writers/html5_polyglot
647 - New HTML writer generating `HTML 5`_.
649 .. _HTML 5: https://www.w3.org/TR/html5/
653 - New front-end ``rst2html5.py``.
655 * languages: persian/farsi (fa) and latvian (la) mappings.
657 * change default base url for :rfc: to http://tools.ietf.org/html/
659 * tables accept widths, a list and align
661 * latex2e: Fix admonition width, remove deprecated options,
662 better tablewidth auto, ...
664 * rst.el: The problem with ``electric-indent-mode`` has been fixed.
667 Release 0.12 (2014-07-06)
668 =========================
670 Small changes only, release current state
673 Release 0.11 (2013-07-22)
674 =========================
678 - Apply [ 2714873 ] Fix for the overwriting of document attributes.
679 - Support embedded aliases within hyperlink references.
680 - Fix [ 228 ] try local import of docutils components (reader, writer, parser,
681 language module) before global search.
683 * docutils/parsers/rst/directives/tables.py
685 - Fix [ 210 ] Python 3.3 checks CVS syntax only if "strict" is True.
687 * docutils/writers/html4css1/__init__.py
688 - Fix [ 3600051 ] for tables in a list, table cells are not compacted.
689 - New setting `stylesheet_dirs` (see above).
691 Now, it is easy to add a custom stylesheet to Docutils' default
692 stylesheet with, e.g., ``--stylesheet_path='html4css1.css, mystyle.css'``
694 Changed behaviour of the default settings:
695 if there is a file ``html4css1.css`` in the working directory of the
696 process at launch, it is used instead of the one provided by Docutils
697 in the writer source directory.
699 - New default for math-output_: ``HTML math.css``.
700 - Avoid repeated class declarations in html4css1 writer
701 (modified version of patch [ 104 ]).
703 .. _math-output: docs/user/config.html#math-output
705 * docutils/writers/latex2e/__init__.py
707 - Drop the simple algorithm replacing straight double quotes with
708 English typographic ones.
709 Activate the SmartQuotes_ transform if you want this feature.
710 - New setting `stylesheet_dirs`: Comma-separated list of directories
711 where stylesheets are found. Used by `stylesheet_path` when expanding
712 relative path arguments.
714 .. _SmartQuotes: docs/user/config.html#smart-quotes
716 * docutils/writers/manpage.py
718 - Fix [3607063] handle lines starting with a period.
719 - Fix option separating comma was bold (thanks to Bill Morris).
721 Release 0.10 (2012-12-16)
722 =========================
724 Docutils 0.10 is compatible with Python versions from 2.4 to 3.2.
728 - SmartQuotes transform for typographic quotes and dashes.
730 - ``docutils/math``, ``docutils/error_reporting.py``, and
731 ``docutils/urischemes.py`` moved to the utils package.
732 Code importing these modules needs to adapt, e.g.::
735 import docutils.math as math
737 import docutils.utils.math as math
739 - enhanced math and error handling.
743 - FileInput/FileOutput: no system-exit on IOError.
744 The `handle_io_errors` argument is ignored.
746 * docutils/writers/html4css1/__init__.py
748 - Use ``<code>`` tag for inline "code",
749 do not drop nested inline nodes (syntax highlight tokens).
750 - Customizable MathJax URL (based on patch by Dmitry Shachnev).
751 - No line break after opening inline math tag.
753 * docutils/writers/latex2e/__init__.py, docutils/writers/xetex/__init__.py
755 - Fix section numbering by LaTeX.
757 * docutils/writers/s5_html/__init__.py
759 - Fix [ 3556388 ] Mathjax does not work with rst2s5.
762 Release 0.9.1 (2012-06-17)
763 ==========================
767 Docutils 0.9.1 is the last version supporting Python 2.3.
771 Several fixes for Python 3 usage.
775 - Fix [ 3527842 ]. Under Python 3, converted tests and tools were
776 installed in the PYTHONPATH. Converted tests are now
777 stored in ``docutils/test3/``, tools no longer need conversion.
779 If you installed one of Docutils versions 0.7 ... 0.9 with
780 ``setup.py install`` under Python 3, remove the spurious
781 ``test/`` and ``tools/`` directories in the site library root.
784 Release 0.9 (2012-05-02)
785 =========================
789 - reStructuredText "code" role and directive with syntax highlighting
791 - "code" option of the "include" directive.
793 .. _Pygments: https://pygments.org/
795 - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation
796 characters and "international" quotes around inline markup.
798 - Fix handling of missing stylesheets.
802 - Fix [ 2971827 ] and [ 3442827 ]
803 extras/roman.py moved to docutils/utils/roman.py
805 * docutils/utils.py -> docutils/utils/__init__.py
807 - docutils.utils is now a package (providing a place for sub-modules)
809 * docutils/writers/html4css1/__init__.py
811 - change default for `math-output` setting to MathJax
813 * docutils/writers/latex2e/__init__.py
815 - Support the `abbreviation` and `acronym` standard roles.
816 - Record only files required to generate the LaTeX source as dependencies.
817 - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions
818 when suppressing LaTeX section numbering.
821 Release 0.8.1 (2011-08-30)
822 ==========================
826 - Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause)
827 and [ 3395920 ] (correct copyright info for rst.el).
829 * docutils/writers/latex2e/__init__.py
831 - Clean up Babel language setting. Restores Sphinx compatibility.
834 Release 0.8 (2011-07-07)
835 ========================
839 - Some additions to the Docutils core are released under the 2-Clause BSD
844 - Handle language codes according to `BCP 47`_.
845 - If the specified language is not supported by Docutils,
846 warn and fall back to English.
847 - Math support: reStructuredText "math" role and directive,
848 ``math`` and ``math_block`` doctree elements.
849 - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox.
851 .. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
855 - most directives now support a "name" option that attaches a
856 reference name. So you can write ::
858 .. figure:: image.png
861 as a short form of ::
865 .. figure:: image.png
867 Internationalization:
869 * Added lithuanian mappings.
875 - New setting "math-output" with support for HTML, MathML, and LaTeX.
879 - Convert image URI to a local file path.
880 - Apply [ 3148141 ] fix multicolumn support when a colspanning cell
881 has more than one paragraph (Wolfgang Scherer).
885 - New writer generating LaTeX code for compiling with ``xelatex``.
887 XeTeX uses unicode and modern font technologies.
889 * and fixes and enhancements here and there.
892 Release 0.7 (2010-07-07)
893 ========================
899 - Support SVG and SWF images (thanks to Stefan Rank).
900 - Generate valid XHTML for centered images with targets.
901 Use CSS classes instead of "align" tags for image alignment.
905 - Use the ``\url`` command for URLs (breaks long URLs instead of writing
907 - Preserve runs of spaces in 'inline literals'.
908 - Deprecate ``figure_footnotes`` setting.
909 - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__.
910 - New ``latex_preamble`` setting.
911 - Use PDF standard fonts (Times/Helvetica/Courier) as default.
912 - `hyperref` package called with ``unicode`` option (see the
913 `hyperref config tips`__ for how to override).
914 - Drop the special `output_encoding`__ default ("latin-1").
915 The Docutils wide default (usually "UTF-8") is used instead.
917 __ docs/user/config.html#docutils-footnotes
918 __ docs/user/latex.html#hyperlinks
919 __ docs/user/latex.html#output-encoding
923 - Titles level 1, that is ``.SH``, always uppercase.
924 - Apply patch from mg: literal text should be bold in man-pages.
928 * io.FileInput opens files as text files with universal newline support
929 (mode "rU", configurable with the new optional argument "mode").
933 - Python 3 support: copy test/ and tools/ to the build-dir
934 and convert Python sources with 2to3.
937 Release 0.6 (2009-10-11)
938 ========================
940 Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6
941 and convertible to 3.1 code.
945 The "newlatex" writer is orphaned.
947 The recommended way to generate PDF output is to use either the
948 LaTeX2e writer or one of the alternatives listed at
949 https://docutils.sourceforge.io/docs/user/links.html#pdf.
953 - Allow length units for all length specifications.
954 - Allow percent sign in "scale" argument of "figure" and "image" directives.
955 - Bugfix: The "figalign" argument of a figure now works as intended
956 (aligning the figure not its contents).
957 - Align images with class "align-[right|center|left]"
958 (allows setting the alignment of an image in a figure).
959 - Hard tabs in literal inclusions are replaced by spaces. This is
960 configurable via the new "tab-width" option of the "include" directive
961 (a negative tab-width prevents tab expansion).
965 - ``--stylesheet`` and ``--stylesheet-path`` options now support a comma
966 separated list of stylesheets.
971 - font-encoding: "T1" (formerly implicitly set by 'ae').
972 - use-latex-toc: true (ToC with page numbers).
973 - use-latex-footnotes: true (no mixup with figures).
974 - Float placement defaults to "here definitely" (configurable).
975 - Align of image in a figure defaults to 'center'.
976 - Use class defaults for page margins ('typearea' now optional).
977 - Support LaTeX packages as ``--stylesheet`` arguments.
978 - Use ``bp`` for lengths without unit or unit ``pt``,
979 do not convert ``px`` to ``pt``.
980 - Do not use 'ae' and 'aeguill' packages if font-encoding is set to ''.
981 - Set sub- and superscript role argument as text not math.
982 - Support custom roles based on standard roles.
983 - Load packages and define macros only if required in the document.
984 - All Docutils specific LaTeX macros are prefixed with ``DU``.
985 - Better conformance to Docutils specifications with "use_latex_toc".
986 - If 'sectnum_xform' is False, the 'sectnum' directive triggers
987 section numbering by LaTeX.
988 - Use default font in admonitions and sidebar.
989 - Typeset generic topic as "quote with title".
990 - Use template (file and configuration option).
991 - Render doctest blocks as literal blocks (indented).
995 - moved from sandbox to Doctutils core.
999 - moved from sandbox to Doctutils core.
1002 Release 0.5 (2008-06-25)
1003 ========================
1007 Docutils 0.5 is the last version supporting Python 2.2.
1013 - Dropped all ``name`` attributes of ``a`` elements (``id`` is
1014 universally supported now).
1018 - Better bibTeX citation support.
1019 - Add ``--literal-block-env``
1023 - Changed to support new python.org website structure and
1028 * Changed the directive API to a new object-oriented system.
1029 (Compatibility for the old, functional-style directive interface is
1030 retained.) See the updated `Creating reStructuredText Directives`__
1033 __ docs/howto/rst-directives.html
1035 * Allow ``+`` and ``:`` in reference names requested for citations.
1039 * Added `Deploying Docutils Securely`__
1041 __ docs/howto/security.txt
1043 Internationalization:
1045 * Added hebrew mappings.
1049 * Configuration files are now assumed and required to be
1052 * Added docutils/writers/html4css1/template.txt.
1054 * Enhance emacs support.
1057 Release 0.4 (2006-01-09)
1058 ========================
1062 Docutils 0.4 is the last version supporting Python 2.1.
1064 It is also the last version that will make compromises in
1065 its HTML output for Netscape Navigator 4. Docutils 0.5 will
1066 require more up-to-date browsers (the exact definition is to be
1071 * Added an `S5/HTML writer`__ and the rst2s5.py__ front end:
1072 multi-platform, multi-browser HTML slide shows.
1074 __ docs/user/slide-shows.html
1075 __ docs/user/tools.html#rst2s5-py
1077 * The newlatex2e writer is nearing completion.
1079 * Added a DocTree reader, ``publish_doctree`` and
1080 ``publish_from_doctree`` convenience functions, for document tree
1081 extraction and reprocessing.
1085 * Added directives: "container__" (generic block-level container),
1086 "default-role__" (role used for \`backtick\` syntax), "title__"
1087 (document title metadata), and "date__" (generate the current local
1088 date, for substitution definitions).
1090 __ docs/ref/rst/directives.html#container
1091 __ docs/ref/rst/directives.html#default-role
1092 __ docs/ref/rst/directives.html#title
1093 __ docs/ref/rst/directives.html#date
1095 * Length units are now supported for image__ sizes.
1097 __ docs/ref/rst/directives.html#image
1099 * Added `standard definition files`__ for special characters etc.
1101 __ docs/ref/rst/definitions.html
1103 Internationalization:
1105 * Added Japanese and Simplified Chinese language mappings, and support
1106 for double-width CJK-characters in tables and section titles.
1110 * Added a `guide for distributors`__ (package maintainers) and a
1111 `guide for developers`__.
1113 __ docs/dev/distributing.html
1114 __ docs/dev/hacking.html
1118 * Added significant `Emacs support for reST`__.
1120 __ docs/user/emacs.html
1122 * Added a `--strip-comments`__ option.
1124 __ docs/user/config.html#strip-comments
1126 * `--embed-stylesheet`__ is now the default for the HTML writer
1127 (rather than --link-stylesheet).
1129 __ docs/user/config.html#embed-stylesheet
1132 Release 0.3.9 (2005-05-26)
1133 ==========================
1135 * Added "file_insertion_enabled__" and "raw_enabled__" settings.
1137 __ docs/user/config.html#file-insertion-enabled
1138 __ docs/user/config.html#raw-enabled
1140 * Added `auto-enumerated lists`__.
1142 __ docs/ref/rst/restructuredtext.html#enumerated-lists
1144 * Added `"header" and "footer"`__ directives.
1146 __ docs/ref/rst/directives.html#document-header-footer
1148 * Added "list-table__" directive.
1150 __ docs/ref/rst/directives.html#list-table
1152 * Added support for `section subtitles`__.
1154 __ docs/user/config.html#sectsubtitle-xform
1156 * Added "field_name_limit__" and "option_limit__" settings to HTML writer.
1158 __ docs/user/config.html#field-name-limit
1159 __ docs/user/config.html#option-limit
1161 * Added "cloak_email_addresses__" setting to HTML writer.
1163 __ docs/user/config.html#cloak-email-addresses
1165 * UTF-8 BOMs are now removed from the input stream.
1168 Release 0.3.7 (2004-12-24)
1169 ==========================
1171 * A special "`line block`__" syntax has been added. (Also see the
1172 `quick reference`__.)
1174 __ docs/ref/rst/restructuredtext.html#line-blocks
1175 __ docs/user/rst/quickref.html#line-blocks
1177 * Empty sections are now allowed.
1179 * A "raw__" role has been added.
1181 __ docs/ref/rst/roles.html#raw
1183 * The LaTeX writer now escapes consecutive dashes (like "--" or "---")
1184 so that they are no longer transformed by LaTeX to en or em dashes.
1185 (Please see the FAQ__ for how to represent such dashes.)
1187 __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document
1189 * A `dependency recorder`__ has been added.
1191 __ docs/user/config.html#record-dependencies
1193 * A directive has been added for `compound paragraphs`__.
1195 __ docs/ref/rst/directives.html#compound-paragraph
1198 Release 0.3.5 (2004-07-29)
1199 ==========================
1201 * Improved, extended and reorganized the documentation__.
1205 * Added "csv-table__" directive.
1207 __ docs/ref/rst/directives.html#csv-table
1209 .. _HISTORY: HISTORY.html
1210 .. _Python 3 compatibility: README.html#python-3-compatibility