eUgEntOptIc44/docutils
1
0
Fork 0
mirror of git://repo.or.cz/docutils.git synced 2025-10-06 00:32:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation amendments.

Browse Source 
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".

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@10232 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
This commit is contained in:
milde
2025-09-13 16:01:09 +00:00
parent 951f9da20e
commit c210e76a91
7 changed files with 226 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docutils/RELEASE-NOTES.rst
View File

@@ -210,6 +210,7 @@ Removals
* 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.

158
docutils/docs/ref/doctree.rst
View File

@@ -3357,16 +3357,48 @@ See `\<table>`_.
<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,16 +3650,113 @@ Pseudo-XML_ fragment from simple parsing::
<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 @@ The attribute is set by the `"title" directive`_ or the
`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 @@ Bibliography
.. _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 @@ Bibliography
.. _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 @@ Bibliography
.. _"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 @@ Bibliography
.. _"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

2
docutils/docs/ref/rst/definitions.rst
View File

@@ -215,6 +215,8 @@ __ ../../user/config.html#stylesheet-2
.. [#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

128
docutils/docs/ref/rst/restructuredtext.rst
View File

@@ -1703,7 +1703,7 @@ unambiguous.
.. _footnote:
Footnotes
---------
`````````
:Doctree elements: `\<footnote>`_, `\<label>`_
:Config settings: footnote_references_
@@ -1749,7 +1749,7 @@ Syntax diagram::
Numbered Footnotes
``````````````````
..................
`Numbered footnotes` use decimal numbers as label. The number may
be specified in the source or automatically assigned.
@@ -1760,7 +1760,7 @@ or `hyperlink reference`_::
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 @@ same as the order in which a person would read them.
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 @@ illustrative::
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 @@ reused, doubled and then tripled, and so on (``**`` etc.).
Citations
---------
`````````
:Doctree element: `\<citation>`_
:See also: `citation references`_
@@ -1902,7 +1902,7 @@ differently from footnotes. For example::
.. _hyperlink target:
Hyperlink Targets
-----------------
`````````````````
:Doctree element: `\<target>`_
:See also: | `hyperlink references`_
@@ -2097,7 +2097,7 @@ Syntax diagram::
.. _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 @@ require attention to the order of corresponding targets.
Directives
----------
``````````
:Doctree elements: depend on the directive
@@ -2245,7 +2245,7 @@ Syntax diagram::
Substitution Definitions
------------------------
````````````````````````
:Doctree element: `\<substitution_definition>`_
:See also: `substitution references`_
@@ -2405,7 +2405,7 @@ Templates
Comments
--------
````````
:Doctree element: `\<comment>`_
:Config setting: strip_comments_
@@ -2447,7 +2447,7 @@ Syntax diagram::
+----------------------+
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 @@ construct, insert an unindented empty comment in-between::
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 @@ characters (see `Escaping Mechanism`_ above).
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
==================

12
docutils/docs/ref/rst/roles.rst
View File

@@ -376,6 +376,14 @@ Writer. For example::
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 @@ generated roles.
.. _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

2
docutils/docs/user/rst/cheatsheet.rst
View File

@@ -76,7 +76,7 @@ Directive Quick Reference
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"

2
web/rst.rst
View File

@@ -235,8 +235,8 @@ is left as an exercise for the reader.
.. |reStructuredText| image:: rst.png
.. Emacs settings
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil