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

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

Revision: 10266
          http://sourceforge.net/p/docutils/code/10266
Author:   milde
Date:     2025-11-28 13:52:09 +0000 (Fri, 28 Nov 2025)
Log Message:
-----------
Documentation update and fixes.

Announce upcoming changes.

The "raw" directive can be used in substitution definitions.

Hide documentation for deprecated "line-block" directive in a
details/disclosure list.

Small edits for improved clarity.

Modified Paths:
--------------
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/ref/doctree.rst
    trunk/docutils/docs/ref/rst/directives.rst
    trunk/docutils/docs/ref/rst/restructuredtext.rst
    trunk/docutils/docs/user/config.rst
    trunk/docutils/docs/user/rst/demo.rst
    trunk/docutils/docutils/writers/html5_polyglot/__init__.py
    trunk/docutils/docutils/writers/latex2e/__init__.py

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-11-28 13:52:09 UTC (rev 10266)
@@ -56,9 +56,6 @@
 * The <footnote> element's first child (<label>) will become mandatory
   in Docutils 1.0.
 
-* The "rst" parser will warn if a `"figure"`_ directive is missing both
-  caption and legend in Docutils 1.0.
-
 * Inline `\<target>`_ elements and <target> elements with content will be
   deprecated in Docutils 1.0 and invalid in Docutils 2.0.
   The "rst" parser will use <inline> elements for inline targets
@@ -74,6 +71,15 @@
   The rST parser will handle a `doctest block`_ similar to a "code" directive
   with language "pycon" (Python console) and generate a <literal_block>.
 
+Parsers
+-------
+
+* The "rst" parser will warn, if a directive that does not take arguments
+  has content above and below directive options in Docutils 0.23.
+
+* The "rst" parser will warn if a `"figure"`_ directive is missing both
+  caption and legend in Docutils 1.0.
+
 Writers
 -------
 
@@ -93,6 +99,11 @@
 
 * "html5" writer:
 
