SF.net SVN: docutils:[10237] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Mon, 15 Sep 2025 22:57:17 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
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.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins