SF.net SVN: docutils:[9673 ] trunk/docutils/docs/ref/d octree.txt
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9673
http://sourceforge.net/p/docutils/code/9673
Author: milde
Date: 2024-05-03 20:25:50 +0000 (Fri, 03 May 2024)
Log Message:
-----------
Doctree documentation: make documentation more concise.
Don't put element "Details" into a separate subsection
but just after a short element definition.
Do not repeat descriptions from the "details" list
in plain text description.
+ Less overhead and less scrolling in both, source and HTML.
+ A longer free-text description can move below the "details"
field-list making it more prominent and the overall structure of
element sections more uniform.
Modified Paths:
--------------
trunk/docutils/docs/ref/doctree.txt
Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt 2024-05-03 09:48:07 UTC (rev 9672)
+++ trunk/docutils/docs/ref/doctree.txt 2024-05-03 20:25:50 UTC (rev 9673)
@@ -277,9 +277,10 @@
:depth: 1
Each element in the DTD (document type definition) is described in its
-own section below. Each section contains an introduction plus the
-following subsections:
+own section below. Each section contains the following items:
+* Summary description (up to two sentences).
+
* Details (of element relationships and semantics):
:Category: One or more references to the element categories in
@@ -303,8 +304,10 @@
:Parameter Entities:
Lists the `parameter entities <parameter entity reference_>`__
- which directly or indirectly include the element.
+ which directly or indirectly include the element (if applicable).
+* Additional free text description and explanations (optional).
+
* Examples: reStructuredText_ examples are shown along with
fragments of the document trees resulting from parsing.
_`Pseudo-XML` is used for the results of parsing and processing.
@@ -345,9 +348,6 @@
*abbreviation*, a shortened or contracted form of a word or phrase
used to represent the whole.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <abbreviation> is analogous to the DocBook_ <abbrev> element
and similar to the HTML_ <abbr> element.
@@ -382,9 +382,6 @@
The <acronym> element is an inline element used to represent an
*acronym* (abbreviation formed by the initial letters of other words).
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <acronym> is analogous to the DocBook_ <acronym> element.
In HTML_, the <abbr> element is used for both,
@@ -418,13 +415,8 @@
The <address> element holds the surface mailing address information
for the author(s) (individual or group) of the document, or a third-party
-contact address. Its structure is identical to that of the
-`\<literal_block>`_ element: whitespace is significant, especially
-newlines.
+contact address.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <address> is analogous to the DocBook_ <address> element.
:Processing: As with the `\<literal_block>`_ element, newlines and other
@@ -472,13 +464,6 @@
The <admonition> element is a generic, titled *admonition*,
a distinctive and self-contained notice.
-See also the _`specific admonition elements`
-`\<attention>`_ `\<caution>`_, `\<danger>`_, `\<error>`_, `\<hint>`_,
-`\<important>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_.
-
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: The generic <admonition> has no direct analogues in common DTDs.
@@ -502,6 +487,10 @@
includes <admonition>. The `%structure.model`_
parameter entity indirectly includes <admonition>.
+See also the _`specific admonition elements`
+`\<attention>`_ `\<caution>`_, `\<danger>`_, `\<error>`_, `\<hint>`_,
+`\<important>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_.
+
Examples
--------
@@ -524,13 +513,9 @@
<attention>
===========
-The <attention> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <attention> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <attention> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
@@ -545,6 +530,9 @@
directly includes <attention>. The `%structure.model`_
parameter entity indirectly includes <attention>.
+See also the generic `\<admonition>`_ and the other
+`specific admonition elements`_.
+
Examples
--------
@@ -571,9 +559,6 @@
The <author> element holds the name of the author (or one of the authors)
of the document.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <author> is analogous to the DocBook_ <author> element.
:Processing: See `\<docinfo>`_.
@@ -615,9 +600,6 @@
The <authors> element is a container for author information for
documents with multiple authors.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <authors> is analogous to the DocBook_ <authorgroup> element.
:Processing: See `\<docinfo>`_.
@@ -668,9 +650,6 @@
The <block_quote> element is used for quotations set off from the
main text (standalone).
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <block_quote> is analogous to the <blockquote> element
in both HTML and DocBook_.
@@ -717,9 +696,6 @@
uniformly marked with bullets. Bullets are typically simple dingbats
(symbols) such as circles and squares.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <bullet_list> is analogous to the HTML<ul> element [#]_
and to the DocBook_ <itemizedlist> element.
@@ -777,13 +753,10 @@
<caution>
=========
-The <caution> element is an *admonition*, a distinctive and
+The <caution> element is a specific *admonition*, a distinctive and
self-contained notice. See also the generic `\<admonition>`_ and the
other `specific admonition elements`_.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <caution> is analogous to the `DocBook \<caution>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.), with the
@@ -830,9 +803,6 @@
of the `\<term>`_ being defined in a `\<definition_list>`_.
For example, it can be used to indicate the type of a variable.
-Details
--------
-
:Category: `Body Subelements`_ (simple)
:Analogues: <classifier> has no direct analogues in common DTDs.
It can be emulated with primitives or type effects.
@@ -878,9 +848,6 @@
The <colspec> element contains specifications for a column in a `\<table>`_.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <colspec> is defined in the `XML Exchange Table Model DTD`_.
[#extblx]_ It is analogous to the DocBook_ <colspec> element.
@@ -925,9 +892,6 @@
The <compound> element combines multiple `body elements`_
to a single logical paragraph.
-Details
--------
-
:Category: `Body Elements`_
:Analogues: The <compound> element has no direct analogues in common DTDs.
@@ -989,9 +953,6 @@
(individual or group) of the document, or a third-party contact.
It is typically used for an email or web address.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <contact> is analogous to the DocBook_ <email> element.
The HTML <address> element serves a similar purpose.
@@ -1035,9 +996,6 @@
The <container> element groups multiple `body elements`_ for user- or
application-specific purposes.
-Details
--------
-
:Category: `Body Elements`_
:Analogues: The <container> element is analogous to the HTML <div>
@@ -1092,9 +1050,6 @@
The <copyright> element contains the document's copyright statement.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <copyright> is analogous to the DocBook_ <copyright> element.
:Processing: See `\<docinfo>`_.
@@ -1132,13 +1087,9 @@
<danger>
========
-The <danger> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <danger> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <danger> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
@@ -1153,6 +1104,9 @@
directly includes <danger>. The `%structure.model`_
parameter entity indirectly includes <danger>.
+See also the generic `\<admonition>`_ and the other
+`specific admonition elements`_.
+
Examples
--------
@@ -1173,9 +1127,6 @@
The <date> element contains the date of publication, release, or
last modification of the document.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <date> is analogous to the DocBook_ <date> element.
:Processing: Often used with the RCS/CVS keyword "Date". See `\<docinfo>`_.
@@ -1217,9 +1168,6 @@
elements and potential future extensions. These elements are used for
notes, time/datestamp, processing information, etc.
-Details
--------
-
:Category: `Structural Subelements`_
:Analogues: There are no direct analogies to <decoration> in HTML or
in DocBook.
@@ -1242,9 +1190,6 @@
The <definition> element is a container for the body elements
used to define a `\<term>`_ in a `\<definition_list>`_.
-Details
--------
-
:Category: `Body Subelements`_ (compound)
:Analogues: <definition> is analogous to the HTML <dd> element
and to the DocBook_ <listitem> element
@@ -1265,12 +1210,8 @@
The <definition_list> element contains a list of terms and their
definitions. It can be used for glossaries or dictionaries, to
-describe or classify things, for dialogues, or to itemize subtopics
-(such as in this reference).
+describe or classify things, for dialogues, or to itemize subtopics.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <definition_list> is analogous to the HTML <dl> element
and to the DocBook_ <variablelist> element.
@@ -1286,6 +1227,8 @@
directly includes <definition_list>. The `%structure.model`_
parameter entity indirectly includes <definition_list>.
+See also `\<field_list>`_.
+
Examples
--------
@@ -1326,9 +1269,6 @@
The <definition_list_item> element contains a single
`\<term>`_/`\<definition>`_ pair (with optional `\<classifier>`_).
-Details
--------
-
:Category: `Body Subelements`_ (compound)
:Analogues: <definition_list_item> is analogous to the
@@ -1399,12 +1339,9 @@
<description>
=============
-The <description> element contains body elements, describing the
-purpose or effect of a command-line option or group of options.
+The <description> element is the part of an `\<option_list>`_ item that
+contains the description of a command-line option or group of options.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <description> has no direct analogues in common DTDs.
:Processing: See `\<option_list>`_.
@@ -1424,11 +1361,6 @@
data, or meta-data (data about the document). It corresponds to the
front matter of a book, such as the title page and copyright page.
-See also the `\<meta>`_ element (for hidden meta-data).
-
-Details
--------
-
:Category: `Structural Subelements`_
:Analogues: <docinfo> is analogous to DocBook_ <info> elements.
@@ -1452,7 +1384,9 @@
:Attributes: The <docinfo> element contains only the `common attributes`_.
+See also the `\<meta>`_ element (for hidden meta-data).
+
Examples
--------
@@ -1516,21 +1450,9 @@
<doctest_block>
===============
-The <doctest_block> element is a Python-specific variant of
-`\<literal_block>`_. It is a block of text where line breaks and
-whitespace are significant and must be preserved.
+The <doctest_block> element is a Python-specific variant of a
+`\<literal_block>`_.
-<doctest_block> elements are used for interactive Python interpreter
-sessions, which are distinguished by their input prompt: ``>>>``.
-They are meant to illustrate usage by example, and provide an elegant
-and powerful testing environment via the `doctest module`_ in the
-Python standard library.
-
-.. _doctest module: https://docs.python.org/3/library/doctest.html
-
-Details
--------
-
:Category: `Simple Body Elements`_
:Analogues: <doctest_block> is analogous to the HTML <pre> element
and to the DocBook_ <programlisting> and <screen> elements.
@@ -1549,6 +1471,14 @@
directly includes <doctest_block>. The `%structure.model`_
parameter entity indirectly includes <doctest_block>.
+<doctest_block> elements are used for interactive Python interpreter
+sessions, which are distinguished by their input prompt: ``>>>``.
+They are meant to illustrate usage by example, and provide an elegant
+and powerful testing environment via the `doctest module`_ in the
+Python standard library.
+
+.. _doctest module: https://docs.python.org/3/library/doctest.html
+
Examples
--------
@@ -1572,13 +1502,8 @@
==========
The <document> element is the root (topmost) element of the Docutils
-document tree. <document> is the direct or indirect ancestor of
-every other element in the tree. It encloses the entire document
-tree. It is the starting point for a document.
+document tree.
-Details
--------
-
:Category: `Root Element`_
:Analogues: <document> is analogous to the HTML <html> element and to
@@ -1597,19 +1522,6 @@
(docinfo, transition?)?,
`%structure.model`_; )
- Depending on the source of the data and the stage of
- processing, the "document" may not initially contain a
- "title". A document title is not directly representable in
- reStructuredText_. Instead, a lone top-level section may
- have its title promoted to become the document `\<title>`_,
- and similarly for a lone second-level (sub)section's title
- to become the document `\<subtitle>`_.
-
- The contents of "`\<decoration>`_" may be specified in
- a document, constructed programmatically, or both.
- The "`\<docinfo>`_" may be transformed from an initial
- `\<field_list>`_.
-
See the `%structure.model`_ parameter entity for details of
the body of a <document>.
@@ -1617,6 +1529,24 @@
plus an optional title_ attribute which stores the document
title metadata.
+<document> is the direct or indirect ancestor of every other element in
+the tree. It encloses the entire document tree. It is the starting
+point for a document.
+
+
+Depending on the source of the data and the stage of processing,
+the <document> may not initially contain a `\<title>`_.
+A document title is not directly representable in reStructuredText_.
+Instead, the `DocTitle transform`_ may promote a lone top-level section
+title to become the document `\<title>`_, and similarly a lone
+second-level (sub)section's title to become the document `\<subtitle>`_.
+
+The contents of "`\<decoration>`_" may be specified in a document,
+constructed programmatically, or both.
+
+The "`\<docinfo>`_" may be transformed from an initial `\<field_list>`_.
+
+
Examples
--------
@@ -1652,9 +1582,6 @@
The <emphasis> element is an inline element representing
text that has *stress emphasis*.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <emphasis> is analogous to the HTML_ <em> element
and the DocBook_ <emphasis> element.
@@ -1689,9 +1616,6 @@
The <entry> element represents one cell of a `\<table>`_.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <entry> is defined in the `XML Exchange Table Model DTD`_.
[#extblx]_ It is analogous to the DocBook_ <entry> element.
@@ -1721,9 +1645,6 @@
The <enumerated_list> element contains `\<list_item>`_ elements which are
uniformly marked with enumerator labels.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <enumerated_list> is analogous to the HTML <ol> element
@@ -1808,13 +1729,9 @@
<error>
=======
-The <error> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <error> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <error> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
@@ -1829,6 +1746,9 @@
<error>. The `%structure.model`_ parameter entity indirectly
includes <error>.
+See also the generic `\<admonition>`_ and the other `specific admonition
+elements`_.
+
Examples
--------
@@ -1846,12 +1766,9 @@
<field>
=======
-The <field> element contains a pair of `\<field_name>`_ and
-`\<field_body>`_ elements.
+The <field> element contains one item of a `\<field_list>`_,
+a pair of `\<field_name>`_ and `\<field_body>`_ elements.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <field> has no direct analogues in common DTDs.
HTML5 uses <div> elements inside <dl> lists for
@@ -1873,12 +1790,8 @@
<field_body>
============
-The <field_body> element contains body elements.
-It is analogous to a database field's data.
+The <field_body> element is analogous to a database field's data.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <field_body> is analogous to the HTML <dd> element.
:Processing: See `\<field_list>`_.
@@ -1895,14 +1808,8 @@
============
The <field_list> element contains two-column table-like structures
-resembling database records (label & data pairs). Field lists are
-often meant for further processing.
-In reStructuredText_, field lists are used to represent bibliographic
-fields (contents of the `\<docinfo>`_ element) and `directive`_ options.
+resembling database records (label & data pairs).
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <field_list> is analogue to the HTML <dl> element.
:Processing: A <field_list> is typically rendered as a two-column list,
@@ -1919,6 +1826,11 @@
directly includes <field_list>. The `%structure.model`_
parameter entity indirectly includes <field_list>.
+Field lists are often meant for further processing.
+In reStructuredText_, field lists are used to represent bibliographic
+fields (contents of the `\<docinfo>`_ element) and `directive`_ options.
+
+
Examples
--------
@@ -1961,12 +1873,8 @@
<field_name>
============
-The <field_name> element contains text; it is analogous to a
-database field's name.
+The <field_name> element is analogous to a database field's name.
-Details
--------
-
:Category: `Body Subelements`_ (simple)
:Analogues: <field_name> is analogous to the HTML <dt> element.
:Processing: See `\<field_list>`_.
@@ -1993,13 +1901,6 @@
to appear at the bottom of a web page, or repeated at the bottom of
every printed page.
-The <footer> element may contain processing information (datestamp, a
-link to Docutils_, etc.) as well as custom content.
-
-
-Details
--------
-
:Category: `Decorative Elements`_
:Analogues: <footer> is analogous to the HTML5 <footer> element. There
are no direct analogies to <footer> in HTML4 or DocBook.
@@ -2009,6 +1910,10 @@
:Children: <footer> elements may contain `body elements`_.
:Attributes: The <footer> element contains only the `common attributes`_.
+The <footer> element may contain processing information (datestamp, a
+link to Docutils_, etc.) as well as custom content.
+
+
Examples
--------
@@ -2040,9 +1945,6 @@
.. _notes: https://en.wikipedia.org/wiki/Note_(typography)
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <footnote> has no direct analogues in DocBook or HTML.
@@ -2112,9 +2014,6 @@
The <footnote_reference> element is an inline element representing a
cross reference to a `\<footnote>`_ (a footnote mark).
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: The <footnote_reference> element resembles
the `DocBook \<footnoteref>`_ element or
@@ -2180,11 +2079,7 @@
to appear at the top of a web page, or at the top of every printed
page.
-Details
--------
-
:Category: `Decorative Elements`_
-
:Analogues: <header> is analogous to the HTML5 <header> element.
There are no direct analogies to <header> in HTML4 or DocBook.
Equivalents are typically constructed from primitives and/or
@@ -2212,13 +2107,9 @@
<hint>
======
-The <hint> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <hint> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <hint> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
@@ -2233,6 +2124,9 @@
directly includes <hint>. The `%structure.model`_
parameter entity indirectly includes <hint>.
+See also the generic `\<admonition>`_ and the other
+`specific admonition elements`_.
+
Examples
--------
@@ -2253,20 +2147,12 @@
The <image> element refers to an image resource that should be included
in the document.
-It is up to the author to ensure compatibility of the image data format
-with the output format or user agent (LaTeX engine, HTML browser, ...).
-The `reStructuredText Directives` documentation contains a non exhaustive
-`table of compatible image formats`_.
-
-Details
--------
-
:Categories: `Body Elements`_, `Inline Elements`_
:Analogues: <image> is analogous to the `HTML \<img>`_,
`DocBook \<imagedata>`_, and `SVG \<image>`_ elements.
:Processing: The specified image is included into the output document.
Depending on the output format, this is done by referring to
- the image URI or by embedding the image files content.
+ the image URI or by embedding the image data.
:Parents: All elements employing the `%body.elements`_,
`%inline.elements`_, or `%structure.model`_ parameter entities
in their content models may contain <image>.
@@ -2278,6 +2164,11 @@
entities directly include <image>. The `%structure.model`_
parameter entity indirectly includes <image>.
+It is up to the author to ensure compatibility of the image data format
+with the output format or user agent (LaTeX engine, HTML browser, ...).
+The `reStructuredText Directives` documentation contains a non exhaustive
+`table of compatible image formats`_.
+
Examples
--------
@@ -2299,13 +2190,9 @@
<important>
===========
-The <important> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <important> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <important> is analogous to the `DocBook \<important>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
@@ -2319,6 +2206,9 @@
directly includes <important>. The `%structure.model`_
parameter entity indirectly includes <important>.
+See also the generic `\<admonition>`_ and the other
+`specific admonition elements`_.
+
Examples
--------
@@ -2350,9 +2240,6 @@
The <inline> element is a generic inline container.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <inline> is analogous to the HTML <span> element.
:Processing: Writers_ typically pass the classes_ attribute to the output
@@ -2406,9 +2293,6 @@
The <line> element contains a single line of text,
part of a `\<line_block>`_.
-Details
--------
-
:Category: `Body Subelements`_ (simple)
:Analogues: <line> has no direct analogues in common DTDs.
It can be emulated with primitives or type effects.
@@ -2426,16 +2310,8 @@
============
The <line_block> element contains a sequence of lines and nested line
-blocks. Line breaks (implied between elements) and leading whitespace
-(indicated by nesting) is significant and must be preserved.
+blocks.
-<line_block> elements are commonly used for verse and addresses.
-See `\<literal_block>`_ for an alternative useful for
-program listings and interactive computer sessions.
-
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <line_block> is analogous to the DocBook_ <literallayout>
@@ -2442,10 +2318,10 @@
element and to the HTML <pre> element (with modifications to
typeface styles).
-:Processing: Unlike <literal_block>, <line_block> elements are
+:Processing: Line breaks (implied between elements) and leading whitespace
+ (indicated by nesting) is significant and must be preserved.
+ Unlike <literal_block>, <line_block> elements are
typically rendered in an ordinary text typeface.
- It is crucial that leading whitespace and line breaks
- are preserved in the rendered form.
:Parents: All elements employing the `%body.elements`_ or
`%structure.model`_ parameter entities in their content models
@@ -2462,6 +2338,10 @@
directly includes <line_block>. The `%structure.model`_
parameter entity indirectly includes <line_block>.
+<line_block> elements are commonly used for verse and addresses.
+See `\<literal_block>`_ for an alternative useful for
+program listings and interactive computer sessions.
+
Examples
--------
@@ -2529,9 +2409,6 @@
The <list_item> element is a container for the elements of a list
item.
-Details
--------
-
:Category: `Body Subelements`_ (compound)
:Analogues: <list_item> is analogous to the HTML <li> element
and to the DocBook_ <listitem> element.
@@ -2584,9 +2461,6 @@
The <literal_block> element contains a block of text where line
breaks and whitespace are significant and must be preserved.
-<literal_block> elements are commonly used for program listings and
-interactive computer sessions.
-See `\<line_block>`_ for an alternative useful for verse and addresses.
Details
-------
@@ -2608,6 +2482,10 @@
directly includes <literal_block>. The `%structure.model`_
parameter entity indirectly includes <literal_block>.
+<literal_block> elements are commonly used for program listings and
+interactive computer sessions.
+See `\<line_block>`_ for an alternative useful for verse and addresses.
+
Examples
--------
@@ -2643,9 +2521,6 @@
The <math> element contains text in `LaTeX math format` [#latex-math]_
that is typeset as mathematical notation (inline formula).
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <math> is analogous to a HTML/MathML <math> element or
the LaTeX (``$ math $``) mode.
@@ -2682,9 +2557,6 @@
The <math_block> element contains a block of text in `LaTeX math format`
[#latex-math]_ that is typeset as mathematical notation (display formula).
-Details
--------
-
:Category: `Simple Body Elements`_
:Analogues: <math_block> is analogous to a HTML/MathML <math> element
displayed as block-level element or a LaTeX ``equation*``
@@ -2703,7 +2575,6 @@
Example
-------
-
The reStructuredText `"math" directive`_ generates a <math_block> element::
Euler's identity is the equality
@@ -2723,14 +2594,7 @@
The <meta> element is a container for "hidden" document
bibliographic data, or meta-data (data about the document).
-It corresponds to the HTML <meta> element.
-See also the `\<docinfo>`_ element for displayed meta-data.
-The document's title_ attribute stores the metadata document title.
-
-Details
--------
-
:Category: `Structural Subelements`_
:Analogues: <meta> is analogous to the `HTML <meta> element`_
@@ -2750,6 +2614,9 @@
*scheme* that correspond to the respective attributes
of the `HTML <meta> element`_.
+See also the `\<docinfo>`_ element for displayed meta-data.
+The document's `title attribute`_ stores the metadata document title.
+
Example
-------
@@ -2771,13 +2638,9 @@
<note>
======
-The <note> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <note> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <note> is analogous to the `DocBook \<note>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
@@ -2791,6 +2654,9 @@
directly includes <note>. The `%structure.model`_
parameter entity indirectly includes <note>.
+See also the generic `\<admonition>`_ and the other
+`specific admonition elements`_.
+
Examples
--------
@@ -2811,12 +2677,8 @@
========
The <option> element groups an option string together with zero or
-more option argument placeholders. Note that reStructuredText_
-currently supports only one argument per option.
+more option argument placeholders.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <option> has no direct analogues in common DTDs.
:Processing: See `\<option_list>`_.
@@ -2828,6 +2690,9 @@
:Attributes: The <option> element contains only the `common attributes`_.
+Note that reStructuredText_ currently supports only one argument per
+option.
+
Examples
--------
See the examples for the `\<option_list>`_ element.
@@ -2839,9 +2704,6 @@
The <option_argument> element contains placeholder text for option
arguments.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <option_argument> has no direct analogues in common DTDs.
:Processing: The value of the "delimiter" attribute is prefixed to the
@@ -2866,9 +2728,6 @@
The <option_group> element groups together one or more `\<option>`_
elements, all synonyms.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <option_group> has no direct analogues in common DTDs.
:Processing: Typically `\<option>`_ elements within an <option_group> are
@@ -2889,9 +2748,6 @@
Each <option_list> element contains a two-column list of command-line
options and descriptions, documenting a program's options.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <option_list> has no direct analogues in common DTDs.
It can be emulated with primitives such as tables.
@@ -2956,10 +2812,6 @@
The <option_list_item> element is a container for a pair of
`\<option_group>`_ and `\<description>`_ elements.
-
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <option_list_item> has no direct analogues in common DTDs.
:Processing: See `\<option_list>`_.
@@ -2979,9 +2831,6 @@
The <option_string> element contains the text of a command-line option.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <option_string> has no direct analogues in common DTDs.
:Processing: The <option_string> text is typically rendered in a
@@ -3002,9 +2851,6 @@
The <organization> element contains the name of document author's
organization, or the organization responsible for the document.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <organization> is analogous to the DocBook_ <orgname>,
<corpname>, or <publishername> elements.
@@ -3047,9 +2893,6 @@
The <paragraph> element contains the text and inline elements of a
single paragraph, a fundamental building block of documents.
-Details
--------
-
:Category: `Simple Body Elements`_
:Analogues: <paragraph> is analogous to the HTML <p> element
and to the DocBook_ <para> elements.
@@ -3097,9 +2940,6 @@
The <raw> element contains non-reStructuredText data that is to be passed
untouched to the Writer.
-Details
--------
-
:Category: `Simple Body Elements`_, `Inline Elements`_
:Analogues: The <raw> element has no direct analogues in common DTDs.
:Processing: Passed untouched to the Writer_.
@@ -3146,9 +2986,6 @@
The <revision> element contains the revision number of the document.
It can be used alone or in conjunction with `\<version>`_.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <revision> is analogous to but simpler than the DocBook_
<revision> element. It closely matches the DocBook
@@ -3194,9 +3031,6 @@
The <row> element represents one row of a `\<table>`_.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <row> is defined in the `XML Exchange Table Model DTD`_.
[#extblx]_ It is analogous to the HTML_ <tr> element
@@ -3235,24 +3069,12 @@
The <section> element is the main unit of hierarchy for Docutils documents.
-The Docutils document model uses a simple, recursive model for section
-structure. A `\<document>`_ node may contain <section> elements.
-Sections in turn may contain other <section> elements, without limit.
-The level (depth) of a section element is determined from its physical
-nesting level.
-
-Paragraphs and other body elements may occur before a <section>,
-but not after it.
-
-Details
--------
-
:Category: `Structural Elements`_
:Analogues: <section> is analogous to the section elements in DocBook and
- HTML. Unlike ``<h1>`` … ``<h6>`` in HTML_, ``<sect1>`` …
- ``<sect5>`` in DocBook_, or ``<div1>`` … in XMLSpec_, the
- level is not incorporated into the element name.
+ HTML. However, unlike ``<h1>`` … ``<h6>`` in HTML_ and
+ ``<sect1>`` … ``<sect5>`` in DocBook_, the level is not
+ incorporated into the element name.
:Parents: The following elements may contain <section>:
`\<document>`_, `\<section>`_
@@ -3272,6 +3094,16 @@
directly includes <section>. The `%structure.model`_
parameter entity indirectly includes <section>.
+The Docutils document model uses a simple, recursive model for section
+structure. A `\<document>`_ node may contain <section> elements.
+Sections in turn may contain other <section> elements, without limit.
+The level (depth) of a section element is determined from its physical
+nesting level.
+
+Paragraphs and other body elements may occur before a <section>,
+but not after it.
+
+
Examples
--------
@@ -3325,21 +3157,8 @@
Sidebars are like miniature, parallel documents that occur inside other
documents, providing related or reference material.
-A <sidebar> is typically offset by a border and "floats" to the side of
-the page; the document's main text may flow around it. Sidebars can also
-be likened to super-footnotes; their content is outside of the flow of
-the document's main text.
+Their content is outside of the flow of the document's main text.
-The <sidebar> element is a non-recursive `\<section>`_-like construct
-which may occur at the top level of a `\<section>`_ wherever a body
-element (list, table, etc.) is allowed. In other words, <sidebar>
-elements cannot nest inside body elements, so you can't have a <sidebar>
-inside a ``table`` or a ``list``, or inside another <sidebar> or
-`\<topic>`_.
-
-Details
--------
-
:Category: `Structural Elements`_
:Analogues: <sidebar> is analogous to the DocBook_ <sidebar> and
@@ -3366,7 +3185,12 @@
:Parameter Entities: The `%structure.model`_ parameter entity
directly includes <sidebar>.
+The <sidebar> element is a non-recursive `\<section>`_-like construct.
+<sidebar> elements cannot nest inside body elements, so you can't have a
+<sidebar> inside a `\<table>`_ or a list, or inside another <sidebar>
+or `\<topic>`_.
+
Examples
--------
@@ -3394,9 +3218,6 @@
The <status> element contains a status statement for the document,
such as "Draft", "Final", "Work In Progress", etc.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <status> is analogous to the DocBook_ <status> element.
:Processing: See `\<docinfo>`_.
@@ -3435,11 +3256,8 @@
========
The <strong> element is an inline element representing
-text that has strong importance, seriousness, or urgency.
+text that has **strong importance**, **seriousness**, or **urgency**.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <strong> is analogous to the HTML_ <strong> element.
:Processing: Typically displayed in boldface.
@@ -3475,9 +3293,6 @@
The <subscript> element is an inline element representing text which
should be displayed as subscript.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <subscript> is analogous to the HTML_ <sub> element
and the DocBook_ <subscript> element.
@@ -3523,11 +3338,8 @@
==========
The <subtitle> element stores the subtitle of a `\<document>`_,
-`\<section>`, or `\<sidebar>`.
+`\<section>`_, or `\<sidebar>`_.
-Details
--------
-
:Category: `Structural Subelements`_
:Analogues: <subtitle> is analogous to the DocBook_ <subtitle> element.
In HTML, subtitles are represented by a <p> element inside
@@ -3581,9 +3393,6 @@
The <superscript> element is an inline element representing text which
should be displayed as superscript.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <superscript> is analogous to the HTML_ <sup> element
and the DocBook_ <superscript> element.
@@ -3621,9 +3430,6 @@
The <table> element represents a data arrangement with rows and columns.
-Details
--------
-
:Category: `Body Elements`_
:Analogues: <table> is defined in the `XML Exchange Table Model DTD`_.
@@ -3702,9 +3508,6 @@
The <tbody> element identifies the rows that form the *body*
of a `\<table>`_ (as distinct from the header rows).
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <tbody> is defined in the `XML Exchange Table Model DTD`_.
[#extblx]_ It is analogous to the HTML_ <tbody> and
@@ -3728,9 +3531,6 @@
The <term> element contains a word or phrase being defined in a
`\<definition_list>`_.
-Details
--------
-
:Category: `Body Subelements`_ (simple)
:Analogues: <term> is analogous to the HTML <dt> element
and to the DocBook_ <term> element.
@@ -3750,16 +3550,13 @@
========
The <tgroup> element identifies a logically complete portion of a
-`\<table>`_. [#]_
+`\<table>`_.
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <tgroup> is defined in the `XML Exchange Table Model DTD`_.
[#extblx]_ It is analogous to the DocBook_ <tgroup> element.
- There is no corresponding HTML element, the <colgroup>
- element has a different semantics.
+ There is no corresponding HTML element (the <colgroup>
+ element has a different purpose and semantics).
:Processing: See the `Exchange Table Model`_.
:Parents: Only the `\<table>`_ element contains <tgroup>.
:Children: <tgroup> elements contain one or more `\<colspec>`_
@@ -3772,17 +3569,17 @@
Via the `%tbl.tgroup.att`_ parameter entity, <tgroup>
supports the `common attributes`_.
+Tables usually consist of a single <tgroup>. Complex tables with widely
+varying column specifications may be easier to code using multiple
+<tgroup>s. However, this is not supported by `table markup in
+reStructuredText <rST tables_>`__ and Docutils table handling routines.
+
Examples
--------
See `\<table>`_.
-.. [#] Tables usually consist of a single <tgroup>. Complex tables with
- widely varying column specifications may be easier to code using
- multiple <tgroup>s. However, this is not supported by `table markup in
- reStructuredText <rST tables_>`__ and Docutils table handling routines.
-
<thead>
=======
@@ -3789,9 +3586,6 @@
The <thead> element identifies the row(s) that form the head of
a `\<table>`_ (as distinct from the body rows).
-Details
--------
-
:Category: `Body Subelements`_
:Analogues: <thead> is defined in the `XML Exchange Table Model DTD`_.
[#extblx]_ It is analogous to the HTML_ and DocBook_
@@ -3816,13 +3610,9 @@
<tip>
=====
-The <tip> element is an *admonition*, a distinctive and self-contained
-notice. See also the generic `\<admonition>`_ and the other
-`specific admonition elements`_.
+The <tip> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <tip> is analogous to the `DocBook \<tip>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
@@ -3836,6 +3626,9 @@
directly includes <tip>. The `%structure.model`_
parameter entity indirectly includes <tip>.
+See also the generic `\<admonition>`_ and the other `specific admonition
+elements`_.
+
Examples
--------
@@ -3857,12 +3650,6 @@
elements`_, or a generic `\<admonition>`_. It is also used for the
caption of a `\<table>`_.
-The <title> of a <document> may differ from its *metadata title*
-stored in the `title attribute`_.
-
-Details
--------
-
:Category: `Structural Subelements`_, `Body Subelements`_
:Analogues: <title> is analogous to the DocBook_ <title> element and
the HTML_ header elements (<h1> etc.) while the HTML <title>
@@ -3878,6 +3665,9 @@
plus refid_ (used as a backlink to a table of contents entry)
and auto_.
+The <title> of a <document> may differ from its *metadata title*
+stored in the `title attribute`_.
+
Examples
--------
@@ -3914,9 +3704,6 @@
The <title_reference> element is an inline element representing
the titles of a cited creative work.
-Details
--------
-
:Category: `Inline Elements`_
:Analogues: <title_reference> is analogous to the HTML_ <cite> element
and the DocBook_ <citetitle> element.
@@ -3948,25 +3735,18 @@
<topic>
=======
-The <topic> element is a non-recursive section-like construct which may
-occur at the top level of a `\<document>`_, `\<section>`_, or `\<sidebar>`_
-wherever a body element (list, table, etc.) is allowed. In other words,
-<topic> elements cannot nest inside body elements. You may use a
-`\<rubric>`_ element to get an informal heading inside a <table>
-or a <list>, or inside another <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.
-Docutils uses the <topic> element also for a generated `table of contents`_,
-and the "abstract" and "dedication" `bibliographic fields`_.
-
-Details
--------
-
:Category: `Structural Elements`_
-:Analogues: <topic> is analogous to the DocBook_ <simplesect> element.
+:Analogues: <topic> is analogous to the DocBook_ <simplesect> element
+ and the HTML_ <aside> element.
:Processing: A <topic> element should be set off from the rest of the
document somehow, such as with indentation or a border.
+ In contrast to a `\<sidebar>`_, it should not float.
:Parents: The following elements may contain <topic>:
`\<document>`_, `\<section>`_, `\<sidebar>`_
@@ -3976,12 +3756,22 @@
(title?, (%body.elements;)+)
-:Attributes: The <topic> element contains the `common attributes`_ plus
+:Attributes: The <topic> element accepts the `common attributes`_ plus
depth_ and local_.
: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`_.
+
+<topic> elements may occur anywhere a `\<section>`_ or `\<transition>`_
+may occur. They cannot nest inside body elements.
+
+.. Tip:: Use a `\<rubric>`_ element to get an informal heading inside a
+ table, list, or inside another <topic>.
+
+
Examples
--------
@@ -4003,28 +3793,9 @@
<transition>
============
-The <transition> element is commonly seen in novels and short
-fiction, as a gap spanning one or more lines, with or without a type
-ornament such as a row of asterisks.
+The <transition> element separates body elements and sections, dividing a
+`\<section>`_ into untitled divisions.
-Transitions separate body elements and sections, dividing a section into
-untitled divisions. A transition may not begin or end a section [#]_ or
-document, nor may two transitions be immediately adjacent.
-
-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.
-
-__ ../dev/rst/alternatives.html#doctree-representation-of-transitions
-__ ../dev/rst/alternatives.html
-
-Details
--------
-
:Category: `Structural Subelements`_
:Analogues: <transition> is analogous to the HTML <hr> element.
:Processing: The <transition> element is typically rendered as vertical
@@ -4039,6 +3810,21 @@
:Parameter Entities: The `%structure.model`_ parameter entity
directly includes <transition>.
+A transition may not begin or end a section [#]_ or document, nor may two
+transitions be immediately adjacent.
+
+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.
+
+__ ../dev/rst/alternatives.html#doctree-representation-of-transitions
+__ ../dev/rst/alternatives.html
+
+
Examples
--------
@@ -4066,9 +3852,6 @@
The <version> element contains the version number of the document.
It can be used alone or in conjunction with `\<revision>`_.
-Details
--------
-
:Category: `Bibliographic Elements`_
:Analogues: <version> may be considered analogous to the DocBook_
<revision>, <revnumber>, or <biblioid> elements.
@@ -4108,13 +3891,9 @@
<warning>
=========
-The <warning> element is an *admonition*, a distinctive and
-self-contained notice. See also the generic `\<admonition>`_
-and the other `specific admonition elements`_.
+The <warning> element is a specific *admonition*, a distinctive and
+self-contained notice.
-Details
--------
-
:Category: `Compound Body Elements`_
:Analogues: <warning> is analogous to the `DocBook \<warning>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
@@ -4128,6 +3907,9 @@
directly includes <warning>. The `%structure.model`_
parameter entity indirectly includes <warning>.
+See also the generic `\<admonition>`_ and the other
+`specific admonition elements`_.
+
Examples
--------
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins