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

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

Revision: 10166
          http://sourceforge.net/p/docutils/code/10166
Author:   milde
Date:     2025-06-16 09:45:10 +0000 (Mon, 16 Jun 2025)
Log Message:
-----------
Documentation edits.

Fixes and clarifications.

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/api/transforms.rst
    trunk/docutils/docs/ref/rst/directives.rst
    trunk/docutils/docs/user/latex.rst
    trunk/docutils/docutils/transforms/misc.py
    trunk/docutils/docutils/transforms/references.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/HISTORY.rst	2025-06-16 09:45:10 UTC (rev 10166)
@@ -37,8 +37,10 @@
   - Replace `Writer.bibtex_reference_resolver()` with a transform.
   - `LaTeXTranslator.visit_inline()` now inserts labels for the
     node's IDs.
-  - Disable "hyperref" footnote handling to avoid "empty anchor" warnings.
-  - Re-style system messages.
+  - Disable footnote handling by the "hyperref" LaTeX package (Docutils'
+    ``\DUfootnotemark`` and ``\DUfootnotetext`` macros implement
+    hyperlinks and backlinks).  Avoids "empty anchor" warnings.
+  - Fix target position and re-style system messages.
   - Don't merge paragraphs if there is a target between them.
 
 * docutils/writers/manpage.py
@@ -56,9 +58,9 @@
 
 * docutils/parsers/rst/states.py
 
-  - Remove the list`states.RSTStateMachine.memo.section_parents`
+  - Remove the `states.RSTStateMachine.memo.section_parents` cache
     (introduced in Docutils 0.22rc1) that broke 3rd-party applications
-    setting up a "mock memo".
+    employing a "mock memo".
   - Use `types.SimpleNamespace` instead of a local definition for
     the auxilliary class `states.Struct`.
 
@@ -155,7 +157,7 @@
 
   - Pass the included file's path to the parser when the
     "include" directive is used with :parser: option.
-    Enables system messages with correct source/line indication.
+    Enables system messages with correct source/line info.
 
 * docutils/parsers/rst/directives/tables.py
 
@@ -192,7 +194,7 @@
 
 * docutils/transforms/writer_aux.py
 
-  - Removed `Compound` class.
+  - Removed `Compound` transform.
 
 * docutils/transforms/references.py
 
@@ -200,7 +202,8 @@
 
 * docutils/transforms/universal.py
 
-  - `Messages` also handles "loose" system messages generated by the parser.
+  - `Messages` transform now also handles "loose" system messages
+    generated by the parser.
 
 * docutils/utils/__init__.py
 
@@ -241,10 +244,10 @@
 * docutils/writers/latex2e/__init__.py
 
   - `LaTeXTranslator.to_latex_length()`:
-    remove optional argument `pxunit` (ignored since at least 2012),
-    drop trailing zeroes from length values,
-    move XeTeX-specific code to the "xetex" writer.
     Handle CSS3 `length units`_.
+    Remove optional argument `pxunit` (ignored since at least 2012).
+    Drop trailing zeroes from length values.
+    Move XeTeX-specific code to the "xetex" writer.
   - Don't wrap references with custom reference-label_ in
     a ``\hyperref`` command.
   - Mark the main language when loading "babel".
@@ -251,10 +254,10 @@
   - Provide an "unknown_references_resolver" (cf. `docutils/TransformSpec`)
     for citation references resolved with BibTeX (cf. `use_bibtex`_ setting).
   - Support SVG image inclusion with the "svg" LaTeX package (see the
-    `stylesheet`__ configuration setting).
+    `stylesheet`__ configuration setting). Solves feature-request #83
   - Add "template" to the parts returned by `Writer.assemble_parts()`.
   - Use standard `dict` for `LaTeXTranslator.requirements`
-    and`LaTeXTranslator.fallbacks`.
+    and `LaTeXTranslator.fallbacks`.
   - Use <document> "title" attribute in pdfinfo.
   - Encode <meta> element content in pdfinfo.
   - Improve formatting of docinfo fields.
@@ -303,7 +306,7 @@
 
 * tools/rst2odt_prepstyles.py
 
-  - Removed. Use `docutils.writers.odf_odt.prepstyles`.
+  - Removed. Use ``python -m docutils.writers.odf_odt.prepstyles``.
 
 .. _length units: docs/ref/rst/restructuredtext.html#length-units
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-06-16 09:45:10 UTC (rev 10166)
@@ -173,7 +173,7 @@
   in Docutils 1.0.  Use a transform_,
   see `transforms.references.CitationReferences` for an example.
 
