Contents

• Docutils Release Notes
  • Release 0.17 (2021-04-03)
  • Future changes

Release 0.17 (2021-04-03)

• Installing with setup.py now requires setuptools. Alternatively, install with pip.

• The generic command line front end tool docutils-cli.py allows the free selection of reader, parser, and writer components.

• New, experimental wrapper to integrate the recommonmark Markdown parser for use with Docutils.

• HTML5 writer:

  • Use the new semantic tags <main>, <section>, <header>, <footer>, <aside>, <figure>, and <figcaption>. See minimal.css and plain.css for styling rule examples.

    Change the initial_header_level setting's default to "2", as browsers use the same style for <h1> and <h2> when nested in a section.

  • Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>, <i>, <b>, <u>, <mark>, and <bdi> if a matching class value is found in inline and literal elements. Use <ins> and <del> if a matching class value is found in inline, literal, or container elements.

  • New optional style responsive.css, adapts to different screen sizes.

  • New option embed_images.

• docutils/writers/html5_polyglot/

  • minimal.css: Move non-essential styling to plain.css. Code line numbers as pseudo-elements which are skipped when copying text.
  • plain.css: Support numbered figures.

• LaTeX writer:

  • New configuration setting legacy_class_functions.
  • The special value "auto" for the graphicx_option setting is no longer supported (it never worked for xetex/luatex).
  • Styling commands using the legacy \docutilsrole prefix are now ignored. Use \DUrole.
  • Most helper commands and element definitions are now defined in the LaTeX package docutils.sty and only inserted in the document preamble if the stylesheet setting does not lists "docutils".
  • Remove legacy LaTeX stylesheet docutils-05-compat.sty.
  • Fixes (thanks to) from John Thorvald Wodder II: alignment of nested tables, support memoir document class,

• pseudoxml-writer got a --detailled option for pretty printing text nodes.

• odf/odt-writer improved metadata handling.

• manpage-writer fixes #380 commandline option in spinx, #126 title with spaces, #168 empty citation, #394 newline after rubric.

• Miscellaneous:

  • Fixes in Arabic mappings and Korean translations.
  • directives: Prevent infinte inclusion loops.
  • roles: Apply patch #174 Lowercase new role names on registration by John Thorvald Wodder II.

Future changes

• latex writer:

  The default for the configuration setting legacy_class_functions will change to "False". Adapt stylesheets modifying \DUadmonition and/or \DUtitle or set to "True".

• html5 writer:

  Semantic tags: Use <aside> instad of <dl> for footnote text and citations, <aside> for topics (except abstract), admonitions, and system messages, and <nav> for the Table of Contents.

  Write footnote brackets and field term colons to HTML, so that they are present also without CSS and when copying text. Hide with CSS if required.

  Use <summary> and <details> tags for term and definition of a definition list with class value "details".

  Move attribution behind the blockquote to comply with https://html.spec.whatwg.org/#the-blockquote-element.

• htm4css1 writer: Support the embed_images option.

• s5_html writer: Remove the IE PNG Fix by Angus Turnbull. IE has native PNG support since version 7.

• Make <meta> a standard Docutils doctree node.

  The meta directive will insert <meta> instead of pending nodes. Writers may ignore some or all <meta> elements if they are not supported by the output format.

  The transforms/components.Filter class will become obsolete by this change and may be removed in future.

• Node.traverse() will return an iterator instead of a list.

• Remove utils.unique_combinations (obsoleted by itertools.combinations).

• Eventually remove the "rawsource" attribute and argument from nodes.Text: we store the null-escaped text in Text nodes since 0.16 so there is no additional information in the rawsource.

• If the id_prefix setting is non-empty, leading number and hyphen characters will not be stripped from a reference name during identifier normalization. This may change generated identifier keys.

  Example: with --id-prefix="DU-", a section with title "34. May" currently gets the identifier key DU-may and after the change the identifier key DU-34-may.

• The default value for auto_id_prefix will change to "%". This means auto-generated IDs will use the tag name as prefix. Set auto_id_prefix to "id" if you want unchanged auto-IDs or to "%" if you want the new feature already in 0.17.

• The default HTML writer "html" with frontend rst2html.py may change from "html4css1" to "html5".

  Use get_writer_by_name('html') or the rst2html.py front end, if you want the output to be up-to-date automatically.

  Use the "html4" writer or rst2html4.py, if you depend on stability of the generated HTML code, e.g. because you use a custom style sheet or post-processing that may break otherwise.