|
From: <mi...@us...> - 2025-12-02 19:48:44
|
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.
|