-* Ignore `transforms.references.DanglingReferences` and
+* Don't call `transforms.references.DanglingReferences` and
   `transforms.references.DanglingReferencesVisitor` in Docutils 1.0;
   remove them in Docutils 2.0. [rationale__]
 
@@ -186,7 +186,7 @@
 * Remove the "rawsource" argument from `nodes.Text.__init__()`
   in Docutils 2.0.
 
-* Remove attributes `nodes.Element.known_attributes`,
+* Remove the internal attributes `nodes.Element.known_attributes`,
   `nodes.Element.basic_attributes`, and `nodes.Element.local_attributes`,
   in Docutils 2.0.
 
@@ -246,12 +246,13 @@
 
 Nothing yet.
 
+
 Release 0.22rc3 (2025-06-10)
 ============================
 
 New objects
-  `transforms.references.`CitationReferences`
-     Mark citation_references as resolved if the backend (LaTeX)
+  `transforms.references.CitationReferences`
+     Mark citation_references as resolved if the backend
      uses a BibTeX database.
 
 Output changes
@@ -259,6 +260,7 @@
   manpage:
      Do not drop text of internal targets.
 
+
 Release 0.22rc2 (2025-05-22)
 ============================
 
@@ -303,13 +305,17 @@
 
 Output changes
   LaTeX:
-     Don't wrap references with custom reference-label_ in a ``\hyperref``
+     Don't wrap references with custom reference_label_ in a ``\hyperref``
      command. The "hyperref" package generates hyperlinks for labels by
-     default, so there is no change in the PDF (except for "ref*").
+     default, so there is no change in the PDF
+     (except for the starred forms like ``reference_label = \ref*``).
 
-     Stop requiring "ifthen.sty". Replace use of
-     ``\ifthenelse{\isundefined...`` with the eTeX primitive ``\ifdefined``.
+     Stop requiring "ifthen.sty". Add "ifthen" to the stylesheet__ setting
+     or replace use of ``\ifthenelse{\isundefined...`` with the eTeX
+     primitive ``\ifdefined``.
 
+     __ docs/user/config.html#stylesheet-2
+
   HTML5:
      Unitless image_ size measures__ are written as <img> "width" and
      "hight" values instead of "style" rules.  The current behaviour
@@ -320,8 +326,9 @@
 
   manpage:
      Don't UPPERCASE section headings.
-     Handle hyperlink references (see text_references_).
 
+     Handle hyperlink references (see the text_references_ setting).
+
   null:
      The "null" writer output changed from None to the empty string.
 
@@ -1505,7 +1512,7 @@
     docs/user/config.html#old-format-configuration-files
 .. _output:
 .. _output_path: docs/user/config.html#output-path
-.. _reference-label: docs/user/config.html#reference-label
+.. _reference_label: docs/user/config.html#reference-label
 .. _root_prefix: docs/user/config.html#root-prefix
 .. _SmartQuotes: docs/user/config.html#smart-quotes
 .. _sources: docs/user/config.html#sources

Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docs/api/transforms.rst	2025-06-16 09:45:10 UTC (rev 10166)
@@ -137,10 +137,10 @@
 * (t): Transform
 * (/p): Via a `\<pending>`_ element
 
-.. [#dangling] `references.DanglingReferences` will be split into a
-   transform resolving refnames__ to refids__ and a transform reporting
-   unresolved references to make space for reference-resolving transforms
-   added by extensions or applications
+.. [#dangling] `references.DanglingReferences` will be replaced by
+   separate transforms for resolving refnames__ to refids__
+   and for reporting unresolved references to make space for
+   reference-resolving transforms added by extensions or applications
    (cf. `Release Notes`__).
 
    __ ../ref/doctree.html#refname

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docs/ref/rst/directives.rst	2025-06-16 09:45:10 UTC (rev 10166)
@@ -610,7 +610,7 @@
 
 The parsing can be turned off with the syntax_highlight_ configuration
 setting and command line option or by specifying the language as
-`class <class option>`_ option instead of directive argument.
+`class <class option_>`_ option instead of directive argument.
 This also avoids warnings when Pygments_ is not installed or the language
 is not in the `supported languages and markup formats`_.
 
@@ -1317,13 +1317,20 @@
 :Directive Options: `class <class option_>`_, name_
 :Directive Content: none
 
-The "target-notes" directive creates a footnote for each external
-target in the text, and corresponding footnote references after each
-reference.  For every explicit target (of the form, ``.. _target name:
-URL``) in the text, a footnote will be generated containing the
-visible URL as content.
+The "target-notes" directive generates a list of referenced URIs.
+This ensures the information is not lost in a hardcopy.
 
+For every explicit [#]_ `external hyperlink target`_ in the document,
+the "target-notes" directive inserts a `\<footnote>`_ showing the URL
+at the place of the directive and a `\<footnote_reference>`_ after each
+matching `hyperlink reference`_.
 
+The value of the `class option`_ is passed to the generated footnote
+references.
+
+.. [#] `Embedded URIs`_ like ```this <http://example.org>`_`` are skipped.
+
+
 Footnotes
 =========
 