+  - If a section title has several IDs, use the last one (from the first
+    `explicit target`__) as self-link_ in Docutils 0.23.
+
+    __ docs/ref/rst/restructuredtext.html#explicit-hyperlink-targets
+
   - Move attribution behind the blockquote to comply with the
     `"HTML living standard"`__ [#]_ and adapt CSS stylesheets
     in Docutils 1.0.
@@ -107,8 +118,9 @@
 
 * "latex2e" writer:
 
-  - Only write ``\label`` commands for IDs that are referenced in the
-    current document in Docutils 0.23.
+  - Only write ``\label`` commands for explicit IDs and IDs that are
+    referenced in the current document (i.e. not for un-referenced
+    section titles) in Docutils 0.23.
 
   - Change default of use_latex_citations_ setting to True
     in Docutils 1.0.
@@ -1560,6 +1572,7 @@
 .. _output_path: docs/user/config.html#output-path
 .. _reference_label: docs/user/config.html#reference-label
 .. _root_prefix: docs/user/config.html#root-prefix
+.. _self-link: docs/user/config.html#section-self-link
 .. _SmartQuotes: docs/user/config.html#smart-quotes
 .. _sources: docs/user/config.html#sources
 .. _use_latex_citations: docs/user/config.html#use-latex-citations

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/ref/doctree.rst	2025-11-28 13:52:09 UTC (rev 10266)
@@ -3854,8 +3854,9 @@
 :Children:   one or more `body elements`_
 :Attributes: backrefs_, level_, line_, type_, and the `common attributes`_.
 
-In Docutils, the generation of system messages can be configured with the
-`"report_level"`_ setting.
+In Docutils, system messages with a level lower than the
+`"report_level"`_ setting are removed by the `universal.FilterMessages`
+transform_.
 
 Examples
 --------
@@ -4249,8 +4250,9 @@
 
 :Category:   `Structural Elements`_
 
-:Analogues:  <topic> is analogous to the DocBook_ <simplesect> element
-             and the HTML_ <aside> element.
+:Analogues:  <topic> is analogous to the HTML_ <aside> element.
+             The DocBook_ <simplesect> element is similar, but you cannot
+             place `body elements`_ after a <simplesect>.
 
 :Processing: A <topic> element should be set off from the rest of the
              document somehow, such as with indentation or a border.
@@ -5794,7 +5796,7 @@
   .. _namespace:
 
   Almost all elements in a document share a common *namespace*
-  for reference names, comparison ignores case.
+  for reference names and match them ignoring case.
   Only `\<substitution_definition>`_ and `\<substitution_reference>`_
   elements use a distinct namespace with `case-sensitive but forgiving`_
   matching of reference names.

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/ref/rst/directives.rst	2025-11-28 13:52:09 UTC (rev 10266)
@@ -453,8 +453,8 @@
 A topic is like a block quote with a title, or a self-contained
 section with no subsections.  Use the "topic" directive to indicate a
 self-contained idea that is separate from the flow of the document.
-Topics may occur anywhere a section or transition may occur and
-in sidebars.  Body elements and topics may not contain nested topics.
+Topics may be nested in the document, a section, or a
+sidebar_.  Body elements and topics may not contain topics.
 
 The directive's sole argument is interpreted as the topic title; the
 next line must be blank.  All subsequent lines make up the topic body,
@@ -511,13 +511,6 @@
 Line Block
 ==========
 
-.. admonition:: Deprecated
-
-   The "line-block" directive is deprecated.  Use the `line block
-   syntax`_ instead.
-
-   .. _line block syntax: restructuredtext.html#line-blocks
-
 .. class:: field-indent-13em
 
 :Directive Type: "line-block"
@@ -526,28 +519,31 @@
 :Directive Options: `class <class option_>`_, name_
 :Directive Content: Becomes the body of the line block.
 
-The "line-block" directive constructs an element where line breaks and
-initial indentation is significant and inline markup is supported.  It
-is equivalent to a `parsed literal block`_ with different rendering:
-typically in an ordinary serif typeface instead of a
-typewriter/monospaced face, and not automatically indented.  (Have the
-line-block directive begin a block quote to get an indented line
-block.)  Line blocks are useful for address blocks and verse (poetry,
-song lyrics), where the structure of lines is significant.  For
-example, here's a classic::
+.. class:: details
 
-    "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
-    Ewan McTeagle (for Lassie O'Shea):
+**Deprecated.**  Use the `line block syntax`_ instead.
+  The "line-block" directive constructs an element where line breaks and
+  initial indentation is significant and inline markup is supported.  It
+  is comparable to a `parsed literal block`_ with different rendering:
+  typically in an ordinary serif typeface instead of a
+  typewriter/monospaced face, and not automatically indented.  (Have the
+  line-block directive begin a block quote to get an indented line
+  block.)  Line blocks are useful for address blocks and verse (poetry,
+  song lyrics), where the structure of lines is significant.  For
+  example, here's a classic::
 
-        .. line-block::
+      "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
+      Ewan McTeagle (for Lassie O'Shea):
 
-            Lend us a couple of bob till Thursday.
-            I'm absolutely skint.
-            But I'm expecting a postal order and I can pay you back
-                as soon as it comes.
-            Love, Ewan.
+          .. line-block::
 
+              Lend us a couple of bob till Thursday.
+              I'm absolutely skint.
+              But I'm expecting a postal order and I can pay you back
+                  as soon as it comes.
+              Love, Ewan.
 
+
 .. _parsed-literal:
 
 Parsed Literal Block
@@ -1171,9 +1167,9 @@
 :Directive Content: none
 :Configuration Settings: toc_backlinks_, use_latex_toc_, generate_oowriter_toc_
 
-The "contents" directive generates a table of contents (TOC) in
+The "contents" directive generates a table of contents (ToC) in
 a `\<topic>`_ element.  Topics, and therefore tables of contents,
-may occur anywhere a section or transition may occur and in sidebars.
+may be nested in the document, a section, or a sidebar_.
 Body elements and topics may not contain tables of contents.
 
 Here's the directive in its simplest form::
@@ -1284,6 +1280,8 @@
 Document Header & Footer
 ========================
 
+.. class:: field-indent-13em
+
 :Directive Types: "header" and "footer"
 :Doctree Elements: `\<decoration>`_, `\<header>`_, `\<footer>`_
 :Directive Arguments: none
@@ -1411,18 +1409,13 @@
  Directives for Substitution Definitions
 -----------------------------------------
 
-The directives introduced in this section may be used in
-`substitution definitions`_.  They may not be used directly,
-in standalone context (except for the image_ directive).
+This section lists directives that may be used in `substitution definitions`_.
 
-.. _substitution definitions:
-.. _substitution definition: restructuredtext.html#substitution-definitions
 
-
 Inline Images
 =============
 
-The `image`_ directive can be used both, stand-alone (to define
+The "`image`_" directive can be used both, stand-alone (to define
 block-level images) and in substitution definitions to define
 inline images. [#no-inline-name]_
 
@@ -1430,6 +1423,15 @@
                      a substitution definition. [#substitution-limits]_
 
 
+Inline Raw
+==========
+
+The "raw_" directive can be used stand-alone and in substitution definitions.
+
+"Raw data pass-through" in inline context is also possible with
+a `custom role`_ derived from the `"raw" role`_.
+
+
 .. _replace:
 
 Replacement Text
@@ -1464,10 +1466,11 @@
     .. |Python| replace:: Python, *the* best language around
     .. _Python: https://www.python.org/
 
-.. [#substitution-limits] As a substitution may be referenced more than
-   one time, a substitution definition may not contain references to
-   `anonymous hyperlinks`_, `auto-numbered`_ or `auto-symbol`_ footnotes
-   and no `hyperlink targets`__ (names and identifiers must be unique).
+.. [#substitution-limits]
+   A substitution definition may not contain references to `anonymous
+   hyperlinks`_, `auto-numbered`_ or `auto-symbol`_ footnotes and no
+   `hyperlink targets`__ because a substitution may be referenced more
+   than once but names and identifiers must be unique.
 
    __ restructuredtext.html#inline-internal-targets
 
@@ -1768,6 +1771,8 @@
 
 Inline equivalents of the "raw" directive can be defined via
 `custom interpreted text roles`_ derived from the `"raw" role`_.
+The "raw" directive can also be used directly in a `substitution
+definition`_.
 
 .. _raw options:
 
@@ -1788,8 +1793,8 @@
 .. _class directive:
 .. _rst-class:
 
-Class
-=====
+Setting Class Attributes
+========================
 
 .. class:: field-indent-13em
 
@@ -1949,6 +1954,7 @@
 
 
 .. _role:
+.. _custom role:
 
 Custom Interpreted Text Roles
 =============================
@@ -2342,10 +2348,13 @@
 .. _hyperlink references: restructuredtext.html#hyperlink-references
 .. _hyperlink targets:
 .. _hyperlink target: restructuredtext.html#hyperlink-targets
+.. _line block syntax: restructuredtext.html#line-blocks
 .. _reference name:
 .. _reference names: restructuredtext.html#reference-names
 .. _section title style hierarchy: restructuredtext.html#title-styles
 .. _simple table: restructuredtext.html#simple-tables
+.. _substitution definitions:
+.. _substitution definition: restructuredtext.html#substitution-definitions
 .. _supported length units: restructuredtext.html#length-units
 
 .. _reStructuredText Interpreted Text Roles:

Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-11-28 13:52:09 UTC (rev 10266)
@@ -88,7 +88,7 @@
 
          1. This is an enumerated list.
 
-         2. Enumerators may be arabic numbers, letters, or roman
+         2. Enumerators may be arabic numerals, letters, or roman
             numerals.
 
   3. `Definition lists`_::
@@ -204,7 +204,7 @@
 
   - Comments_::
 
-        .. Comments begin with two dots and a space.  Anything may
+        .. Comments begin with two dots and whitespace.  Anything may
            follow, except for the syntax of footnotes/citations,
            hyperlink targets, directives, or substitution definitions.
 
@@ -359,7 +359,7 @@
   itself. (A literal backslash can be specified by two backslashes in a
   row -- the first backslash escapes the second. [#caveat]_)
 
-* Escaped whitespace characters are removed from the output document
+* _`Escaped whitespace` characters are removed from the output document
   together with the escaping backslash. This allows for `character-level
   inline markup`_.
 
@@ -743,7 +743,7 @@
 Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists,
 but use enumerators instead of bullets.  An enumerator consists of an
 enumeration sequence member and formatting, followed by whitespace.
-The following enumeration sequences are recognized:
+The following *enumeration sequences* are recognized:
 
 - arabic numerals: 1, 2, 3, ... (no upper limit).
 - uppercase alphabet characters: A, B, C, ..., Z.
@@ -753,10 +753,10 @@
 
 In addition, the auto-enumerator, ``#``, may be used to automatically
 enumerate a list.  Auto-enumerated lists may begin with explicit
-enumeration, which sets the sequence.  Fully auto-enumerated lists use
-arabic numerals and begin with 1.
+enumeration, which sets the sequence and start value.
+Fully auto-enumerated lists use arabic numerals and begin with 1.
 
-The following formatting types are recognized:
+The following *formatting types* are recognized:
 
 - suffixed with a period: ``1.``, ``A.``, ``a.``, ``I.``, ``i.``.
 - surrounded by parentheses: ``(1)``, ``(A)``, ``(a)``, ``(I)``, ``(i)``.
@@ -1377,7 +1377,7 @@
 
         -- Sherlock Holmes
 
-A block quote may end with an attribution: a text block beginning with
+A block quote may end with an _`attribution`: a paragraph beginning with
 ``--``, ``---``, or a true em-dash, flush left within the block quote.  If
 the attribution consists of multiple lines, the left edges of the
 second and subsequent lines must align.
@@ -2299,9 +2299,14 @@
 
 The following *inline-compatible directives* are implemented in Docutils:
 
+:`"date"`_: inserts the current local date.
+
 :`"image"`_: can be used for block-level images as well as in a
              substitution definition for `inline images`_.
 
+:`"raw"`_: can be used in block-level context as well as in a
+           substitution definition.
+
 :`"replace"`_: allows simple macro substitution.
   It also provides a workaround__ for the still missing support of
   nested inline markup.
@@ -2310,8 +2315,6 @@
 
 :`"unicode"`_: converts Unicode character codes to characters.
 
-:`"date"`_: inserts the current local date.
-
 Applications may find other use cases for the substitution mechanism.
 The following are ideas that have not been implemented in Docutils.
 

Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/user/config.rst	2025-11-28 13:52:09 UTC (rev 10266)
@@ -1521,8 +1521,8 @@
 
 section_self_link
 """""""""""""""""
-Append an empty anchor element with a ``href`` to the section to
-section headings. See ``responsive.css`` for an example how this can be
+Extend section headings with an empty <a> element with a ``href`` to
+the section.  See ``responsive.css`` for an example how this can be
 styled to show a symbol allowing users to copy the section's URL.
 
 :Default: False.

Modified: trunk/docutils/docs/user/rst/demo.rst
===================================================================
--- trunk/docutils/docs/user/rst/demo.rst	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/user/rst/demo.rst	2025-11-28 13:52:09 UTC (rev 10266)
@@ -546,7 +546,7 @@
 
 Here's one:
 
-.. Comments begin with two dots and a space. Anything may
+.. Comments begin with two dots and whitespace. Anything may
    follow, except for the syntax of footnotes, hyperlink
    targets, directives, or substitution definitions.
 

Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py	2025-11-28 13:52:09 UTC (rev 10266)
@@ -388,6 +388,8 @@
     def section_title_tags(self, node):
         start_tag, close_tag = super().section_title_tags(node)
         ids = node.parent['ids']
+        # TODO: use ``ids[-1]``
+        # (IDs from explicit targets are appended to the implicit ID)
         if (ids and getattr(self.settings, 'section_self_link', None)
             and not isinstance(node.parent, nodes.document)):
             self_link = ('<a class="self-link" title="link to this section"'

Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py	2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py	2025-11-28 13:52:09 UTC (rev 10266)
@@ -2600,23 +2600,21 @@
         self.depart_inline(node)
         self.out.append('}')
 
-    # Literal blocks are used for '::'-prefixed literal-indented
-    # blocks of text, where the inline markup is not recognized,
-    # but are also the product of the "parsed-literal" directive,
-    # where the markup is respected.
+    # <literal_block> elements are used
+    # for literal blocks (where content is not parsed),
+    # for the "code" directive (where content may be parsed by Pygments), and
+    # for the "parsed-literal" directive (where rST inline markup is parsed).
     #
-    # In both cases, we want to use a typewriter/monospaced typeface.
-    # For "real" literal-blocks, we can use \verbatim, while for all
-    # the others we must use \ttfamily and \raggedright.
+    # In all cases, we want to use a monospaced typeface.
+    # If the <literal_block> contains only text, we can use a "verbatim-like"
+    # environment, for mixed content we must use \ttfamily and \raggedright.
     #
-    # We can distinguish between the two kinds by the number of
-    # siblings that compose this node: if it is composed by a
-    # single element, it's either
-    # * a real one,
-    # * a parsed-literal that does not contain any markup, or
-    # * a parsed-literal containing just one markup construct.
+    # We can distinguish between the use cases looking at the element's
+    # children: if there is a single <Text> child, it is either
+    # * a "real" literal block or
+    # * a parsed-literal that does not contain any markup.
     def is_plaintext(self, node):
-        """Check whether a node can be typeset verbatim"""
+        """Check whether `node` contains only text"""
         return (len(node) == 1) and isinstance(node[0], nodes.Text)
 
     def visit_literal_block(self, node) -> None:

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