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

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

Revision: 10237
          http://sourceforge.net/p/docutils/code/10237
Author:   milde
Date:     2025-09-15 22:57:17 +0000 (Mon, 15 Sep 2025)
Log Message:
-----------
Document the `<target>` element.

Add the last missing element reference section to the Document Tree documentation.

Modified Paths:
--------------
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/ref/doctree.rst

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-09-14 17:26:51 UTC (rev 10236)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-09-15 22:57:17 UTC (rev 10237)
@@ -59,12 +59,11 @@
 * The "rst" parser will warn if a `"figure"`_ directive is missing both
   caption and legend in Docutils 1.0.
 
-* The "rst" parser will use <inline> elements for inline targets
+* 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
   in Docutils 1.0.
 
-* <target> elements with content will be deprecated in Docutils 1.0
-  and invalid in Docutils 2.0.
-
 * To match the definition in the "Exchange Table Model", the
   `"colwidth" attribute`_ will be stored as a `str` (instead of
   numerical) value in Python element instances in Docutils 1.0.
@@ -1512,6 +1511,7 @@
 .. _Docutils XML: docs/ref/doctree.html
 .. _"colwidth" attribute: docs/ref/doctree.html#colwidth
 .. _<doctest_block>: docs/ref/doctree.html#doctest-block
+.. _<target>: docs/ref/doctree.html#target
 
 .. _"class": docs/ref/rst/directives.html#class
 .. _csv-table: docs/ref/rst/directives.html#csv-table

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2025-09-14 17:26:51 UTC (rev 10236)
+++ trunk/docutils/docs/ref/doctree.rst	2025-09-15 22:57:17 UTC (rev 10237)
@@ -130,7 +130,7 @@
 
 _`Simple elements`
   | may contain text data.
-  | Most simple elements support have a mixed content model.  However, only
+  | Most simple elements have a mixed content model.  However, only
     `inline elements`_ may be intermixed with text (`%text.model`_). [#]_
   | Examples: `\<paragraph>`_ (mixed), `\<literal_block>`_ (text-only)
 
@@ -245,11 +245,11 @@
   .. class:: narrow run-in
 
   :empty:
-    `\<image>`_ , `\<pending>`_
+    `\<image>`_ , `\<pending>`_, `\<target>`_
   :simple:
     `\<comment>`_, `\<doctest_block>`_, `\<literal_block>`_, `\<math_block>`_,
     `\<paragraph>`_, `\<raw>`_, `\<reference>`_, `\<rubric>`_,
-    `\<substitution_definition>`_, `\<target>`_
+    `\<substitution_definition>`_
   :compound:
     `\<admonition>`_, `\<attention>`_, `\<block_quote>`_, `\<bullet_list>`_,
     `\<caution>`_, `\<citation>`_, `\<compound>`_, `\<container>`_,
@@ -363,9 +363,6 @@
   fragments of the document trees resulting from parsing.
   Pseudo-XML_ is used to display the results of parsing and processing.
 
-.. Note::
-   Some element reference sections below are marked "_`to be completed`".
-   Please help complete this document by contributing to its writing.
 
 <abbreviation>
 ==============
@@ -3943,9 +3940,76 @@
 <target>
 ========
 
-`To be completed`_.
+The <target> element provides an end-point for a hypertext `\<reference>`_.
 
+:Category:   Empty `Body Elements`_, `Inline Elements`_ [#inline-targets]_
+:Analogues:  As body element, <target> is similar to the DocBook_ <anchor>
+             element. An inline <target> can be represented by a DocBook
+             <phrase> or HTML_ <span> element.
+:Processing: <target> elements with refid_, refname_, or refuri_ attribute
+             (indirect targets) act as a relay for links to one of the
+             target's ids_ or names_.
+             A <target> without refid_, refname_, or refuri_ attributes
+             provides ids_ or names_ for its content or, if empty, the
+             next element.
+:Parents:    all elements employing `%body.elements`_, `%structure.model`_,
+             or `%text.model`_ in their content models
+:Children:   only text data [#target-content]_
+:Attributes: anonymous_, refid_, refname_, refuri_, and
+             the `common attributes`_.
 
+
+.. [#inline-targets] Inline <target> elements will be deprecated in
+   Docutils 1.0 and invalid in Docutils 2.0.  The "rst" parser will
+   use `\<inline>`_ elements for inline targets.
+
+.. [#target-content] <target> elements with content will be deprecated in
+   Docutils 1.0 and invalid in Docutils 2.0.
+
+Examples
+--------
+
+In reStructuredText, `hyperlink targets`_ are indicated by a leading
+underscore::
+
+    .. _inline: `inline target`_
+    .. _example: https//:example.org
+    .. _alias:
+    .. _explicit target:
+
+    The hyperlink target above points to this paragraph
+    with an _`inline target`.
+
+Pseudo-XML_ fragment from simple parsing::
+
+    <target ids="inline" names="inline" refname="inline target">
+    <target ids="example" names="example" refuri="https//:example.org">
+    <target ids="alias" names="alias">
+    <target ids="explicit-target" names="explicit\ target">
+    <paragraph>
+        The hyperlink target above points to this paragraph
+        with an
+        <target ids="inline-target" names="inline\ target">
+            inline target
+        .
+
+After applying transforms_, the paragraph has two reference names and
+two IDs, transferred from the preceding targets::
+
+    <target ids="inline" names="inline" refid="inline-target">
+    <target ids="example" names="example" refuri="https//:example.org">
+    <target refid="alias">
+    <target refid="explicit-target">
+    <paragraph ids="explicit-target alias" names="explicit\ target alias">
+        The hyperlink target above points to this paragraph
+        with an
+        <target ids="inline-target" names="inline\ target">
+            inline target
+        .
+
+For more examples, see `\<reference>`_.
+
+
 <tbody>
 =======
 

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