[Docutils-checkins] SF.net SVN: docutils:[9561] trunk/docutils

[<mi...@us...>]

Revision: 9561
          http://sourceforge.net/p/docutils/code/9561
Author:   milde
Date:     2024-03-14 16:34:48 +0000 (Thu, 14 Mar 2024)
Log Message:
-----------
Documentation fixes. Prepare release 0.21.rc1

Fix typos, links,

Harmonise spacing and markup.

Verify authorship of "literal block" patch for the manpage writer
(forwarded from a Debian bug report discussion as patch #205).

Use NBSP between program name and version number.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/ref/rst/directives.txt
    trunk/docutils/docs/ref/rst/restructuredtext.txt
    trunk/docutils/docs/user/config.txt
    trunk/docutils/docs/user/slide-shows.txt
    trunk/docutils/docutils/parsers/commonmark_wrapper.py
    trunk/docutils/docutils/utils/math/mathml_elements.py

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/HISTORY.txt	2024-03-14 16:34:48 UTC (rev 9561)
@@ -14,16 +14,14 @@
 .. contents::
 
 
-Changes since 0.20.1
-====================
+Release 0.21.rc1
+================
 
 * General
 
   - Drop support for Python 3.7 and 3.8.
-
-  - Updated build stystem to use Flit_ (patch #186 by Adam Turner).
+  - Updated build system to use Flit_ (patch #186 by Adam Turner).
     Removed ``setup.py``.
-
   - Provide ``rst2*`` "console_scripts" `entry points`_
     (without the ``.py`` extension) instead of installing the
     ``rst2*.py`` front end tools in the binary PATH.
@@ -33,6 +31,7 @@
 * docs/ref/docutils.dtd
 
   - The <image> element accepts a new attribute "loading".
+
   - Fix definitions (no change to actual behaviour):
 
     * The <math_block> element uses the attribute "xml:space".
@@ -51,23 +50,21 @@
     Do not use the locale encoding as fallback if Python is started in
     `UTF-8 mode`_. Stop using "latin1" as second fallback.
 
-    Remove BOM (U+FEFF ZWNBSP at start of data) only if the `input_encoding`_
+    Remove BOM (U+FEFF ZWNBSP at start of data) only if the "input_encoding"
     configuration setting is None, '', 'utf-8-sig', 'utf-16', or 'utf-32'.
     Do not remove other ZWNBSPs.
 
+    .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
+    .. _input encoding: docs/api/publisher.html#encodings
+
   - Auto-close `FileInput.source` in case of reading/decoding errors.
 
-  .. _UTF-8 mode: https://docs.python.org/3/library/os.html#utf8-mode
-  .. _input encoding: docs/api/publisher.html#encodings
-
 * docutils/languages/, docutils/parsers/rst/languages/
 
   - Mark/Fix mistranslated localizations of the "admonition" directive
     name. In Docutils, "admonition" is used as a generic term for
     "advice"/"advisory"/"remark", not a reprimand.
-
   - Add support for Georgian language (patch #204 by Temuri Doghonadze).
-
   - Update/complete Catalan translations (patch #203 by Antoni Bella Pérez).
 
 * docutils/nodes.py
@@ -83,8 +80,8 @@
   - Use the same CSV format for the ``:header:`` option and the main data
     of the "csv-table" directive.
 
-  - Move `parsers.rst.directives.Table.process_header_option()` to
-    `parsers.rst.directives.CSVTable`.
+  - Move `parsers.rst.directives.Table.process_header_option()` method
+    to `parsers.rst.directives.CSVTable`.
 
 * docutils/parsers/rst/states.py
 
@@ -93,7 +90,7 @@
 * docutils/parsers/rst/directives/misc.py,
   docutils/parsers/rst/directives/tables.py
 
-  - Consider the root-prefix_ setting when including files with
+  - Consider the new root_prefix_ setting when including files with
     "include", "raw", or "csv-table" directives.
 
 * docutils/utils/math/*
@@ -102,7 +99,6 @@
     abusing `SyntaxError` for LaTeX math syntax errors.
   - Unify interface of LaTeX -> MathML conversion functions.
     Improve error reporting.
-  - Elimitate side-effect of importing "latex2mathml" on "tex2unichar".
   - Sort ℏ (`\hslash`) as "mathord", not "mathalpha".
 
 * docutils/utils/math/latex2mathml.py
@@ -112,7 +108,7 @@
     Use CSS rules instead of the deprecated "columnalign" attribute
     to style <mtable> as "align" environment.
 
-    Use Mathematical Alphanumeric Symbols instead of `<mstyle>` with
+    Use Mathematical Alphanumeric Symbols instead of <mstyle> with
     "mathvariant" attribute.
 
   - Use <mi> instead of <mo> for character class "mathord".
@@ -119,26 +115,28 @@
 
   - Support "aligned" environment.
 
+  - Eliminate side-effect on later import of "tex2unichar".
+
 * docutils/utils/math/mathml_elements.py
 
-  - New module defining MathML element classes (outsourced from
-    latex2mathml.py).
+  - New module defining MathML element classes
+    (outsourced from latex2mathml.py).
   - Base MathML element classes on `xml.etree.ElementTree`.
 
 * docutils/utils/roman.py
 
   - Update to version `1.4 <https://pypi.org/project/roman/4.1/>`__.
-    Fixes feature-requests:#95 (license is now ZPL 2.1).
+    Fixes feature-request #95 (license is now ZPL 2.1).
 
 * docutils/utils/smartquotes.py
 
   - Pre-compile regexps once, not with every call of `educateQuotes()`
-    (patch #206 by Chris Sewell); simplify regexps; skip replacement
-    rules if there is nothing to replace.
+    (patch #206 by Chris Sewell).
+  - Simplify regexps; skip replacement rules if there is nothing to replace.
 
 * docutils/writers/html4css1/__init__.py
 
-  - Support video inclusion via `<object>` tags.
+  - Support video inclusion via ``<object>`` tags.
 
 * docutils/writers/html5_polyglot/\*.css
 
@@ -153,33 +151,31 @@
   - Warn, if image scaling fails because the image file cannot be read.
   - Support video inclusion via ``<video>`` tags
     (moved here from writers/html5_polyglot/__init__.py).
-  - New auxiliary function `HTMLTranslator.uri2imagepath()`
-    ensures the image file can also be read when
-    CWD and output directory differ.
-  - Consider the root-prefix_ setting when converting an image URI
+  - New auxiliary method `HTMLTranslator.uri2imagepath()` ensures the
+    image file can also be read when CWD and output directory differ.
+  - Consider the root_prefix_ setting when converting an image URI
     to a local filesystem path.
-  - New <image> attribute "loading" overrides "image-loading" setting.
-  - Embed SVG images as ``<svg>`` instead of data-URI
-    (not used by "html4css1").  Fixes [feature-requests:#100].
-  - Write system messages for errors/warnings during the writing stage
+  - New `\<image>`_ attribute "loading" overrides image_loading_ setting.
+  - Embed SVG images as ``<svg>`` instead of data-URI.
+    Fixes feature-request #100.
+  - Generate system messages for errors/warnings during the writing stage
     (image transformations, math content conversion, ...).
-  - Close ``<dt>`` element in `depart_term()` to allow a `definition_list_item`
-    with multiple `term`\ s (cf. [feature-requests:60]).
+  - Close ``<dt>`` element in `depart_term()` to allow a
+    "definition_list_item" with multiple "terms" (cf. feature-request #60).
 
-  .. _root-prefix: docs/user/config.html#root-prefix
-
 * docutils/writers/latex2e/__init__.py
 
   - Fix placement of hyperlink target (label) for tables (bug #440).
-  - More compact option-list and description-list.
+  - More compact LaTeX source for option-lists and description-lists
+    (no change in output).
 
 * docutils/writers/manpage.py
 
   - Add multiple definition list term support, see feature #60.
-  - Add preprocessor hinting tbl first line, see bugs #477.
-  - Change tbl-Tables using box option, see bugs #475.
+  - Add preprocessor hinting tbl first line, see bug #477.
+  - Change tbl-Tables using box option, see bug #475.
   - Apply literal block patch #205. Use ``.EE`` and ``.EX`` macros.
-    Thanks to G. Branden Robinson (I assume).
+    Thanks to G. Branden Robinson.
 
 * docutils/writers/odf_odt/__init__.py
 
@@ -191,17 +187,13 @@
 * docutils/writers/s5_html/__init__.py
 
   - Warn if the S5 writer cannot copy the theme files.
+  - Programmatic customization of theme_url_ setting no longer
+    overridden by the default for theme_.
 
-  - Programmatic customization of "theme_url__" setting no longer
-    overridden by the default for "theme__".
-
-    __ docs/user/config.html#theme-url
-    __ docs/user/config.html#theme
-
 * tools/buildhtml.py
 
-  - New option `rst_sources`_.
-    Match `prune` values with `fnmatch.fnmatch()`.
+  - New configuration setting `sources`_.
+  - Match `prune`_ values with `fnmatch.fnmatch()`.
 
 
 Release 0.20.1 (2023-05-17)
@@ -589,11 +581,9 @@
 
 * docutils/nodes.py
 
-  - Make meta__ a standard Docutils doctree node. Writers may ignore
-    `meta` nodes if they are not supported by the output format.
+  - Make `\<meta>`_ a standard Docutils doctree node. Writers may ignore
+    <meta> nodes if they are not supported by the output format.
 
-    __ docs/ref/doctree.html#meta
-
   - document.make_id(): Do not strip leading number and hyphen characters
     from `name` if the `id_prefix`_ setting is non-empty.
 
@@ -853,14 +843,11 @@
 
   - Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
     <i>, <b>, <u>, <mark>, and <bdi> if a unique, matching class value
-    is found in `inline`__ and `literal`__ elements.
+    is found in `\<inline>`_ and `\<literal>`_ elements.
     Use <ins> and <del> if a unique matching class value
     is found in `inline`, `literal`, or `container` elements.
     Use <small> for generated code line numbers.
 
-    __ docs/ref/doctree.html#inline
-    __ docs/ref/doctree.html#literal
-
   - Fix bug #398: properly close link tag to "schema.dcterms".
 
   - Add a `viewport meta tag`__ to fix rendering in mobile browsers.
@@ -990,12 +977,12 @@
 
 * docutils/statemachine.py
 
-  - Patch [ 158 ]: Speed up patterns by saving compiled versions (eric89gxl)
+  - Patch [ 158 ] Speed up patterns by saving compiled versions (eric89gxl)
 
 * docutils/transforms/universal.py
 
-  - Fix [ 332 ]: Standard backslash escape for smartquotes.
-  - Fix [ 342 ]: No escape in roles descending from `inline literal`.
+  - Fix [ 332 ] Standard backslash escape for smartquotes.
+  - Fix [ 342 ] No escape in roles descending from `inline literal`.
 
 * docutils/utils/__init__.py
 
@@ -1028,12 +1015,12 @@
 
 * test/alltests.py
 
-  - Fix: 377 ResourceWarning: unclosed file python3.8
+  - Fix [ 377 ] ResourceWarning: unclosed file python3.8
     Close alltests.out with atexit.
 
 * test/functional/*
 
-  - Fix: 377 ResourceWarning: unclosed file python3.8
+  - Fix [ 377 ] ResourceWarning: unclosed file python3.8
     Read defaults file with context.
 
   - Set `auto_id_prefix`_ to "%" (expands to tag-names).
@@ -1046,7 +1033,7 @@
 
 * test/test_writers/test_odt.py
 
-  - Fix [ 359 ]: Test suite fails on Python 3.8. odt XML sorting.
+  - Fix [ 359 ] Test suite fails on Python 3.8. odt XML sorting.
     Use ElementTree instead of minidom.
 
 * tools/buildhtml.py
@@ -1059,7 +1046,7 @@
 
 source: branches/rel-0.15
 
-Bugs #366 fix release for python2 only.
+Fix [ 366 ] circular dependency. Release for Python 2 only.
 
 
 Release 0.15 (2019-07-20)
@@ -1067,7 +1054,7 @@
 
 * General
 
-  - Dropped support for Python 2.4, 2.5, 3.1, and 3.2.
+  - Dropped support for Python 2.4, 2.5, 3.1, and 3.2.
   - Infrastructure automation.
 
 * docs/ref/docutils.dtd
@@ -1379,7 +1366,6 @@
 
 .. _polyglot: https://www.w3.org/TR/html-polyglot/
 .. _HTML 5: https://www.w3.org/TR/html5/
-.. _XHTML 1.0: https://www.w3.org/TR/xhtml1/
 
 
 Release 0.12 (2014-07-06)
@@ -1608,7 +1594,7 @@
   - New reStructuredText "code" role and directive and "code" option
     of the "include" directive with syntax highlighting by Pygments_.
   - Fix parse_option_marker for option arguments containing ``=``.
-  - Fix [ 2993756 ]: import Python Imaging Library's Image module
+  - Fix [ 2993756 ] import Python Imaging Library's Image module
     via ``import PIL`` as starting with PIL 1.2,
     "PIL lives in the PIL namespace only" (announcement__).
 
@@ -4390,10 +4376,12 @@
 .. _math_output: docs/user/config.html#math-output
 .. _output: docs/user/config.html#output
 .. _output_encoding: docs/user/config.html#output-encoding
+.. _prune: docs/user/config.html#prune
 .. _raw_enabled: docs/user/config.html#raw-enabled
 .. _reference_label: docs/user/config.html#reference-label
-.. _rst_sources: docs/user/config.html#rst-sources
+.. _root_prefix: docs/user/config.html#root-prefix
 .. _smart_quotes: docs/user/config.html#smart-quotes
+.. _sources: docs/user/config.html#sources
 .. _strip_classes: docs/user/config.html#strip-classes
 .. _strip_elements_with_classes: docs/user/config.html#strip-elements-with-classes
 .. _stylesheet: docs/user/config.html#stylesheet
@@ -4401,6 +4389,8 @@
 .. _stylesheet_path: docs/user/config.html#stylesheet-path
 .. _syntax_highlight: docs/user/config.html#syntax-highlight
 .. _table_style: docs/user/config.html#table-style
+.. _theme: docs/user/config.html#theme
+.. _theme_url: docs/user/config.html#theme-url
 .. _traceback: docs/user/config.html#traceback
 .. _use_bibtex: docs/user/config.html#use-bibtex
 .. _use_latex_abstract: docs/user/config.html#use-latex-abstract
@@ -4408,7 +4398,12 @@
 .. _use_latex_toc: docs/user/config.html#use-latex-toc
 .. _view_mode: docs/user/config.html#view-mode
 
+.. _<meta>: docs/ref/doctree.html#meta
+.. _<image>: docs/ref/doctree.html#image
+.. _<inline>: docs/ref/doctree.html#inline
+.. _<literal>: docs/ref/doctree.html#literal
 
+
 ..
    Local Variables:
    mode: indented-text

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/RELEASE-NOTES.txt	2024-03-14 16:34:48 UTC (rev 9561)
@@ -170,8 +170,8 @@
 .. _buildhtml.py: docs/user/tools.html#buildhtml-py
 
 
-Release 0.21 (unpublished)
-==========================
+Release 0.21.rc1 (unpublished)
+==============================
 
 * General:
 

Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/docs/ref/rst/directives.txt	2024-03-14 16:34:48 UTC (rev 9561)
@@ -314,7 +314,6 @@
 .. [#] SVG images are directly included, other images are base64_ encoded
    and included as a `data URI`_.
 
-.. _image_loading: ../../user/config.html#image-loading
 .. _lazy loading attribute: https://html.spec.whatwg.org/multipage/
     urls-and-fetching.html#lazy-loading-attributes
 .. _base64: https://en.wikipedia.org/wiki/Base64
@@ -573,7 +572,7 @@
 :Directive Arguments: one, optional (formal language)
 :Directive Options: `see below <code options_>`__
 :Directive Content: Becomes the body of the literal block.
-:Configuration Setting: syntax_highlight_.
+:Configuration Setting: syntax_highlight_
 
 The "code" directive constructs a literal block. If the code language is
 specified, the content is parsed by the Pygments_ syntax highlighter and
@@ -611,7 +610,6 @@
 
 .. _sandbox/stylesheets: https://docutils.sourceforge.io/sandbox/stylesheets/
 .. _Pygments: https://pygments.org/
-.. _syntax_highlight: ../../user/config.html#syntax-highlight
 .. _supported languages and markup formats: https://pygments.org/languages/
 
 
@@ -647,7 +645,6 @@
 For inline formulas, use the `"math" role`_.
 
 .. _LaTeX math syntax: ../../ref/rst/mathematics.html
-.. _math_output: ../../user/config.html#math-output
 
 
 Rubric
@@ -850,6 +847,7 @@
 :Directive Arguments: one, optional (table title)
 :Directive Options: `see below <table options_>`__
 :Directive Content: A normal `reStructuredText table`_.
+:Configuration Setting: table_style_
 
 The "table" directive is used to associate a
 title with a table or specify options, e.g.::
@@ -902,10 +900,6 @@
        values "colwidths-auto"/"colwidths-grid").
 
 
-.. _reStructuredText table: restructuredtext.html#tables
-.. _table_style: ../../user/config.html#table-style
-
-
 .. _csv-table:
 
 CSV Table
@@ -919,6 +913,7 @@
 :Directive Options: `see below <csv-table options_>`__
 :Directive Content: A CSV (comma-separated values) table
                     or (with the `file`_ or `url`_ options) none.
+:Configuration Settings: table_style_, file_insertion_enabled_
 
 .. WARNING::
 
@@ -1052,6 +1047,7 @@
 :Directive Arguments: one, optional (table title)
 :Directive Options: `see below <list-table options_>`__
 :Directive Content: A uniform two-level bullet list.
+:Configuration Setting: table_style_
 
 (This is an initial implementation; `further ideas`__ may be implemented
 in the future.)
@@ -1135,6 +1131,7 @@
 :Directive Arguments: one, optional: title
 :Directive Options: `see below <contents options_>`__
 :Directive Content: none
+:Configuration Settings: toc_backlinks_, use_latex_toc_, generate_oowriter_toc_
 
 The "contents" directive generates a table of contents (TOC) in
 a `\<topic>`_ element.  Topics, and therefore tables of contents,
@@ -1242,9 +1239,7 @@
     numbering for a document split over several source files.  The
     default is 1.
 
-.. _sectnum_xform: ../../user/config.html#sectnum-xform
 
-
 .. _header:
 .. _footer:
 
@@ -1543,8 +1538,6 @@
    The "include" directive represents a potential security hole.  It
    can be disabled with the "file_insertion_enabled_" runtime setting.
 
-   .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
-
 The "include" directive reads a text file. The directive argument is
 the path to the file to be included, relative to the document containing
 the directive. Unless the options ``literal``, ``code``, or ``parser``
@@ -1591,8 +1584,6 @@
     The text encoding of the external file.
     Defaults to the document's input_encoding_.
 
-    .. _input_encoding: ../../user/config.html#input-encoding
-
 ``end-before`` : text_
     Only the content before the first occurrence of the specified *text*
     in the external data file (but after any ``start-after`` text)
@@ -1629,8 +1620,6 @@
     where a negative value prevents expansion of hard tabs.
     Defaults to the tab_width_ configuration setting.
 
-    .. _tab_width: ../../user/config.html#tab-width
-
 With ``code`` or ``literal`` the common options class_ and name_
 are recognized as well.
 
@@ -1652,7 +1641,7 @@
 :Directive Options: `see below <raw options_>`__
 :Directive Content: Stored verbatim, uninterpreted.
                     None (empty) if a ``file`` or ``url`` option given.
-:Configuration Setting: raw_enabled_
+:Configuration Settings: raw_enabled_, file_insertion_enabled_
 
 .. WARNING::
 
@@ -1661,8 +1650,6 @@
    Insertion of external files can be disabled with the
    "file_insertion_enabled_" runtime setting.
 
-   .. _raw_enabled: ../../user/config.html#raw-enabled
-
 .. Caution::
 
    The "raw" directive is a stop-gap measure allowing the author to
@@ -2114,10 +2101,11 @@
 .. class:: field-indent-13em
 
 :Directive Type: "title"
-:Doctree Element: none (sets the document's `title attribute`_)
+:Doctree Element: sets the `\<document>`_ element's `title attribute`_)
 :Directive Arguments: one, required (the title text)
 :Directive Options: none
 :Directive Content: none
+:Configuration Setting: `title <"title" configuration setting_>`__
 
 The "title" directive specifies the document title as metadata, which
 does not become part of the document body. It overrides the
@@ -2125,10 +2113,7 @@
 setting`_. For example, in HTML output the metadata document title
 appears in the title bar of the browser window.
 
-.. _document title: restructuredtext.html#document-title
-.. _"title" configuration setting: ../../user/config.html#title
 
-
 Restructuredtext-Test-Directive
 ===============================
 
@@ -2248,6 +2233,7 @@
 
 .. _reStructuredText Markup Specification: restructuredtext.html
 .. _Directives: restructuredtext.html#directives
+.. _document title: restructuredtext.html#document-title
 .. _escaping mechanism: restructuredtext.html#escaping-mechanism
 .. _external hyperlink targets:
     restructuredtext.html#external-hyperlink-targets
@@ -2257,6 +2243,7 @@
 .. _percentage: restructuredtext.html#percentage-units
 .. _reference name:
 .. _reference names: restructuredtext.html#reference-names
+.. _reStructuredText table: restructuredtext.html#tables
 
 .. _reStructuredText Interpreted Text Roles:
 .. _interpreted text role: roles.html
@@ -2264,9 +2251,24 @@
 .. _"math" role: roles.html#math
 .. _"raw" role: roles.html#raw
 
-.. _The Docutils Document Tree: ../doctree.html
+.. Docutils Configuration
+.. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
+.. _generate_oowriter_toc: ../../user/config.html#generate-oowriter-toc
+.. _image_loading: ../../user/config.html#image-loading
+.. _input_encoding: ../../user/config.html#input-encoding
+.. _math_output: ../../user/config.html#math-output
+.. _raw_enabled: ../../user/config.html#raw-enabled
+.. _sectnum_xform: ../../user/config.html#sectnum-xform
+.. _syntax_highlight: ../../user/config.html#syntax-highlight
+.. _tab_width: ../../user/config.html#tab-width
+.. _table_style: ../../user/config.html#table-style
+.. _"title" configuration setting: ../../user/config.html#title
+.. _toc_backlinks: ../../user/config.html#toc-backlinks
+.. _use_latex_toc: ../../user/config.html#use-latex-toc
+
 .. _reStructuredText Standard Definition Files: definitions.html
 
+.. _The Docutils Document Tree: ../doctree.html
 .. _identifier keys: ../doctree.html#ids-type
 .. _inline elements: ../doctree.html#inline-elements
 .. _class names: ../doctree.html#classname
@@ -2286,6 +2288,7 @@
 .. _<container>: ../doctree.html#container
 .. _<danger>: ../doctree.html#danger
 .. _<decoration>: ../doctree.html#decoration
+.. _<document>: ../doctree.html#document
 .. _<error>: ../doctree.html#error
 .. _<figure>: ../doctree.html#figure
 .. _<footer>: ../doctree.html#footer

Modified: trunk/docutils/docs/ref/rst/restructuredtext.txt
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.txt	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/docs/ref/rst/restructuredtext.txt	2024-03-14 16:34:48 UTC (rev 9561)
@@ -25,7 +25,7 @@
 constructs to indicate the structure of a document.  These constructs
 are equally easy to read in raw and processed forms.  This document is
 itself an example of reStructuredText (raw, if you are reading the
-text file, or processed, if you are reading an HTML document, for
+`text file`__, or processed, if you are reading an HTML document, for
 example).  The reStructuredText parser is a component of Docutils_.
 
 Simple, implicit markup is used to indicate special constructs, such
@@ -45,6 +45,7 @@
 `Literal blocks`_ (in which no markup processing is done) are used for
 examples throughout this document, to illustrate the plaintext markup.
 
+__ restructuredtext.txt
 
 .. contents::
 

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/docs/user/config.txt	2024-03-14 16:34:48 UTC (rev 9561)
@@ -366,7 +366,7 @@
 as external attributes (with "internal:" namespace prefix).
 Values are appended. [#append-values]_
 
-*Default*: ``[]``.
+*Default*: empty list.
 *Option*: ``--expose-internal-attribute`` (hidden, for development use only).
 
 
@@ -584,7 +584,8 @@
 -----------
 
 Base directory, prepended to a filesystem path__ starting with "/" when
-including files with the "include_", "raw_", or "csv-table_" directives.
+including files with the `"include"`_, `"raw"`_, or `"csv-table"`_
+directives.
 
 Also applied when a writer converts an image URI__ to a local filesystem
 path in order to determine the image size or embed the image in the output.
@@ -603,7 +604,7 @@
 
 Enable automatic section numbering by Docutils
 (`docutils.transforms.parts.SectNum`) associated
-with the `sectnum directive`_.
+with the `"sectnum" directive`_.
 
 If disabled, section numbers might be added to the output by the
 renderer (e.g. by LaTeX or via a CSS style definition).
@@ -611,9 +612,7 @@
 :Default: True.
 :Options: ``--section-numbering``, ``--no-section-numbering``.
 
-.. _sectnum directive: ../ref/rst/directives.html#sectnum
 
-
 source_link
 -----------
 
@@ -657,7 +656,7 @@
 .. WARNING:: Some standard class values are required in order to achieve
              the expected output rendering; use with caution.
 
-*Default*: ``[]``.  *Option*: ``--strip-class``.
+*Default*: empty list.  *Option*: ``--strip-class``.
 
 
 strip_comments
@@ -679,7 +678,7 @@
 .. WARNING:: Potentially dangerous: may lead to an invalid document tree
    and subsequent writer errors.  Use with caution.
 
-*Default*: ``[]``.  *Option*: ``--strip-elements-with-class``.
+*Default*: empty list.  *Option*: ``--strip-elements-with-class``.
 
 
 title
@@ -697,8 +696,6 @@
 :Option:  ``--title``.
 
 .. _title attribute: ../ref/doctree.html#title-attribute
-.. _document title: ../ref/rst/restructuredtext.html#document-title
-.. _"title" directive: ../ref/rst/directives.html#metadata-document-title
 
 
 toc_backlinks
@@ -705,7 +702,7 @@
 -------------
 
 Enable backlinks from section titles to table of contents entries
-("entry"), to the top of the ToC ("top"), or disable ("none").
+("entry"), to the top of the ToC ("top"), or disable (False).
 
 :Default: "entry".
 :Options: ``--toc-entry-backlinks``, ``--toc-top-backlinks``,
@@ -745,9 +742,9 @@
 file_insertion_enabled
 ----------------------
 
-Enable directives inserting the contents of
-external files, such as "include_" directive
-or the "raw_" and "csv-table_" directives with option "url" or "file".
+Enable directives inserting the contents of external files,
+such as `"include"`_ directive or the `"raw"`_ and `"csv-table"`_
+directives with option "url" or "file".
 A "warning" system message (including the directive text) is inserted
 instead.  (See also raw_enabled_ for another security-relevant setting.)
 
@@ -754,15 +751,11 @@
 :Default: True.
 :Options: ``--file-insertion-enabled``, ``--no-file-insertion``.
 
-.. _include: ../ref/rst/directives.html#include
-.. _raw: ../ref/rst/directives.html#raw
-.. _csv-table: ../ref/rst/directives.html#csv-table
 
-
 line_length_limit
 -----------------
 
-Maximal number of characters in an input line or `substitution`_
+Maximal number of characters in an input line or `"substitution"`_
 definition. To prevent extraordinary high processing times or memory
 usage for certain input constructs, a "warning" system message is
 inserted instead.
@@ -772,13 +765,11 @@
 
 New in Docutils 0.17.
 
-.. _substitution: ../ref/rst/directives.html#substitution
 
-
 raw_enabled
 -----------
 
-Enable the "raw_" directive.  A "warning" system message
+Enable the `"raw" directive`_.  A "warning" system message
 (including the directive text) is inserted instead.  See also
 file_insertion_enabled_ for another security-relevant setting.
 
@@ -901,7 +892,7 @@
 
 syntax_highlight
 ~~~~~~~~~~~~~~~~
-Token type names used by Pygments_ when parsing contents of the code_
+Token type names used by Pygments_ when parsing contents of the `"code"`_
 directive and role.
 
 Supported values:
@@ -915,7 +906,6 @@
 *Default*: "long".  *Option*: ``--syntax-highlight``.
 
 .. _Pygments: https://pygments.org/
-.. _code: ../ref/rst/directives.html#code
 .. _Pygments-generated stylesheets:
    https://pygments.org/docs/cmdline/#generating-styles
 
@@ -1107,7 +1097,6 @@
 :Default: True.
 :Options: ``--compact-lists``, ``--no-compact-lists``.
 
-.. _"class" directive: ../ref/rst/directives.html#class
 
 compact_field_lists
 ~~~~~~~~~~~~~~~~~~~
@@ -1158,7 +1147,7 @@
 
 math_output
 ~~~~~~~~~~~
-The format of mathematical content (`math directive`_ and role) in
+The format of mathematical content (`"math" directive`_ and role) in
 the output document. Supported values are (case insensitive):
 
 HTML:
@@ -1256,7 +1245,6 @@
           to "MathML" in Docutils 0.22.
 :Option:  ``--math-output``.
 
-.. _math directive: ../ref/rst/directives.html#math
 .. _MathJax: http://www.mathjax.org/
 .. _MathML: https://www.w3.org/TR/MathML/
 .. _blahtexml: http://gva.noekeon.org/blahtexml/
@@ -1275,7 +1263,7 @@
 Overrides also stylesheet_path_. [#override]_
 See also `stylesheet [latex writers]`_.
 
-*Default*: ``[]``.  *Option*: ``--stylesheet``.
+*Default*: empty list.  *Option*: ``--stylesheet``.
 
 
 .. _stylesheet_dirs:
@@ -1347,16 +1335,14 @@
 :colwidths-auto:
     Delegate the determination of table column widths to the back-end
     (leave out the ``<colgroup>`` column specification).
-    Overridden by the "widths" option of the `table directive`_.
+    Overridden by the "widths" option of the `"table" directive`_.
 :colwidths-grid:
     Write column widths determined from the source to the HTML file.
-    Overridden by the "widths" option of the `table directive`_.
+    Overridden by the "widths" option of the `"table" directive`_.
 
 *Default*: "".  *Option*: ``--table-style``.
 
-.. _table directive: ../ref/rst/directives.html#table
 
-
 .. _template [html writers]:
 
 template
@@ -1469,7 +1455,6 @@
 
 New in Docutils 0.18.
 
-.. _"image" directive: ../ref/rst/directives.html#image
 .. _lazy loading attribute: https://html.spec.whatwg.org/multipage/
     urls-and-fetching.html#lazy-loading-attributes
 
@@ -1741,7 +1726,7 @@
 table width and keeps the ratio of specified column widths.
 
 Custom table and/or column widths can be set with the respective options
-of the `table directive`_. See also `Generating LaTeX with Docutils`__.
+of the `"table" directive`_. See also `Generating LaTeX with Docutils`__.
 
 :Default: True (will change to False in Docutils 1.0).
 :Options: ``--legacy-column-widths``, ``--new-column-widths``.
@@ -1763,13 +1748,11 @@
 :Default: "" (use "alltt" with quoting of whitespace and special chars).
 :Option:  ``--literal-block-env``.
 
-.. [#] A <literal-block> element originating from a `parsed literal`_ or
-   code_ directive may contain inline elements. LaTeX' verbatim-like
+.. [#] A <literal-block> element originating from a `"parsed-literal"`_ or
+   `"code"`_ directive may contain inline elements. LaTeX' verbatim-like
    environments cannot be used in this case.
 
-.. _parsed literal: ../ref/rst/directives.html#parsed-literal
 
-
 reference_label
 ~~~~~~~~~~~~~~~
 Per default the LaTeX writer uses ``\hyperref`` for `hyperlink
@@ -1836,7 +1819,7 @@
 extension) or ``\input`` (any other extension).
 LaTeX will search the specified files in the `TeX input path`_.
 
-*Default*: ``[]``.  *Option*: ``--stylesheet``.
+*Default*: empty list.  *Option*: ``--stylesheet``.
 
 __ `stylesheet_path [latex writers]`_
 __ `embed_stylesheet [latex writers]`_
@@ -1875,7 +1858,7 @@
 
 For files in the `TeX input path`_, the stylesheet__  option is recommended.
 
-*Default*: ``[]``.  *Option*: ``--stylesheet-path``.
+*Default*: empty list.  *Option*: ``--stylesheet-path``.
 
 .. _<destination>: tools.html#usage-pattern
 __ `stylesheet_dirs [latex writers]`_
@@ -1922,7 +1905,7 @@
    Name, values, and behaviour may change in future versions or the
    option may be removed.
 
-*Default*: ``[]`` (don't use BibTeX).  *Option* ``--use-bibtex``.
+*Default*: empty list (don't use BibTeX).  *Option* ``--use-bibtex``.
 
 use_latex_abstract
 ~~~~~~~~~~~~~~~~~~
@@ -2192,7 +2175,7 @@
 Source files with matching filename are silently ignored.
 Values are appended. [#append-values]_
 
-*Default*: ``[]``.  *Option*: ``--ignore``.
+*Default*: empty list.  *Option*: ``--ignore``.
 
 prune
 ~~~~~
@@ -2210,8 +2193,7 @@
 The default patterns skip auxiliary directories from Python or
 popular version control tools anywhere [#]_.
 
-:Default: ``['/*/.hg', '/*/.bzr', '/*/.git', '/*/.svn',
-          '/*/.venv', '/*/__pycache__']``.
+:Default: ``/*/.hg:/*/.bzr:/*/.git:/*/.svn:/*/.venv:/*/__pycache__``.
 :Option:  ``--prune``.
 
 .. [#] The leading "/" prevents expansion with `pwd`;
@@ -2230,7 +2212,7 @@
 Values in configuration files overwrite the default and are
 overwritten by the command line option.
 
-*Default*: ``['*.rst', '*.txt']``.  *Option*: ``--rst-sources``.
+*Default*: ``*.rst:*.txt``.  *Option*: ``--rst-sources``.
 
 New in Docutils 0.21.
 
@@ -2363,7 +2345,7 @@
 (``buildhtml.py`` front end.)  List of paths to source
 directories, set from positional arguments.
 
-*Default* current working directory (None).  No command-line options.
+*Default*: None (current working directory).  No command-line options.
 
 _disable_config
 ~~~~~~~~~~~~~~~
@@ -2428,11 +2410,26 @@
 
 .. References
 
-.. _runtime settings:
-.. _Docutils Runtime Settings: ../api/runtime-settings.html
+.. _Docutils Runtime Settings:
+.. _runtime settings: ../api/runtime-settings.html
 
-.. _table of contents: ../ref/rst/directives.html#contents
+.. RestructuredText Directives
+.. _"class" directive: ../ref/rst/directives.html#class
+.. _"code": ../ref/rst/directives.html#code
+.. _"csv-table": ../ref/rst/directives.html#csv-table
+.. _"image" directive: ../ref/rst/directives.html#image
+.. _"include": ../ref/rst/directives.html#include
+.. _"math" directive: ../ref/rst/directives.html#math
+.. _"parsed-literal": ../ref/rst/directives.html#parsed-literal
+.. _"raw":
+.. _"raw" directive: ../ref/rst/directives.html#raw
+.. _"sectnum" directive: ../ref/rst/directives.html#sectnum
+.. _"substitution": ../ref/rst/directives.html#substitution
+.. _"table" directive: ../ref/rst/directives.html#table
+.. _"title" directive: ../ref/rst/directives.html#metadata-document-title
+.. _table of contents: ../ref/rst/directives.html#table-of-contents
 
+.. RestructuredText Markup Specification
 .. _abstract:
 .. _bibliographic field list:
 .. _bibliographic fields:
@@ -2440,6 +2437,7 @@
 .. _block quote: ../ref/rst/restructuredtext.html#block-quotes
 .. _bullet lists: ../ref/rst/restructuredtext.html#bullet-lists
 .. _citations: ../ref/rst/restructuredtext.html#citations
+.. _document title: ../ref/rst/restructuredtext.html#document-title
 .. _enumerated lists: ../ref/rst/restructuredtext.html#enumerated-lists
 .. _field lists: ../ref/rst/restructuredtext.html#field-lists
 .. _field names: ../ref/rst/restructuredtext.html#field-names

Modified: trunk/docutils/docs/user/slide-shows.txt
===================================================================
--- trunk/docutils/docs/user/slide-shows.txt	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/docs/user/slide-shows.txt	2024-03-14 16:34:48 UTC (rev 9561)
@@ -324,7 +324,7 @@
    .. container:: handout
 
       The ``--no-toc-backlinks`` option is the default for the S5/HTML
-      writer (``toc_backlinks=0`` setting).  Other values for this
+      writer (``toc_backlinks=False`` setting).  Other values for this
       setting will change the CSS class of headings such that they
       won't show up correctly in the slide show.
 

Modified: trunk/docutils/docutils/parsers/commonmark_wrapper.py
===================================================================
--- trunk/docutils/docutils/parsers/commonmark_wrapper.py	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/docutils/parsers/commonmark_wrapper.py	2024-03-14 16:34:48 UTC (rev 9561)
@@ -18,8 +18,8 @@
 parser packages:
 
 :pycmark:       https://pypi.org/project/pycmark/
-:myst:          https://pypi.org/project/pycmark/
-:recommonmark:  https://pypi.org/project/pycmark/ (unmaintained, deprecated)
+:myst:          https://pypi.org/project/myst-docutils/
+:recommonmark:  https://pypi.org/project/recommonmark/ (deprecated)
 
 The first parser class that can be successfully imported is mapped to
 `commonmark_wrapper.Parser`.

Modified: trunk/docutils/docutils/utils/math/mathml_elements.py
===================================================================
--- trunk/docutils/docutils/utils/math/mathml_elements.py	2024-03-14 10:30:39 UTC (rev 9560)
+++ trunk/docutils/docutils/utils/math/mathml_elements.py	2024-03-14 16:34:48 UTC (rev 9561)
@@ -215,8 +215,8 @@
         specified encoding. The XML default encoding is UTF-8, any other
         encoding must be specified in an XML document header.
 
-        Name and encoding handling match `xml.dom.minidom.Node.toxml()`;
-        `etree.Element.tostring()` returns `bytes` by default.
+        Name and encoding handling match `xml.dom.minidom.Node.toxml()`
+        while `etree.Element.tostring()` returns `bytes` by default.
         """
         xml = ET.tostring(self, encoding or 'unicode',
                           short_empty_elements=False)

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.