Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10232] trunk
|
From: <mi...@us...> - 2025-09-13 16:01:11
|
Revision: 10232
http://sourceforge.net/p/docutils/code/10232
Author: milde
Date: 2025-09-13 16:01:09 +0000 (Sat, 13 Sep 2025)
Log Message:
-----------
Documentation amendments.
Announce removement of `memo.section_level` in Docutils 2.0.
Add some missing element descriptions to The Docutils Document Tree.
Revert section level changes in restructuredtext.rst doc. Move section
"Implicite Hyperlink Targets" to the end.
Mention Roles Defined in Standard Definition Files in
"reStructuredText Interpreted Text Roles".
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/ref/rst/definitions.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/ref/rst/roles.rst
trunk/docutils/docs/user/rst/cheatsheet.rst
trunk/web/rst.rst
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -210,6 +210,7 @@
* Remove `states.RSTStateMachine.memo.reporter`,
`states.RSTStateMachine.memo.section_bubble_up_kludge`,
+ `states.RSTStateMachine.memo.section_level`,
`states.RSTState.title_inconsistent()`, and `states.Line.eofcheck`
in Docutils 2.0. Ignored since Docutils 0.22.
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/docutils/docs/ref/doctree.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -3357,18 +3357,50 @@
<rubric>
========
- rubric n. 1. a title, heading, or the like, in a manuscript,
- book, statute, etc., written or printed in red or otherwise
- distinguished from the rest of the text. ...
+A <rubric> is an informal heading outside the document's section structure.
- -- Random House Webster's College Dictionary, 1991
+:Category: `Simple Body Elements`_
+:Analogues: <rubric> has no direct analogues in common DTDs.
+ It shares some features with the <bridgehead> DocBook_ element.
+:Processing: Rendered similar to a section heading, traditionally highlighted
+ in red (hence the name). Rubrics are not (auto)numbered
+ and not included in the document's table of contents.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
-A rubric is like an informal heading that doesn't correspond to the
-document's structure.
+Example
+-------
-`To be completed`_.
+The reStructuredText `"rubric" directive`_ can be used to get a
+heading at places where a section is not allowed::
+ .. sidebar:: Sidebar Title
+ This is a sidebar. It is for text outside the flow
+ of the main text.
+
+ .. rubric:: A heading inside a sidebar
+
+ Sections are not supported in a sidebar.
+ A rubric can be used to structure the content instead.
+
+Pseudo-XML_ fragment from simple parsing::
+
+ <sidebar>
+ <title>
+ Sidebar Title
+ <paragraph>
+ This is a sidebar. It is for text outside the flow
+ of the main text.
+ <rubric>
+ A heading inside a sidebar
+ <paragraph>
+ Sections are not supported in a sidebar.
+ A rubric can be used to structure the content instead.
+
+
<section>
=========
@@ -3618,18 +3650,115 @@
<substitution_definition>
=========================
-The <substitution_definition> element stores a
-reStructuredText `substitution definition`_.
+The <substitution_definition> element stores content that shall
+replace matching `\<substitution_reference>`_ elements.
-`To be completed`_.
+:Category: `Simple Body Elements`_
+:Analogues: Substitution definitions are analog to XML’s
+ `internal entities`_ or programming language macros.
+:Processing: A <substitution_definition> is not directly rendered.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: ltrim_, rtrim_, and the `common attributes`_.
+ The names_ attribute uses the "substitution" namespace_.
+Examples
+--------
+A reStructuredText `substitution definition`_ allows to include
+complex inline structures within text while keeping the details
+out of the text flow::
+
+ The chemical formula for water is |H2O|.
+
+ .. |H2O| replace:: H\ :sub:`2`\ O
+
+
+Pseudo-XML_ fragment from simple parsing::
+
+ <paragraph>
+ The chemical formula for water is
+ <substitution_reference refname="H2O">
+ H2O
+ .
+ <substitution_definition names="H2O">
+ H
+ <subscript>
+ 2
+ O
+
+The `references.Substitutions` transform_ replaces the
+`\<substitution_reference>`_ with the content of the
+<substitution_definition>::
+
+ <paragraph>
+ The chemical formula for water is
+ H
+ <subscript>
+ 2
+ O
+ .
+ <substitution_definition names="H2O">
+ H
+ <subscript>
+ 2
+ O
+
+A substitution definition can also supply an `\<image>`_ for inline use::
+
+ The |biohazard| symbol must be used on
+ medical waste containers.
+
+ .. |biohazard| image:: biohazard.png
+
+Pseudo-XML_ fragment from simple parsing::
+
+ <paragraph>
+ The
+ <substitution_reference refname="biohazard">
+ biohazard
+ symbol must be used on
+ medical waste containers.
+ <substitution_definition names="biohazard">
+ <image alt="biohazard" uri="biohazard.png">
+
+After running the `references.Substitutions` transform_, we get::
+
+ <paragraph>
+ The
+ <image alt="biohazard" uri="biohazard.png">
+ symbol must be used on
+ medical waste containers.
+ <substitution_definition names="biohazard">
+ <image alt="biohazard" uri="biohazard.png">
+
+For more usage examples, see `Substitution Definitions`_ in the
+`reStructuredText Markup Specification`_.
+
+
<substitution_reference>
========================
-`To be completed`_.
+The <substitution_reference> element is a placeholder for the content of
+the matching <substitution_definition>.
+:Category: `Inline Elements`_
+:Analogues: A <substitution_reference> is analogue to an XML
+ `entity reference`_.
+:Processing: Replaced by the content of a matching
+ `\<substitution_definition>`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: the `common attributes`_ plus refname_.
+ The refname_ attribute uses the "substitution" namespace_.
+Examples
+--------
+
+See `\<substitution_definition>`_.
+
+
<subtitle>
==========
@@ -4929,7 +5058,6 @@
`DocTitle transform`_. It is typically not part of the rendered document
but, for example, used as `HTML <title> element`_ and shown in a
browser's title bar, a user's history or bookmarks, or search results.
-
Its value may may differ from the *displayed title* which is stored in a
`\<title>`_ element.
@@ -5689,11 +5817,12 @@
.. _XML: https://developer.mozilla.org/en-US/docs/Web/XML/XML_introduction
.. _Introducing the Extensible Markup Language (XML):
http://xml.coverpages.org/xmlIntro.html
+.. _internal entities: https://www.w3.org/TR/xml/#sec-internal-ent
+.. _entity reference: https://www.w3.org/TR/xml/#dt-entref
.. _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
-
.. _Docutils: https://docutils.sourceforge.io/
.. _docutils.nodes:
.. _nodes.py: ../../docutils/nodes.py
@@ -5771,6 +5900,7 @@
.. _standalone hyperlinks: rst/restructuredtext.html#standalone-hyperlinks
.. _strong emphasis: rst/restructuredtext.html#strong-emphasis
.. _substitution definition:
+.. _substitution definitions:
.. _substitutions: rst/restructuredtext.html#substitution-definitions
.. _hyperlink targets: rst/restructuredtext.html#hyperlink-targets
.. _transition: rst/restructuredtext.html#transitions
@@ -5798,6 +5928,7 @@
.. _"contents" directive: rst/directives.html#table-of-contents
.. _"csv-table": rst/directives.html#csv-table
.. _"danger" directive: rst/directives.html#danger
+.. _"date" directive: rst/directives.html#date
.. _"epigraph": rst/directives.html#epigraph
.. _"error" directive: rst/directives.html#error
.. _"figure" directive: rst/directives.html#figure
@@ -5816,6 +5947,7 @@
.. _"parsed-literal" directive: rst/directives.html#parsed-literal
.. _"pull-quote": rst/directives.html#pull-quote
.. _"raw" directive: rst/directives.html#raw
+.. _"rubric" directive: rst/directives.html#rubric
.. _"sectnum" directive: rst/directives.html#sectnum
.. _"sidebar" directive: rst/directives.html#sidebar
.. _"table" directive: rst/directives.html#table
Modified: trunk/docutils/docs/ref/rst/definitions.rst
===================================================================
--- trunk/docutils/docs/ref/rst/definitions.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/docutils/docs/ref/rst/definitions.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -215,6 +215,8 @@
.. [#attribute-optional] Would gain from support for attributes/arguments
to inline roles (see TODO_).
+New in Docutils 0.22
+
.. _TODO: https://docutils.sourceforge.io/docs/dev/todo.html
#acronym-and-abbreviation
.. _"html5" writer: ../../user/html.html#html5
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -1703,7 +1703,7 @@
.. _footnote:
Footnotes
----------
+`````````
:Doctree elements: `\<footnote>`_, `\<label>`_
:Config settings: footnote_references_
@@ -1749,7 +1749,7 @@
Numbered Footnotes
-``````````````````
+..................
`Numbered footnotes` use decimal numbers as label. The number may
be specified in the source or automatically assigned.
@@ -1760,7 +1760,7 @@
The footnote above can be referred to with 1_ or [1]_.
Auto-Numbered Footnotes
-.......................
+'''''''''''''''''''''''
A number sign (``#``) may be used as the first character of a footnote
label to request automatic numbering of the footnote or footnote
@@ -1809,7 +1809,7 @@
Mixed Manual and Auto-Numbered Footnotes
-........................................
+''''''''''''''''''''''''''''''''''''''''
Manual and automatic footnote numbering may both be used within a
single document, although the results may not be expected. Manual
@@ -1833,7 +1833,7 @@
Auto-Symbol Footnotes
-`````````````````````
+.....................
An asterisk (``*``) may be used as footnote label to request automatic
symbol generation for footnotes and footnote references. The asterisk
@@ -1880,7 +1880,7 @@
Citations
----------
+`````````
:Doctree element: `\<citation>`_
:See also: `citation references`_
@@ -1902,7 +1902,7 @@
.. _hyperlink target:
Hyperlink Targets
------------------
+`````````````````
:Doctree element: `\<target>`_
:See also: | `hyperlink references`_
@@ -2097,7 +2097,7 @@
.. _anonymous:
Anonymous Hyperlinks
-````````````````````
+....................
The `World Wide Web Consortium`_ recommends in its `HTML Techniques
for Web Content Accessibility Guidelines`_ that authors should
@@ -2140,7 +2140,7 @@
Directives
-----------
+``````````
:Doctree elements: depend on the directive
@@ -2245,7 +2245,7 @@
Substitution Definitions
-------------------------
+````````````````````````
:Doctree element: `\<substitution_definition>`_
:See also: `substitution references`_
@@ -2405,7 +2405,7 @@
Comments
---------
+````````
:Doctree element: `\<comment>`_
:Config setting: strip_comments_
@@ -2447,7 +2447,7 @@
+----------------------+
Empty Comments
-``````````````
+..............
An explicit markup start followed by a blank line and nothing else
(apart from whitespace) is an "_`empty comment`". It serves to
@@ -2463,58 +2463,6 @@
This is a block quote.
-.. _implicit hyperlink target:
-
-Implicit Hyperlink Targets
-==========================
-
-:Doctree elements: `\<section>`_, `\<target>`_
-
-Implicit hyperlink targets are generated by `section titles`_
-and named hyperlink references with `embedded URIs and aliases`_.
-They may also be generated by extension constructs.
-Implicit hyperlink targets behave identically to `explicit hyperlink
-targets`_ except in case of duplicate reference names.
-
-.. _name conflicts:
-
-Ambiguity due to different objects with the same `reference name`_ is
-avoided by the following procedure:
-
-#. Duplicate external__ or indirect__ hyperlink targets that refer to
- the same URI or hyperlink reference do not conflict. One target
- is invalidated_ and an INFO [#level]_ system message inserted.
-
- __ `external hyperlink targets`_
- __ `indirect hyperlink targets`_
-
-#. `Explicit hyperlink targets`_, citations_, `numbered footnotes`_,
- and directives_ with `"name" option`_
- override any implicit targets having the same reference name.
- The implicit hyperlink target is invalidated_,
- and an INFO [#level]_ system message inserted.
-
-#. Duplicate implicit hyperlink targets are both invalidated_,
- and INFO [#level]_ system messages inserted.
- For example, if two or more sections
- have the same title (such as "Introduction" subsections of a
- rigidly-structured document), there will be duplicate implicit
- hyperlink targets.
-
-#. Duplicate `explicit hyperlink targets`_ (or other objects with
- the same reference name) are both invalidated_, and WARNING [#level]_
- system messages inserted.
-
-The parser returns a set of *unique* hyperlink targets. The calling
-software (such as Docutils_) can warn of unresolvable links, giving
-reasons for the messages.
-
-.. [#level] See `Error Handling`__ in PEP 258 for a description of
- system message levels.
-
- __ ../../peps/pep-0258.html#error-handling
-
-
Inline Markup
=============
@@ -3126,6 +3074,58 @@
RFC3986_.
+.. _implicit hyperlink target:
+
+Implicit Hyperlink Targets
+==========================
+
+:Doctree elements: `\<section>`_, `\<target>`_
+
+Implicit hyperlink targets are generated by `section titles`_
+and named hyperlink references with `embedded URIs and aliases`_.
+They may also be generated by extension constructs.
+Implicit hyperlink targets behave identically to `explicit hyperlink
+targets`_ except in case of duplicate reference names.
+
+.. _name conflicts:
+
+Ambiguity due to different objects with the same `reference name`_ is
+avoided by the following procedure:
+
+#. Duplicate external__ or indirect__ hyperlink targets that refer to
+ the same URI or hyperlink reference do not conflict. One target
+ is invalidated_ and an INFO [#level]_ system message inserted.
+
+ __ `external hyperlink targets`_
+ __ `indirect hyperlink targets`_
+
+#. `Explicit hyperlink targets`_, citations_, `numbered footnotes`_,
+ and directives_ with `"name" option`_
+ override any implicit targets having the same reference name.
+ The implicit hyperlink target is invalidated_,
+ and an INFO [#level]_ system message inserted.
+
+#. Duplicate implicit hyperlink targets are both invalidated_,
+ and INFO [#level]_ system messages inserted.
+ For example, if two or more sections
+ have the same title (such as "Introduction" subsections of a
+ rigidly-structured document), there will be duplicate implicit
+ hyperlink targets.
+
+#. Duplicate `explicit hyperlink targets`_ (or other objects with
+ the same reference name) are both invalidated_, and WARNING [#level]_
+ system messages inserted.
+
+The parser returns a set of *unique* hyperlink targets. The calling
+software (such as Docutils_) can warn of unresolvable links, giving
+reasons for the messages.
+
+.. [#level] See `Error Handling`__ in PEP 258 for a description of
+ system message levels.
+
+ __ ../../peps/pep-0258.html#error-handling
+
+
Measures and Units
==================
Modified: trunk/docutils/docs/ref/rst/roles.rst
===================================================================
--- trunk/docutils/docs/ref/rst/roles.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/docutils/docs/ref/rst/roles.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -376,6 +376,14 @@
prefix for role names is recommended.
+Roles Defined in Standard Definition Files
+==========================================
+
+The `reStructuredText Standard Definition Files`_ ``html-roles.txt`` and
+``s5defs.txt`` define additional roles for `semantic inline markup`_
+and for use in `S5/HTML slide shows`_ (colors, font sizes, display options).
+
+
Custom Roles
============
@@ -391,6 +399,10 @@
.. _Interpreted Text: restructuredtext.html#interpreted-text
.. _hyperlink references: restructuredtext.html#hyperlink-references
+.. _reStructuredText Standard Definition Files: definitions.html
+.. _HTML5 inline markup elements: definitions.html#additional-roles-for-html
+.. _S5/HTML slide shows: definitions.html#s5-html-definitions
+
.. _The Docutils Document Tree: ../doctree.html
.. _class names: ../doctree.html#classname
.. _classes attribute: ../doctree.html#classes
Modified: trunk/docutils/docs/user/rst/cheatsheet.rst
===================================================================
--- trunk/docutils/docs/user/rst/cheatsheet.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/docutils/docs/user/rst/cheatsheet.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -76,7 +76,7 @@
See <https://docutils.sourceforge.io/docs/ref/rst/directives.html> for full info.
================ ============================================================
-Directive Name Description (Docutils version added to, in [brackets])
+Directive Name Description
================ ============================================================
attention Specific admonition; also "caution", "danger",
"error", "hint", "important", "note", "tip", "warning"
Modified: trunk/web/rst.rst
===================================================================
--- trunk/web/rst.rst 2025-09-11 14:16:33 UTC (rev 10231)
+++ trunk/web/rst.rst 2025-09-13 16:01:09 UTC (rev 10232)
@@ -235,8 +235,8 @@
.. |reStructuredText| image:: rst.png
+.. Emacs settings
-..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