@@ -1640,8 +1647,8 @@
     where a negative value prevents expansion of hard tabs.
     Defaults to the tab_width_ configuration setting.
 
-With ``code`` or ``literal`` the common options `class <class option_>`_ and name_
-are recognized as well.
+With ``code`` or ``literal``, the common options `class <class option_>`_
+and name_ are recognized as well.
 
 Combining ``start-line``/``end-line`` and ``start-after``/``end-before``
 is possible.  The text markers will be searched in the specified lines
@@ -1748,13 +1755,13 @@
                     elements.
 
 The "class" directive sets the `classes attribute`_ value on its content
-or on the first immediately following [#]_ non-comment element [#]_.
+or on the next visible [#]_ element. [#]_
 The directive argument consists of one or more space-separated class
 names. The names are transformed to conform to the regular expression
 ``[a-z](-?[a-z0-9]+)*`` (see `Identifier Normalization`_ below).
 
-.. tip:: For reStructuredText directives, it is recommended to use the
-   `class option`_ option instead of wrapping them in a "class" directive.
+.. tip:: For reStructuredText directives, the `class option`_ provides
+         a more compact markup alternative.
 
 Examples::
 
@@ -1789,40 +1796,38 @@
         <paragraph classes="multiple">
             Second paragraph.
 
+Indented text after the directive is interpreted as content block.
+To set a classes attribute value on a `block quote`_, the
+"class" directive must be followed by a comment::
 
-.. [#] This is also true, if the class directive is "nested" at the end of
-   an indented text block, for example::
+   .. class:: special
+   ..
 
-       .. note:: the class values set in this directive-block do not apply to
-          the note but the next paragraph.
+       Special block quote.
 
-          .. class:: special
+results in this doctree_ fragment::
 
-       This is a paragraph with class value "special".
+    <comment xml:space="preserve">
+    <block_quote classes="special">
+        <paragraph>
+            Special block quote.
 
+.. [#] Elements that are not shown in the output (comments_,
+   `substitution definitions`_, `hyperlink targets`_, ...) as well as
+   "header_" and "footer_" directives are skipped.
+
+.. [#] This also works if the class directive is "nested" at the end of
+   an indented text block.
    This allows the "classification" of individual list items (except the
    first, as a preceding class directive applies to the list as a whole)::
 
        * bullet list
 
-         .. class:: classy item
+         .. class:: classy-item
 
        * second item, with class argument
 
-.. [#] To set a `classes attribute`_ value on a block quote, the
-   "class" directive must be followed by an empty comment::
 
-       .. class:: highlights
-       ..
-
-           Block quote text.
-
-   Without the empty comment, the indented text would be interpreted as the
-   "class" directive's content, and the classes would be applied to each
-   element (paragraph, in this case) individually, instead of to the block
-   quote as a whole.
-
-
 Identifier Normalization
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1839,7 +1844,7 @@
 * leading hyphens and number characters, and
 * trailing hyphens.
 
-For example ``"Rot.Gelb&Grün:+2008"`` becomes ``"rot-gelb-grun-2008"`` and
+For example ``"Rot.Gelb&Grün::2008+"`` becomes ``"rot-gelb-grun-2008"`` and
 ``"1000_Steps!"`` becomes ``"steps"``.
 
 .. topic:: Rationale:
@@ -2048,7 +2053,7 @@
 :Directive Options: none
 :Directive Content: Must contain a flat `field list`_.
 
-The "meta" directive is used to specify metadata\ [#]_ to be stored
+The "meta" directive is used to specify metadata [#]_ to be stored
 in, e.g., `HTML meta elements`_ or as `ODT file properties`_. The
 LaTeX writer passes it to the ``pdfinfo`` option of the hyperref_
 package. If an output format does not support "invisible" metadata,
@@ -2259,12 +2264,18 @@
     https://docs.python.org/3/library/codecs.html#standard-encodings
 
 .. _reStructuredText Markup Specification: restructuredtext.html
-.. _Directives: restructuredtext.html#directives
+.. _block quote: restructuredtext.html#block-quotes
+.. _comments: restructuredtext.html#comments
+.. _directives: restructuredtext.html#directives
 .. _document title: restructuredtext.html#document-title
+.. _embedded URIs: restructuredtext.html#embedded-uris-and-aliases
 .. _escaping mechanism: restructuredtext.html#escaping-mechanism
+.. _external hyperlink target:
 .. _external hyperlink targets:
     restructuredtext.html#external-hyperlink-targets
+.. _hyperlink reference:
 .. _hyperlink references: restructuredtext.html#hyperlink-references
+.. _hyperlink targets:
 .. _hyperlink target: restructuredtext.html#hyperlink-targets
 .. _supported length units: restructuredtext.html#length-units
 .. _reference name:

Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docs/user/latex.rst	2025-06-16 09:45:10 UTC (rev 10166)
@@ -91,9 +91,10 @@
 The LaTeX writer supports all `reStructuredText length units`_
 with the following peculiarities:
 
-* In LaTeX, the size of the *pixel unit* `can be configured
-  <size of a "px"_>`__. It defaults to **1 px = 1/72 in**
+* In LaTeX, the size of the *pixel unit* defaults to **1 px = 1/72 in**
   while the `CSS3 pixel unit`_ is defined as 1 px = 1/96 in.
+  The LaTeX conversion factor can be configured,
+  see below for the `size of a "px"`_.
 
 * LaTeX uses "pt" for the `American point`_ (*TeX point*), 1 pt = 1/72.25 in.
   The `DTP point`_ (*Postscript point*) used in CSS is available in LaTeX

Modified: trunk/docutils/docutils/transforms/misc.py
===================================================================
--- trunk/docutils/docutils/transforms/misc.py	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docutils/transforms/misc.py	2025-06-16 09:45:10 UTC (rev 10166)
@@ -38,7 +38,7 @@
 
     """
     Move the "class" attribute specified in the "pending" node into the
-    immediately following non-comment element.
+    next visible element.
     """
 
     default_priority = 210

Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py	2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docutils/transforms/references.py	2025-06-16 09:45:10 UTC (rev 10166)
@@ -862,7 +862,10 @@
         if not getattr(self.document.settings, 'use_bibtex', []):
             return
         for node in self.document.findall(nodes.citation_reference):
-            # Skip nodes that are resolved or have a matching target:
+            # Skip nodes that are resolved or have a matching target
+            # and will be resolved by `DanglingReferences`:
+            # TODO: drop the second condition when `DanglingReferences` is
+            #       replaced by two separate transitions.
             if node.resolved or self.document.nameids.get(node.get('refname')):
                 continue
             if node.astext():  # ensure text content (becomes the BibTeX key)
@@ -875,6 +878,13 @@
     """
     Check for dangling references (incl. footnote & citation) and for
     unreferenced targets.
+
+    Provisional : pending deprecation
+      Docutils readers will add separate transforms for resolving
+      refnames to refids and for reporting unresolved references
+      instead of this transform (to make space for reference-resolving
+      transforms added by extensions or applications) in Docutils 1.0.
+      This transform will be removed in Docutils 2.0.
     """
 
     default_priority = 850
@@ -908,7 +918,13 @@
 
 
 class DanglingReferencesVisitor(nodes.SparseNodeVisitor):
+    """Provisional : pending deprecation
 
+    This auxiliary class is used by the `DanglingReferences` transform
+    which will no longer be used in Docutils 1.0.
+    It will be removed in Docutils 2.0.
+    """
+
     def __init__(self, document, unknown_reference_resolvers) -> None:
         nodes.SparseNodeVisitor.__init__(self, document)
         self.document = document

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