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

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

Revision: 10178
          http://sourceforge.net/p/docutils/code/10178
Author:   milde
Date:     2025-06-23 15:42:44 +0000 (Mon, 23 Jun 2025)
Log Message:
-----------
Revise documentation.

Clarify description of the handling of duplicate reference names in the
reStructuredText Specification and the docstring in docutils.nodes.

Modified Paths:
--------------
    trunk/docutils/docs/ref/rst/restructuredtext.rst
    trunk/docutils/docutils/nodes.py

Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-06-21 22:10:15 UTC (rev 10177)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-06-23 15:42:44 UTC (rev 10178)
@@ -455,12 +455,14 @@
 reference (``[#note]_``), can also be referred to by a plain hyperlink
 reference (``note_``).  Of course, each type of reference (hyperlink,
 footnote, citation) may be processed and rendered differently.  Some
-care should be taken to avoid reference name conflicts.
+care should be taken to avoid reference name conflicts. [#]_
 References to `substitution definitions`_ (`substitution references`_)
 use a different namespace.
 
 .. [#case-forgiving] Matching `substitution references`_ to
    `substitution definitions`_ is `case-sensitive but forgiving`_.
+.. [#] Docutils' rules for handling duplicate names are described in
+   section `Implicit Hyperlink Targets`_.
 
 
 Document Structure
@@ -1704,7 +1706,7 @@
 whitespace, followed by indented body elements.  A footnote label can
 be:
 
-- a whole decimal number consisting of one or more digits,
+- an integer consisting of one or more digits,
 
 - a single ``#`` (denoting `auto-numbered footnotes`_),
 
@@ -1729,11 +1731,9 @@
 
     .. [1] Body elements go here.
 
-Each footnote automatically generates a hyperlink target pointing to
-itself.  The text of the hyperlink target name is the same as that of
-the footnote label.  `Auto-numbered footnotes`_ generate a number as
-their footnote label and reference name.  See `Implicit Hyperlink
-Targets`_ for a complete description of the mechanism.
+Each footnote automatically generates a `hyperlink target`_ pointing
+to itself (auto-numbered and auto-symbol footnotes generate `implicit
+hyperlink targets`_).  The target name is is the footnote label.
 
 Syntax diagram::
 
@@ -1755,10 +1755,10 @@
 label "1", the second is assigned the label "2", and so on (assuming
 there are no manually numbered footnotes present; see `Mixed Manual
 and Auto-Numbered Footnotes`_ below).  A footnote which has
-automatically received a label "1" generates an implicit hyperlink
-target with name "1", just as if the label was explicitly specified.
+automatically received a label "1" generates an `implicit hyperlink
+target`_ with name "1".
 
-.. _autonumber label: `autonumber labels`_
+.. _autonumber label:
 
 A footnote may specify a label explicitly while at the same time
 requesting automatic numbering: ``[#label]``.  These labels are called
@@ -1891,6 +1891,7 @@
 
 
 .. _explicit hyperlink targets:
+.. _hyperlink target:
 
 Hyperlink Targets
 `````````````````
@@ -2461,33 +2462,40 @@
 Implicit hyperlink targets are generated by `section titles`_,
 auto-numbered footnotes_, and hyperlink references with `embedded URIs
 and aliases`_. They may also be generated by extension constructs.
+Implicit hyperlink targets behave identically to `explicit hyperlink
+targets`_ except in case of duplicate reference names.
 
-Implicit hyperlink targets behave identically to explicit `hyperlink
-targets`_ except in case of duplicate reference names:
+Ambiguity due to different targets with the same reference name is
+avoided by the following procedure:
 
-1. `Explicit hyperlink targets`_ override any implicit targets having
-   the same reference name.  The implicit hyperlink targets are
-   removed, and level-1 (info) system messages are inserted.
+#. Duplicate external__ or indirect__ hyperlink targets that refer to
+   the same URI or hyperlink reference do not conflict.  One target
+   is removed and an INFO [#level]_ system message inserted.
 
-2. Duplicate implicit hyperlink targets are removed, and level-1
-   (info) system messages inserted.  For example, if two or more
-   sections have the same title (such as "Introduction" subsections of
-   a rigidly-structured document), there will be duplicate implicit
+   __ `external hyperlink targets`_
+   __ `indirect hyperlink targets`_
+
+#. `Explicit hyperlink targets`_ override any implicit targets having
+   the same reference name.  The implicit hyperlink target is removed,
+   and an INFO [#level]_ system message inserted.
+
+#. Duplicate implicit hyperlink targets are removed, and INFO [#level]_
+   system messages inserted.  For example, if two or more sections
+   have the same title (such as "Introduction" subsections of a
+   rigidly-structured document), there will be duplicate implicit
    hyperlink targets.
 
-3. Duplicate explicit hyperlink targets are removed, and level-2
-   (warning) system messages are inserted.
+#. Duplicate explicit hyperlink targets are removed, and WARNING [#level]_
+   system messages inserted.
 
-4. Exception: duplicate external or indirect hyperlink targets
-   (identical reference names and referenced URIs or hyperlink
-   references) do not conflict, one is removed.
+The parser returns a set of *unique* hyperlink targets.  The calling
+software (such as Docutils_) can warn of unresolvable links, giving
+reasons for the messages.
 
-System messages are inserted where target links have been removed.
-See "Error Handling" in `PEP 258`_.
+.. [#level] See `Error Handling`__ in PEP 258 for a description of
+   system message levels.
 
-The parser must return a set of *unique* hyperlink targets.  The
-calling software (such as Docutils_) can warn of unresolvable
-links, giving reasons for the messages.
+   __ ../../peps/pep-0258.html#error-handling
 
 
 Inline Markup

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2025-06-21 22:10:15 UTC (rev 10177)
+++ trunk/docutils/docutils/nodes.py	2025-06-23 15:42:44 UTC (rev 10178)
@@ -1878,30 +1878,35 @@
                         explicit: bool = False,
                         ) -> None:
         """
-        `self.nameids` maps names to IDs, while `self.nametypes` maps names to
-        booleans representing hyperlink target type (True==explicit,
-        False==implicit).  This method updates the mappings.
+        Update the name/id mappings.
 
+        `self.nameids` maps names to IDs. The value ``None`` indicates
+        that the name is a "dupname" (i.e. there are already at least
+        two targets with the same name and type).
+
+        `self.nametypes` maps names to booleans representing
+        hyperlink target type (True==explicit, False==implicit).
+
         The following state transition table shows how `self.nameids` items
         ("id") and `self.nametypes` items ("type") change with new input
         (a call to this method), and what actions are performed:
 
-        ====  ========  ========  ========  =======  ====  ========  =====
-          Old State      Input          Action        New State      Notes
-        --------------  --------  -----------------  --------------  -----
-        id    type      new type  sys.msg.  dupname  id    type
-        ====  ========  ========  ========  =======  ====  ========  =====
-        -     -         explicit  -         -        new   explicit
-        -     -         implicit  -         -        new   implicit
-        -     implicit  explicit  -         -        new   explicit
-        old   implicit  explicit  INFO      old      new   explicit
-        -     explicit  explicit  ERROR     new      -     explicit
-        old   explicit  explicit  ERROR     new,old  -     explicit  [#]_
-        -     implicit  implicit  INFO      new      -     implicit
-        old   implicit  implicit  INFO      new,old  -     implicit
-        -     explicit  implicit  INFO      new      -     explicit
-        old   explicit  implicit  INFO      new      old   explicit
-        ====  ========  ========  ========  =======  ====  ========  =====
+        ========  ====  ========  ====  ========  ======== =======  ======
+         Input      Old State      New State            Action      Notes
+        --------  --------------  --------------  ----------------  ------
+        type      id    type      id    type      dupname  report
+        ========  ====  ========  ====  ========  ======== =======  ======
+        explicit                  new   explicit
+        implicit                  new   implicit
+        explicit  old   explicit  None  explicit  new,old  WARNING  [#ex]_
+        implicit  old   explicit  old   explicit  new      INFO     [#ex]_
+        explicit  old   implicit  new   explicit  old      INFO     [#ex]_
+        implicit  old   implicit  None  implicit  new,old  INFO     [#ex]_
+        explicit  None  explicit  None  explicit  new      WARNING
+        implicit  None  explicit  None  explicit  new      INFO
+        explicit  None  implicit  new   explicit
+        implicit  None  implicit  None  implicit  new      INFO
+        ========  ====  ========  ====  ========  ======== =======  ======
 
         .. [#] Do not clear the name-to-id map or invalidate the old target if
            both old and new targets refer to identical URIs or reference names.

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