SF.net SVN: docutils:[9714 ] trunk/docutils/docs/ref/d octree.txt

Revision: 9714
          http://sourceforge.net/p/docutils/code/9714
Author:   milde
Date:     2024-05-18 08:45:16 +0000 (Sat, 18 May 2024)
Log Message:
-----------
Document Tree documentation fixes.

Copy `topic` description text from the element docstring into the element
reference.

Describe a simplified "structure model" (that works with
`nodes.Element.check_content_model()`).

Simplify description of "%section.elements" parameter entity
(similar to the other "....elements" entities).

Remove an erroneous comment in the description of `transition`:
the additional placement constraints are indeed enforced in the
`misc.Transitions` transform.

Fix typos. Add/Fix links.

Modified Paths:
--------------
    trunk/docutils/docs/ref/doctree.txt

Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt	2024-05-18 08:45:06 UTC (rev 9713)
+++ trunk/docutils/docs/ref/doctree.txt	2024-05-18 08:45:16 UTC (rev 9714)
@@ -81,7 +81,7 @@
 .. contents:: :local:
 
 
-Alternatively, we may classify elements by their valid content:
+Alternatively, we may classify elements by their content model:
 
 .. class:: description
 
@@ -1937,7 +1937,7 @@
              context to a referenced passage of text".
 
              For collections of notes that occur at the end of a section,
-             the the DPub ARIA role `"doc-endnotes"`__ is more appropriate.
+             the DPub ARIA role `"doc-endnotes"`__ is more appropriate.
 
              The corresponding types in the `EPUB 3 Structural Semantics
              Vocabulary`__ are "footnote" and "endnote".
@@ -3078,7 +3078,7 @@
 The level (depth) of a section element is determined from its physical
 nesting level.
 
-Paragraphs and other body elements may occur before a <section>,
+Paragraphs and other `body elements`_ may occur before a <section>,
 but not after it.
 
 
@@ -3324,7 +3324,7 @@
              a <hgroup_> element.
 :Processing: A document's subtitle is usually rendered smaller
              than its `\<title>`_.
-:Parents:    The `\<document>`_, `\<section>`, and `\<sidebar>`_ elements
+:Parents:    The `\<document>`_, `\<section>`_, and `\<sidebar>`_ elements
              may contain <subtitle>.
 :Children:   <subtitle> elements may contain text data
              plus `inline elements`_ (`%text.model`_).
@@ -3714,9 +3714,8 @@
 <topic>
 =======
 
-The <topic> element is a non-recursive section-like construct for content
-that is separate from the flow of the document.
-Topics do not appear in the table of contents.
+The <topic> element represents a non-recursive section-like construct for
+content that is separate from the flow of the document.
 
 :Category:   `Structural Elements`_
 
@@ -3741,15 +3740,21 @@
 :Parameter Entities: The `%structure.model`_ parameter entity
              directly includes <topic>.
 
-Docutils uses the <topic> element also for a generated `table of contents`_,
-and the "abstract" and "dedication" `bibliographic fields`_.
+Topics are terminal, "leaf" mini-sections, like block quotes with titles,
+or textual figures.  A <topic> is just like a `\<section>`_, except that
+it has no subsections, it does not get listed in the ToC, and it doesn't
+have to conform to section placement rules.
+You may place a <topic> in the middle of a <section> and continue the same
+section after it --- something that cannot be done with a nested <section>.
 
-<topic> elements may occur anywhere a `\<section>`_ or `\<transition>`_
-may occur.  They cannot nest inside body elements.
+Topics cannot nest inside topics, or `body elements`_
+(tables, lists, block quotes, etc).
 
 .. Tip:: Use a `\<rubric>`_ element to get an informal heading inside a
          table, list, or inside another <topic>.
 
+Docutils uses the <topic> element also for a generated `table of contents`_,
+and the "abstract" and "dedication" `bibliographic fields`_.
 
 Examples
 --------
@@ -3796,8 +3801,8 @@
 `A Record of reStructuredText Syntax Alternatives`__.
 
 .. [#] In reStructuredText markup, a transition may appear to fall at
-   the end of a section immediately before another section.  A
-   transform recognizes this case and moves the transition so it
+   the end of a section immediately before another section.
+   A transform_ recognizes this case and moves the transition so it
    separates the sections.
 
 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
@@ -5078,15 +5083,9 @@
 ``%section.elements``
 ---------------------
 
-The ``%section.elements`` parameter entity contains an OR-list of all
-`\<section>`_-equivalent elements.  ``%section.elements`` is itself
-contained within the `%structure.model`_ parameter entity.
+The ``%section.elements`` parameter entity contains the `\<section>`_
+element.
 
-Entity definition::
-
-    section
-    %additional.section.elements;
-
 The ``%additional.section.elements`` parameter entity can be used
 by wrapper DTDs to extend ``%section.elements``.
 
@@ -5121,40 +5120,46 @@
 hierarchical structure of a document and of its constituent parts.
 See the discussion of the `element hierarchy`_ above.
 
-Entity definition:
+Simplified entity definition:
 
 .. parsed-literal::
 
+   ( ( `%body.elements`_; | topic | sidebar | transition )*,
+     ( `%section.elements`_; | transition )* )
+
+Each `\<document>`_ or `\<section>`_ contains zero or more
+body elements, topics, sidebars, or transitions,
+followed by zero or more sections (whose contents include this model),
+or transitions.
+
+The actual entity definition is more complex,
+
+.. parsed-literal::
+
    ( ( (`%body.elements`_; | topic | sidebar)+, transition? )*,
-     ( (`%section.elements`_;), (transition?, (`%section.elements`_;) )* )? )
+     ( (`%section.elements`_;),
+       (transition?, (`%section.elements`_;) )* )? )
 
-Each `\<document>`_ or `\<section>`_ contains zero or more body elements,
-topics, and/or sidebars, optionally interspersed with single
-transitions, followed by zero or more sections (whose contents are
-recursively the same as this model) optionally interspersed with
-transitions.
+to impose the following restrictions:
 
-The following restrictions are imposed by this model:
+* A `\<transition>`_ may not be the first element (i.e. it may
+  not occur at the beginning of a document or directly after
+  a title, subtitle, meta or decoration element).
 
 * Transitions must be separated by other elements (body elements,
   sections, etc.).  In other words, a transition may not be
   immediately adjacent to another transition.
 
-* A transition may not occur at the beginning of a document or
-  section.
+An additional restriction cannot be expressed in the language of DTDs: [#]_
 
-.. The following is not the case with Docutils (since at least 2004)
-   (cf. test/functional/input/data/standard.txt)
+* A transition may not occur at the end of a document or section.
 
-   An additional restriction, which cannot be expressed in the language
-   of DTDs, is imposed by software:
-
-   * A transition may not occur at the end of a document or section.
-
 The ``%structure.model`` parameter entity is directly employed in the
 content models of the `\<document>`_ and `\<section>`_ elements.
 
+.. [#] Docutils imposes it in the `misc.Transitions` transform_.
 
+
 ``%tbl.entry.mdl``
 -------------------
 

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