SF.net SVN: docutils:[10268 ] trunk/docutils/docs/ref/ doctree.rst

Revision: 10268
          http://sourceforge.net/p/docutils/code/10268
Author:   milde
Date:     2025-12-02 19:48:42 +0000 (Tue, 02 Dec 2025)
Log Message:
-----------
More detailled description of the restrictions on transition placement.

The formulation of the restrictions
"a transition may not begin a section or document" and
"a transition may not be at the end of a section or document"
is vague and inconsistent.

Add description of "invisible" elements that are ignored when determining
whether a transition is at the begin or end of a section or the document.

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

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2025-12-01 22:43:32 UTC (rev 10267)
+++ trunk/docutils/docs/ref/doctree.rst	2025-12-02 19:48:42 UTC (rev 10268)
@@ -4316,24 +4316,40 @@
 :Processing: The <transition> element is typically rendered as vertical
              whitespace (more than that separating paragraphs), with or
              without a horizontal line or row of asterisks.  In novels,
-             transitions are often represented as a row of three
-             well-spaced asterisks with vertical space above and below.
-:Parents:    `\<document>`_, `\<section>`_
+             transitions are often represented as a row of three well-spaced
+             asterisks or a vignette with vertical space above and below.
+:Parents:    `\<document>`_, `\<section>`_ (cf. `%structure.model`_)
 :Children:   none (empty)
 :Attributes: only the `common attributes`_
-:Parameter Entities: `%structure.model`_ directly includes <transition>.
+:Parameter Entities: The `%structure.model`_ directly includes <transition>.
 
-A transition may not begin or end a section [#]_ or document, nor may two
-transitions be immediately adjacent.
+The document model sets additional restrictions
+on the placement of <transitions>: [#extra-rule]_
 
+* A transition may not be immediately adjacent to another transition,
+  i.e., <transition> elements must be separated by other elements.
+
+* A transition may not start the text of a document or section, i.e., a
+  <transition> is invalid as first child or preceded by only `\<title>`_,
+  `\<subtitle>`_, or invisible elements [#invisible-or-moving]_.
+
+* A transition may not occur at the end of a document or section. [#]_
+  In other words, a <transition> is invalid as last child element
+  or followed by only invisible elements [#invisible-or-moving]_.
+
 See also `Doctree Representation of Transitions`__ in
 `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
-   separates the sections.
+.. [#invisible-or-moving] The elements `\<meta>`_, `\<pending>`_,
+  `\<substitution_definition>`_, and `\<target>`_ are not visible
+  in the output document. The `\<decoration>`_ element contains
+  `\<header>`_ and `\<footer>`_ which move to the respective places.
 
+.. [#] In reStructuredText markup, a transition may appear to fall
+   at the end of a section immediately before another section.
+   The `misc.Transitions` transform_ recognizes this case and
+   moves the transition so it separates the sections.
+
 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
 __ ../dev/rst/alternatives.html
 
@@ -5610,25 +5626,15 @@
      ( (`%section.elements`_;),
        (transition?, (`%section.elements`_;) )* )? )
 
-to impose the following restrictions:
+because there are additional restrictions on `\<transition>`_\ s.
+[#extra-rule]_
 
-* 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.
-
-An additional restriction cannot be easily expressed in the
-language of DTDs: [#]_
-
-* 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 enforces it in the `misc.Transitions` transform_.
+.. [#extra-rule] The restrictions cannot be fully expressed in the
+   language of DTDs without making the definition overly complicated.
+   Docutils checks them 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.