SF.net SVN: docutils:[10255 ] trunk/docutils/docs/ref

Revision: 10255
          http://sourceforge.net/p/docutils/code/10255
Author:   milde
Date:     2025-11-02 17:51:07 +0000 (Sun, 02 Nov 2025)
Log Message:
-----------
Documentation update/fixes.

Correct description of refid: refers to another element by
*one of its* identifiers. Add XPath example.

Correct description of valid parents for "topic" and "content"
directives.

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

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2025-11-02 17:50:57 UTC (rev 10254)
+++ trunk/docutils/docs/ref/doctree.rst	2025-11-02 17:51:07 UTC (rev 10255)
@@ -4469,7 +4469,7 @@
   | Used in the `classes`_ attribute.  Python data type: ``list[str]``.
 
 _`%idref.type`
-  | A reference to another element by its identifier_.
+  | A reference to another element by one of its identifiers_.
     Resolves to NMTOKEN_. [#id-vc]_
   | Used in the `refid`_ attribute.  Python data type: ``str``.
 
@@ -4803,12 +4803,20 @@
 unique `identifiers`_, typically assigned by the system.
 It is one of the `common attributes`_, shared by all Docutils elements.
 
+An XPath_ expression to select the element with identifier `test` is ::
+
+  //*[contains(concat(' ', @ids, ' '), ' test ')]
+
+(similar to `selecting an element by CSS class`__).
+
 .. TODO:
    * Use 'id' for primary identifier key?
    * Keep additional keys in `ids`
      or in the preceding target elements?
 
+__ https://stackoverflow.com/questions/1604471/how-can-i-find-an-element-by-css-class-with-xpath
 
+
 ``level``
 =========
 
@@ -4984,8 +4992,8 @@
 
 Attribute type: `%idref.type`_.  Default value: none.
 
-The ``refid`` attribute contains a reference to another element via its
-`identifier`_.
+The ``refid`` attribute contains a reference to another element via
+one of its `identifiers`_.
 It is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
 `\<problematic>`_, `\<reference>`_, `\<target>`_, and `\<title>`_ elements
 (via the `%refid.att`_ and `%reference.atts`_ parameter entities).
@@ -5886,6 +5894,7 @@
 .. _external DTD subset: https://www.w3.org/TR/xml11/#sec-external-ent
 .. _XML attribute types: https://www.w3.org/TR/REC-xml/#sec-attribute-types
 .. _One ID per Element Type: https://www.w3.org/TR/REC-xml/#one-id-per-el
+.. _XPath: https://www.w3.org/TR/xpath/
 
 .. _Docutils: https://docutils.sourceforge.io/
 .. _docutils.nodes:

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2025-11-02 17:50:57 UTC (rev 10254)
+++ trunk/docutils/docs/ref/rst/directives.rst	2025-11-02 17:51:07 UTC (rev 10255)
@@ -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.  Body
-elements and topics may not contain nested topics.
+Topics may occur anywhere a section or transition may occur and
+in sidebars.  Body elements and topics may not contain nested 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,
@@ -1173,7 +1173,7 @@
 
 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.
+may occur anywhere a section or transition may occur and in sidebars.
 Body elements and topics may not contain tables of contents.
 
 Here's the directive in its simplest form::

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