SF.net SVN: docutils:[9969 ] trunk/docutils/docs/ref/d octree.rst
milde--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9969
http://sourceforge.net/p/docutils/code/9969
Author: milde
Date: 2024-10-25 22:46:34 +0000 (Fri, 25 Oct 2024)
Log Message:
-----------
Condense "details" lists in Document Tree documentation.
More concise style in the sections listing doctree element details.
(Reduce boilerplate text and repetitions,
use phrases instead of full sentences if applicable.)
Modified Paths:
--------------
trunk/docutils/docs/ref/doctree.rst
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2024-10-25 17:45:15 UTC (rev 9968)
+++ trunk/docutils/docs/ref/doctree.rst 2024-10-25 22:46:34 UTC (rev 9969)
@@ -386,11 +386,9 @@
:Processing: May be used to semantically mark the presence of an
abbreviation in the text for styling or scripting purposes.
Writers may ignore the element and just render its contents.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <abbreviation>.
-:Children: <abbreviation> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <abbreviation> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -420,11 +418,9 @@
:Processing: May be used to semantically mark the presence of an
acronym in the text for styling or scripting purposes.
Writers may ignore the element and just render its contents.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <acronym>.
-:Children: <acronym> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <acronym> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -448,6 +444,8 @@
for the author(s) (individual or group) of the document, or a third-party
contact address.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <address> is analogous to the DocBook_ <address> element.
:Processing: As with the `\<literal_block>`_ element, newlines and other
@@ -454,14 +452,10 @@
whitespace is significant and must be preserved.
However, a monospaced typeface need not be used.
See also `\<docinfo>`_.
-:Parents: The following elements may contain <address>:
- `\<docinfo>`_, `\<authors>`_.
-:Children: <address> elements contain text data plus `inline elements`_
- (`%text.model`_).
-:Attributes: The <address> element contains the `common attributes`_
- plus `xml:space`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <address>.
+:Parents: `\<docinfo>`_, `\<authors>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: the `common attributes`_ and `xml:space`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <address>.
Examples
--------
@@ -495,29 +489,23 @@
The <admonition> element is a generic, titled *admonition*,
a distinctive and self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
-
:Analogues: The generic <admonition> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
The specific admonitions `\<caution>`_, `\<note>`_,
`\<tip>`_, and `\<warning>`_ are analogous to the
respective DocBook_ elements.
-
:Processing: Rendered distinctly (inset and/or in a box, etc.).
-
-:Parents: All elements employing the `%body.elements`_
- or `%structure.model`_ parameter entities in
- their content models may contain <admonition>.
-
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
:Children: <admonition> elements begin with a `\<title>`_ and may contain
one or more `body elements`_.
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <admonition>,
+ `%structure.model`_ indirectly includes <admonition>.
-:Attributes: The <admonition> element contains only the `common attributes`_.
-
-:Parameter Entities: The `%body.elements`_ parameter entity directly
- 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>`_.
@@ -547,19 +535,19 @@
The <attention> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <attention> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Attention!" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their
- content models may contain <attention>.
-:Children: <attention> elements contain one or more `body elements`_.
-:Attributes: The <attention> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <attention>. The `%structure.model`_
- parameter entity indirectly includes <attention>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <attention>,
+ `%structure.model`_ indirectly includes <attention>.
See also the generic `\<admonition>`_ and the other
`specific admonition elements`_.
@@ -590,16 +578,15 @@
The <author> element holds the name of the author (or one of the authors)
of the document.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <author> is analogous to the DocBook_ <author> element.
-:Processing: See `\<docinfo>`_.
-:Parents: The following elements may contain <author>:
- `\<docinfo>`_, `\<authors>`_.
-:Children: <author> elements may contain text data plus `inline elements`_
- (`%text.model`_).
-:Attributes: The <author> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <author>.
+:Processing: see `\<docinfo>`_
+:Parents: `\<docinfo>`_, `\<authors>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <author>.
Examples
--------
@@ -631,18 +618,24 @@
The <authors> element is a container for author information for
documents with multiple authors.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
+
:Analogues: <authors> is analogous to the DocBook_ <authorgroup> element.
+
:Processing: See `\<docinfo>`_.
-:Parents: Only the `\<docinfo>`_ element contains <authors>.
-:Children: <authors> elements may contain the following elements:
- `\<author>`_, `\<organization>`_, `\<address>`_, `\<contact>`_::
+:Parent: `\<docinfo>`_
+
+:Children: `\<author>`_, `\<organization>`_, `\<address>`_, `\<contact>`_::
+
((author, organization?, address?, contact?)+)
-:Attributes: The <authors> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <authors>.
+:Attributes: only the `common attributes`_
+
+:Parameter Entities: `%bibliographic.elements`_ directly includes <authors>.
+
Examples
--------
@@ -681,20 +674,19 @@
The <block_quote> element is used for quotations set off from the
main text (standalone).
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <block_quote> is analogous to the <blockquote> element
in both HTML and DocBook_.
:Processing: <block_quote> elements serve to set their contents off from the
main text, typically with indentation and/or other decoration.
-:Parents: All elements employing the `%body.elements`_
- or `%structure.model`_ parameter entities in their
- content models may contain <block_quote>.
-:Children: <block_quote> elements contain `body elements`_
- followed by an optional `\<attribution>`_ element.
-:Attributes: The <block_quote> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <block_quote>. The `%structure.model`_
- parameter entity indirectly includes <block_quote>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: `body elements`_ followed by an optional `\<attribution>`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <block_quote>.
+ `%structure.model`_ indirectly includes <block_quote>.
Examples
--------
@@ -719,7 +711,6 @@
Anne Elk (Miss)
-
<bullet_list>
=============
@@ -727,21 +718,19 @@
uniformly marked with bullets. Bullets are typically simple dingbats
(symbols) such as circles and squares.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
-:Analogues: <bullet_list> is analogous to the HTML<ul> element [#]_
+:Analogues: <bullet_list> is analogous to the HTML_ <ul> element [#]_
and to the DocBook_ <itemizedlist> element.
:Processing: Each list item should begin a new vertical block,
prefaced by a bullet/dingbat.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <bullet_list>.
-:Children: <bullet_list> elements contain one or more
- `\<list_item>`_ elements.
-:Attributes: The <bullet_list> element contains the `common attributes`_
- plus bullet_.
-:Parameter Entities: The `%body.elements`_ parameter entity directly includes
- <bullet_list>. The `%structure.model`_ parameter entity
- indirectly includes <bullet_list>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `\<list_item>`_ elements
+:Attributes: the `common attributes`_ and bullet_
+:Parameter Entities: `%body.elements`_ directly includes <bullet_list>.
+ `%structure.model`_ indirectly includes <bullet_list>.
.. [#] HTML's <ul> is short for "unordered list", which we consider to be
a misnomer. "Unordered" implies that the list items may be randomly
@@ -788,18 +777,18 @@
self-contained notice. See also the generic `\<admonition>`_ and the
other `specific admonition elements`_.
+.. class:: run-in
+
: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
generated title "Caution" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their
- content models may contain <caution>.
-:Children: <caution> elements contain one or more `body elements`_.
-:Attributes: The <caution> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <caution>. The `%structure.model`_
- parameter entity indirectly includes <caution>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <caution>,
+ `%structure.model`_ indirectly includes <caution>.
Examples
--------
@@ -837,11 +826,10 @@
:Category: `Body Subelements`_ (simple)
:Analogues: <classifier> has no direct analogues in common DTDs.
It can be emulated with primitives or type effects.
-:Processing: See `\<definition_list_item>`_.
-:Parents: Only the `\<definition_list_item>`_ element contains <classifier>.
-:Children: <classifier> elements may contain text data plus
- `inline elements`_ (`%text.model`_).
-:Attributes: The <classifier> element contains only the `common attributes`_.
+:Processing: see `\<definition_list_item>`_
+:Parent: `\<definition_list_item>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -877,15 +865,15 @@
<colspec>
=========
-The <colspec> element is defined in the `Exchange Table Model`_.
-It contains specifications for a column in a `\<table>`_.
+The <colspec> element contains specifications for a column in a `\<table>`_.
+It is defined in the `Exchange Table Model`_.
:Category: `Body Subelements`_
:Analogues: <colspec> is analogous to the DocBook_ <colspec> element.
The HTML_ <col> element is related but has different semantics.
:Processing: See `colspec`__ in the `Exchange Table Model`.
-:Parents: Only the `\<tgroup>`_ element contains <colspec>.
-:Children: The <colspec> element has no content.
+:Parent: `\<tgroup>`_
+:Children: none (empty)
:Attributes: The `Exchange Table Model` defines the attributes
align_, char_, charoff_, colname_, colnum_, colsep_,
colwidth_, and rowsep_. [#]_
@@ -914,28 +902,21 @@
The <compound> element combines multiple `body elements`_
to a single logical paragraph.
+.. class:: run-in
+
:Category: `Body Elements`_
-
:Analogues: The <compound> element has no direct analogues in common DTDs.
In HTML, it can be emulated with <div> and CSS styling. [#]_
-
:Processing: Typically rendered as multiple distinct text blocks, with
the possibility of variations to emphasize their logical
unity (cf. the `"compound" directive`_).
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <compound>,
+ `%structure.model`_ indirectly includes <compound>.
-:Parents: All elements employing the `%body.elements`_
- or `%structure.model`_ parameter entities in
- their content models may contain <compound>.
-
-:Children: <compound> elements contain one or more `body elements`_.
-
-:Attributes: The <compound> element contains only the `common attributes`_.
-
-:Parameter Entities: The `%body.elements`_ parameter entity directly
- includes <compound>. The `%structure.model`_
- parameter entity indirectly includes <compound>.
-
-
.. [#] The Docutils counterpart to HTML’s <div> is the `\<container>`_ element.
Examples
@@ -975,17 +956,16 @@
(individual or group) of the document, or a third-party contact.
It is typically used for an email or web address.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <contact> is analogous to the DocBook_ <email> element.
The HTML <address> element serves a similar purpose.
:Processing: See `\<docinfo>`_.
-:Parents: The following elements may contain <contact>:
- `\<docinfo>`_, `\<authors>`_.
-:Children: <contact> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <contact> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <contact>.
+:Parents: `\<docinfo>`_, `\<authors>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <contact>.
Examples
--------
@@ -1018,28 +998,21 @@
The <container> element groups multiple `body elements`_ for user- or
application-specific purposes.
+.. class:: run-in
+
:Category: `Body Elements`_
-
:Analogues: The <container> element is analogous to the HTML <div>
element or the SVG <g> element.
-
:Processing: Can be used for styling or scripting purposes.
- An example is a frame or background colour) based
+ An example is a frame or background colour based
on the value of the classes_ attribute.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <container>,
+ `%structure.model`_ indirectly includes <container>.
-:Parents: All elements employing the `%body.elements`_
- or `%structure.model`_ parameter entities in
- their content models may contain <container>.
-
-:Children: <container> elements contain one or more `body elements`_.
-
-:Attributes: The <container> element contains only the `common attributes`_.
-
-:Parameter Entities:
- The `%body.elements`_ parameter entity directly
- includes <container>. The `%structure.model`_
- parameter entity indirectly includes <container>.
-
Examples
--------
@@ -1071,16 +1044,15 @@
The <copyright> element contains the document's copyright statement.
+.. class:: run-in
:Category: `Bibliographic Elements`_
:Analogues: <copyright> is analogous to the DocBook_ <copyright> element.
-:Processing: See `\<docinfo>`_.
-:Parents: Only the `\<docinfo>`_ element contains <copyright>.
-:Children: <copyright> elements may contain text data plus
- `inline elements`_ (`%text.model`_).
-:Attributes: The <copyright> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <copyright>.
+:Processing: see `\<docinfo>`_
+:Parent: `\<docinfo>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <copyright>.
Examples
--------
@@ -1112,19 +1084,19 @@
The <danger> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <danger> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "!DANGER!" (or similar).
-:Parents: All elements employing the `%body.elements`_
- or `%structure.model`_ parameter entities
- in their content models may contain <danger>.
-:Children: <danger> elements contain one or more `body elements`_.
-:Attributes: The <danger> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <danger>. The `%structure.model`_
- parameter entity indirectly includes <danger>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <danger>,
+ `%structure.model`_ indirectly includes <danger>.
See also the generic `\<admonition>`_ and the other
`specific admonition elements`_.
@@ -1149,15 +1121,15 @@
The <date> element contains the date of publication, release, or
last modification of the document.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <date> is analogous to the DocBook_ <date> element.
:Processing: Often used with the RCS/CVS keyword "Date". See `\<docinfo>`_.
-:Parents: Only the `\<docinfo>`_ element contains <date>.
-:Children: <date> elements may contain text data plus `inline elements`_
- (`%text.model`_).
-:Attributes: The <date> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <date>.
+:Parent: `\<docinfo>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <date>.
Examples
--------
@@ -1194,12 +1166,11 @@
:Analogues: There are no direct analogies to <decoration> in HTML or
in DocBook.
:Processing: See the individual `decorative elements`_.
-:Parents: Only the `\<document>`_ element contains <decoration>.
-:Children: <decoration> elements may contain the `decorative elements`_
- `\<header>`_ and/or `\<footer>`_.
+:Parent: `\<document>`_
+:Children: The `decorative elements`_ `\<header>`_ and/or `\<footer>`_.
Although the content model doesn't specifically require
contents, no empty <decoration> elements are ever created.
-:Attributes: The <decoration> element contains only the `common attributes`_.
+:Attributes: only the `common attributes`_
Examples
--------
@@ -1216,10 +1187,10 @@
:Analogues: <definition> is analogous to the HTML <dd> element
and to the DocBook_ <listitem> element
(inside a <variablelistentry> element).
-:Processing: See `\<definition_list_item>`_.
-:Parents: Only `\<definition_list_item>`_ elements contain <definition>.
-:Children: <definition> elements contain `body elements`_.
-:Attributes: The <definition> element contains only the `common attributes`_.
+:Processing: see `\<definition_list_item>`_
+:Parent: `\<definition_list_item>`_
+:Children: `body elements`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -1234,20 +1205,18 @@
definitions. It can be used for glossaries or dictionaries, to
describe or classify things, for dialogues, or to itemize subtopics.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <definition_list> is analogous to the HTML <dl> element
and to the DocBook_ <variablelist> element.
-:Processing: See `\<definition_list_item>`_.
-:Parents: All elements employing the `%body.elements`_
- or `%structure.model`_ parameter entities in their
- content models may contain <definition_list>.
-:Children: <definition_list> elements contain one or more
- `\<definition_list_item>`_ elements.
-:Attributes: The <definition_list> element contains only the
- `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <definition_list>. The `%structure.model`_
- parameter entity indirectly includes <definition_list>.
+:Processing: see `\<definition_list_item>`_
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `\<definition_list_item>`_ elements
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <definition_list>,
+ `%structure.model`_ indirectly includes <definition_list>.
See also `\<field_list>`_.
@@ -1300,8 +1269,7 @@
from the `\<term>`_. They should be separated visually,
typically by spaces plus a colon or dash.
-:Parents: Only the `\<definition_list>`_ element contains
- <definition_list_item>.
+:Parent: `\<definition_list>`_
:Children: <definition_list_item> elements each contain
one or more `\<term>`_ elements,
@@ -1312,8 +1280,7 @@
Changed in Docutils 0.22: allow multiple terms.
-:Attributes: The <definition_list_item> element contains only the
- `common attributes`_.
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -1369,10 +1336,10 @@
:Category: `Body Subelements`_
:Analogues: <description> has no direct analogues in common DTDs.
-:Processing: See `\<option_list>`_.
-:Parents: Only the `\<option_list_item>`_ element contains <description>.
-:Children: <description> elements may contain `body elements`_.
-:Attributes: The <description> element contains only the `common attributes`_.
+:Processing: see `\<option_list>`_
+:Parent: `\<option_list_item>`_
+:Children: `body elements`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -1403,11 +1370,11 @@
field bodies. For complete details, please see `RCS Keywords`_
in the `reStructuredText Markup Specification`_.
-:Parents: Only the `\<document>`_ element contains <docinfo>.
+:Parent: `\<document>`_
-:Children: <docinfo> elements contain `bibliographic elements`_.
+:Children: `bibliographic elements`_
-:Attributes: The <docinfo> element contains only the `common attributes`_.
+:Attributes: only the `common attributes`_.
See also the `\<meta>`_ element (for hidden meta-data).
@@ -1479,6 +1446,8 @@
The <doctest_block> element is a Python-specific variant of a
`\<literal_block>`_.
+.. class:: run-in
+
:Category: `Simple Body Elements`_
:Analogues: <doctest_block> is analogous to the HTML <pre> element
and to the DocBook_ <programlisting> and <screen> elements.
@@ -1486,16 +1455,12 @@
typically rendered in a monospaced typeface. It is crucial
that all 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
- may contain <doctest_block>.
-:Children: <doctest_block> elements may contain text data
- plus `inline elements`_ (`%text.model`_):
-:Attributes: The <doctest_block> element contains the `common attributes`_
- plus `xml:space`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <doctest_block>. The `%structure.model`_
- parameter entity indirectly includes <doctest_block>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: the `common attributes`_ and `xml:space`_
+:Parameter Entities: `%body.elements`_ directly includes <doctest_block>,
+ `%structure.model`_ indirectly includes <doctest_block>.
<doctest_block> elements are used for interactive Python interpreter
sessions, which are distinguished by their input prompt: ``>>>``.
@@ -1537,8 +1502,8 @@
:Parents: The <document> element has no parents.
-:Children: <document> elements may contain `structural elements`_,
- `structural subelements`_, and `body elements`_
+:Children: `structural elements`_, `structural subelements`_,
+ and `body elements`_
.. parsed-literal::
@@ -1551,9 +1516,7 @@
See the `%structure.model`_ parameter entity for details of
the body of a <document>.
-:Attributes: The <document> element contains the `common attributes`_
- plus an optional title_ attribute which stores the document
- title metadata.
+:Attributes: the `common attributes`_ and title_.
<document> is the direct or indirect ancestor of every other element in
the tree. It encloses the entire document tree. It is the starting
@@ -1612,11 +1575,9 @@
:Analogues: <emphasis> is analogous to the HTML_ <em> element
and the DocBook_ <emphasis> element.
:Processing: Typically displayed in italic type.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <emphasis>.
-:Children: <emphasis> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <emphasis> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -1640,8 +1601,8 @@
<entry>
=======
-The <entry> element is defined in the `Exchange Table Model`_.
-It represents one cell of a `\<table>`_.
+The <entry> element represents one cell of a `\<table>`_.
+It is defined in the `Exchange Table Model`_.
:Category: `Body Subelements`_
:Analogues: <entry> is analogous to the DocBook_ <entry> element.
@@ -1651,9 +1612,8 @@
attributes may be used to define an entry spanning several
table cells.
See entry__ in the `Exchange Table Model` for details.
-:Parents: The `\<thead>`_ and `\<tbody>`_ elements contain <entry> elements.
-:Children: <entry> elements may contain `body elements`_
- (via the `%tbl.entry.mdl`_ parameter entity).
+:Parents: `\<thead>`_, `\<tbody>`_
+:Children: `body elements`_ (via the `%tbl.entry.mdl`_ parameter entity)
:Attributes: The <entry> element accepts the colname_, namest_,
nameend_, morerows_, colsep_, rowsep_, align_, char_,
charoff_, and valign_ attributes (ignored by Docutils) and
@@ -1674,29 +1634,20 @@
The <enumerated_list> element contains `\<list_item>`_ elements which are
uniformly marked with enumerator labels.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
-
:Analogues: <enumerated_list> is analogous to the HTML <ol> element
and to the DocBook_ <orderedlist> element.
-
:Processing: Each list item should begin a new vertical block, prefaced
by a enumeration marker (such as "1.").
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `\<list_item>`_ elements
+:Attributes: enumtype_, prefix_, suffix_, start_, and the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <enumerated_list>,
+ `%structure.model`_ indirectly includes <enumerated_list>.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <enumerated_list>.
-
-:Children: <enumerated_list> elements contain one or more
- `\<list_item>`_ elements.
-
-:Attributes: The <enumerated_list> element contains the `common attributes`_
- plus enumtype_, prefix_, suffix_, and start_.
-
-:Parameter Entities:
- The `%body.elements`_ parameter entity directly includes
- <enumerated_list>. The `%structure.model`_ parameter entity
- indirectly includes <enumerated_list>.
-
Examples
--------
@@ -1739,19 +1690,19 @@
The <error> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <error> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Error" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <error>.
-:Children: <error> elements contain one or more `body elements`_.
-:Attributes: The <error> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity directly includes
- <error>. The `%structure.model`_ parameter entity indirectly
- includes <error>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <error>,
+ `%structure.model`_ indirectly includes <error>.
See also the generic `\<admonition>`_ and the other `specific admonition
elements`_.
@@ -1776,18 +1727,17 @@
The <field> element contains one item of a `\<field_list>`_,
a pair of `\<field_name>`_ and `\<field_body>`_ elements.
+.. class:: run-in
+
:Category: `Body Subelements`_
:Analogues: <field> has no direct analogues in common DTDs.
HTML5 uses <div> elements inside <dl> lists for
grouping <dt>/<dd> pairs.
:Processing: See `\<field_list>`_.
-:Parents: The following elements may contain <field>:
- `\<docinfo>`_, `\<field_list>`_
-:Children: Each <field> element contains one `\<field_name>`_ and one
- `\<field_body>`_ element.
-:Attributes: The <field> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <field>.
+:Parents: `\<docinfo>`_, `\<field_list>`_
+:Children: one `\<field_name>`_ and one `\<field_body>`_ element
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <field>.
Examples
--------
@@ -1801,10 +1751,10 @@
:Category: `Body Subelements`_
:Analogues: <field_body> is analogous to the HTML <dd> element.
-:Processing: See `\<field_list>`_.
-:Parents: Only the `\<field>`_ element contains <field_body>.
-:Children: <field_body> elements may contain `body elements`_.
-:Attributes: The <field_body> element contains only the `common attributes`_.
+:Processing: see `\<field_list>`_
+:Parent: `\<field>`_
+:Children: `body elements`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -1817,6 +1767,8 @@
The <field_list> element contains two-column table-like structures
resembling database records (label & data pairs).
+.. class:: run-in
+
: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,
@@ -1824,14 +1776,12 @@
colon suffix). However, field lists are often used for
extension syntax or special processing. Such structures do
not survive as field lists to be rendered.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their
- content models may contain <field_list>.
-:Children: <field_list> elements contain one or more `\<field>`_ elements.
-:Attributes: The <field_list> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <field_list>. The `%structure.model`_
- parameter entity indirectly includes <field_list>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `\<field>`_ elements
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <field_list>,
+ `%structure.model`_ indirectly includes <field_list>.
Field lists are often meant for further processing.
In reStructuredText_, field lists are used to represent bibliographic
@@ -1885,10 +1835,9 @@
:Category: `Body Subelements`_ (simple)
:Analogues: <field_name> is analogous to the HTML <dt> element.
:Processing: See `\<field_list>`_.
-:Parents: Only the `\<field>`_ element contains <field_name>.
-:Children: <field_name> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <field_name> element contains only the `common attributes`_.
+:Parent: `\<field>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -1913,9 +1862,9 @@
are no direct analogies to <footer> in HTML4 or DocBook.
Equivalents are typically constructed from primitives and/or
generated by the processing system.
-:Parents: Only the `\<decoration>`_ element contains <footer>.
-:Children: <footer> elements may contain `body elements`_.
-:Attributes: The <footer> element contains only the `common attributes`_.
+:Parent: `\<decoration>`_
+:Children: `body elements`_
+:Attributes: only the `common attributes`_.
The <footer> element may contain processing information (datestamp, a
link to Docutils_, etc.) as well as custom content.
@@ -1952,6 +1901,8 @@
.. _notes: https://en.wikipedia.org/wiki/Note_(typography)
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <footnote> has no direct analogues in DocBook or HTML.
@@ -1983,9 +1934,8 @@
Footnotes may "float" to the bottom or margin of a page or a
dedicated section.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <footnote>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
:Children: <footnote> elements begin with an optional [#]_ `\<label>`_
and contain `body elements`_. ::
@@ -1992,12 +1942,10 @@
(label?, (%body.elements;)+)
-:Attributes: The <footnote> element contains the `common attributes`_
- plus auto_ and backrefs_.
+:Attributes: the `common attributes`_ plus auto_ and backrefs_
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <footnote>. The `%structure.model`_
- parameter entity indirectly includes <footnote>.
+:Parameter Entities: `%body.elements`_ directly includes <footnote>,
+ `%structure.model`_ indirectly includes <footnote>.
.. [#] The footnote label will become mandatory in Docutils 1.0.
@@ -2033,11 +1981,9 @@
`\<label>`_ of the referenced footnote. The mark is
typically formatted as superscript or enclosed in square
brackets.
-:Parents: All elements employing the `%text.model`_ parameter entity
- in their content models may contain <footnote-reference>.
-:Children: <footnote_reference> elements contain text data only.
-:Attributes: The <footnote_reference> element contains the
- `common attributes`_ plus auto_, refid_, and refname_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: only text data
+:Attributes: auto_, refid_, refname, and _the `common attributes`_.
Examples
--------
@@ -2092,9 +2038,9 @@
There are no direct analogies to <header> in HTML4 or DocBook.
Equivalents are typically constructed from primitives and/or
generated by the processing system.
-:Parents: Only the `\<decoration>`_ element contains <header>.
-:Children: <header> elements may contain `body elements`_.
-:Attributes: The <header> element contains only the `common attributes`_.
+:Parent: `\<decoration>`_
+:Children: `body elements`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2118,19 +2064,19 @@
The <hint> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <hint> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Hint" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their
- content models may contain <hint>.
-:Children: <hint> elements contain one or more `body elements`_.
-:Attributes: The <hint> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <hint>. The `%structure.model`_
- parameter entity indirectly includes <hint>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <hint>,
+ `%structure.model`_ indirectly includes <hint>.
See also the generic `\<admonition>`_ and the other
`specific admonition elements`_.
@@ -2155,6 +2101,8 @@
The <image> element refers to an image resource that should be included
in the document.
+.. class:: run-in
+
:Categories: `Body Elements`_, `Inline Elements`_
:Analogues: <image> is analogous to the `HTML \<img>`_,
`DocBook \<imagedata>`_, and `SVG \<image>`_ elements.
@@ -2161,16 +2109,14 @@
: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 data.
-:Parents: All elements employing the `%body.elements`_,
- `%text.model`_, or `%structure.model`_ parameter entities
- in their content models may contain <image>.
-:Children: The <image> element has no content.
-:Attributes: The <image> element contains the `common attributes`_ plus
- uri_, alt_, align_, height_, width_, scale_, and loading_.
-:Parameter Entities:
- The `%body.elements`_ and `%inline.elements`_ parameter
- entities directly include <image>. The `%structure.model`_
- and `%text.model`_ parameter entities indirectly include <image>.
+:Parents: all elements employing `%body.elements`_, `%text.model`_,
+ or `%structure.model`_ in their content models
+:Children: none (empty)
+:Attributes: uri_, alt_, align_, height_, width_, scale_, loading_,
+ and the `common attributes`_
+:Parameter Entities: `%body.elements`_ and `%inline.elements`_
+ directly include <image>, `%structure.model`_
+ and `%text.model`_ indirectly include <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, ...).
@@ -2201,18 +2147,18 @@
The <important> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <important> is analogous to the `DocBook \<important>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Important" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their
- content models may contain <important>.
-:Children: <important> elements contain one or more `body elements`_.
-:Attributes: The <important> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <important>. The `%structure.model`_
- parameter entity indirectly includes <important>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <important>,
+ `%structure.model`_ indirectly includes <important>.
See also the generic `\<admonition>`_ and the other
`specific admonition elements`_.
@@ -2258,11 +2204,9 @@
render the content distinctly for specific class values.
Moreover, writers may ignore the element and just render
the content.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <inline>.
-:Children: <inline> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <inline> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2306,9 +2250,9 @@
:Analogues: <line> has no direct analogues in common DTDs.
It can be emulated with primitives or type effects.
:Processing: See `\<line_block>`_.
-:Parents: Only the `\<line_block>`_ element contains <line>.
-:Children: <line> elements may contain text data plus `inline elements`_.
-:Attributes: The <line> element contains only the `common attributes`_.
+:Parent: `\<line_block>`_
+:Children: text data plus `inline elements`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2321,6 +2265,8 @@
The <line_block> element contains a sequence of lines and nested line
blocks.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <line_block> is analogous to the DocBook_ <literallayout>
@@ -2332,20 +2278,17 @@
Unlike <literal_block>, <line_block> elements are
typically rendered in an ordinary text typeface.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <line_block>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
-:Children: <line_block> elements may contain `\<line>`_ elements and
- nested <line_block> elements. ::
+:Children: `\<line>`_ elements and nested <line_block> elements::
(line | line_block)+
-:Attributes: The <line_block> element contains only the `common attributes`_.
+:Attributes: only the `common attributes`_
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <line_block>. The `%structure.model`_
- parameter entity indirectly includes <line_block>.
+:Parameter Entities: `%body.elements`_ directly includes <line_block>,
+ `%structure.model`_ indirectly includes <line_block>.
<line_block> elements are commonly used for verse and addresses.
See `\<literal_block>`_ for an alternative useful for
@@ -2422,10 +2365,9 @@
:Analogues: <list_item> is analogous to the HTML <li> element
and to the DocBook_ <listitem> element.
:Processing: See `\<bullet_list>`_ or `\<enumerated_list>`_.
-:Parents: The `\<bullet_list>`_ and `\<enumerated_list>`_ elements
- contain <list_item>.
-:Children: <list_item> elements may contain `body elements`_.
-:Attributes: The <list_item> element contains only the `common attributes`_.
+:Parents: `\<bullet_list>`_, `\<enumerated_list>`_
+:Children: `body elements`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2474,6 +2416,8 @@
Details
-------
+.. class:: run-in
+
:Category: `Simple Body Elements`_
:Analogues: <literal_block> is analogous to the HTML <pre> element
and to the DocBook_ <programlisting> and <screen> elements.
@@ -2480,16 +2424,12 @@
:Processing: <literal_block> elements are typically rendered in a
monospaced typeface. It is crucial that all 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
- may contain <literal_block>.
-:Children: <literal_block> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <literal_block> element contains the `common attributes`_
- plus `xml:space`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <literal_block>. The `%structure.model`_
- parameter entity indirectly includes <literal_block>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: the `common attributes`_ and `xml:space`_
+:Parameter Entities: `%body.elements`_ directly includes <literal_block>,
+ `%structure.model`_ indirectly includes <literal_block>.
<literal_block> elements are commonly used for program listings and
interactive computer sessions.
@@ -2536,10 +2476,9 @@
:Processing: Rendered as mathematical notation.
If the output format does not support math typesetting,
the content may be inserted verbatim.
-:Parents: All elements employing the `%text.model`_
- parameter entity in their content models may contain <math>.
-:Children: <math> elements contain text data only.
-:Attributes: The <math> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: only text data
+:Attributes: only the `common attributes`_.
Example
-------
@@ -2574,12 +2513,10 @@
centered or with indentation
If the output format does not support math typesetting,
the content may be inserted verbatim.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <math_block>.
-:Children: <math_block> elements contain text data only.
-:Attributes: The <math_block> element contains the `common attributes`_
- plus `xml:space`_.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: only text data
+:Attributes: the `common attributes`_ and `xml:space`_.
Example
-------
@@ -2616,13 +2553,14 @@
Meta-data may also be extracted from `\<docinfo>`_ children
or the `\<document>`_ attributes (title).
-:Parents: Only the `\<document>`_ element contains <meta>.
-:Children: The <meta> element has no content.
-:Attributes: The <meta> element contains the attributes
- *content*, *dir*, *http-equiv*, *lang*, *media*, *name*, and
- *scheme* that correspond to the respective attributes of the
- `HTML <meta> element`_.
+:Parent: `\<document>`_
+:Children: none (empty)
+
+:Attributes: the attributes *content*, *dir*, *http-equiv*, *lang*,
+ *media*, name_, and *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.
@@ -2650,18 +2588,18 @@
The <note> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <note> is analogous to the `DocBook \<note>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Note" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <note>.
-:Children: <note> elements contain one or more `body elements`_.
-:Attributes: The <note> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <note>. The `%structure.model`_
- parameter entity indirectly includes <note>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <note>,
+ `%structure.model`_ indirectly includes <note>.
See also the generic `\<admonition>`_ and the other
`specific admonition elements`_.
@@ -2691,13 +2629,13 @@
:Category: `Body Subelements`_
:Analogues: <option> has no direct analogues in common DTDs.
:Processing: See `\<option_list>`_.
-:Parents: Only the `\<option_group>`_ element contains <option>.
+:Parent: `\<option_group>`_
:Children: <option> elements start with an `\<option_string>`_ and
may contain `\<option_argument>`_ elements::
(option_string, option_argument*)
-:Attributes: The <option> element contains only the `common attributes`_.
+:Attributes: only the `common attributes`_.
Note that reStructuredText_ currently supports only one argument per
option.
@@ -2721,10 +2659,9 @@
The <option_argument> text is typically rendered in a
monospaced typeface, possibly italicized or otherwise
altered to indicate its placeholder nature.
-:Parents: Only the `\<option>`_ element contains <option_argument>.
-:Children: <option_argument> elements contain text data only.
-:Attributes: The <option_argument> element contains
- the `common attributes`_ plus delimiter_.
+:Parent: `\<option>`_
+:Children: only text data
+:Attributes: the `common attributes`_ and delimiter_.
Examples
--------
@@ -2741,10 +2678,9 @@
:Analogues: <option_group> has no direct analogues in common DTDs.
:Processing: Typically `\<option>`_ elements within an <option_group> are
joined together in a comma-separated list.
-:Parents: Only the `\<option_list_item>`_ element contains <option_group>.
-:Children: <option_group> elements contain one or more `\<option>`_
- elements.
-:Attributes: The <option_group> element contains only the `common attributes`_.
+:Parent: `\<option_list_item>`_
+:Children: one or more `\<option>`_ elements.
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2757,6 +2693,8 @@
Each <option_list> element contains a two-column list of command-line
options and descriptions, documenting a program's options.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <option_list> has no direct analogues in common DTDs.
It can be emulated with primitives such as tables.
@@ -2763,15 +2701,12 @@
:Processing: An <option_list> is typically rendered as a two-column list,
where the first column contains option strings and
arguments, and the second column contains descriptions.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their
- content models may contain <option_list>.
-:Children: <option_list> elements contain one or more `\<option_list_item>`_
- elements.
-:Attributes: The <option_list> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <option_list>. The `%structure.model`_
- parameter entity indirectly includes <option_list>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `\<option_list_item>`_ elements.
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <option_list>,
+ `%structure.model`_ indirectly includes <option_list>.
Examples
--------
@@ -2823,12 +2758,10 @@
:Category: `Body Subelements`_
:Analogues: <option_list_item> has no direct analogues in common DTDs.
-:Processing: See `\<option_list>`_.
-:Parents: Only the `\<option_list>`_ element contains <option_list_item>.
-:Children: Each <option_list_item> element contains one `\<option_group>`_
- and one `\<description>`_ element.
-:Attributes: The <option_list_item> element contains only the
- `common attributes`_.
+:Processing: see `\<option_list>`_
+:Parent: `\<option_list>`_
+:Children: one `\<option_group>`_ and one `\<description>`_
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2844,10 +2777,9 @@
:Analogues: <option_string> has no direct analogues in common DTDs.
:Processing: The <option_string> text is typically rendered in a
monospaced typeface.
-:Parents: Only the `\<option>`_ element contains <option_string>.
-:Children: <option_string> elements contain text data only.
-:Attributes: The <option_string> element contains only the
- `common attributes`_.
+:Parent: `\<option>`_
+:Children: only text data
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -2860,17 +2792,17 @@
The <organization> element contains the name of document author's
organization, or the organization responsible for the document.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <organization> is analogous to the DocBook_ <orgname>,
<corpname>, or <publishername> elements.
:Processing: See `\<docinfo>`_.
-:Parents: Only the `\<docinfo>`_ element contains <organization>.
-:Children: <organization> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <organization> element contains only the
- `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <organization>.
+:Parent: `\<docinfo>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes
+ <organization>.
Examples
--------
@@ -2902,18 +2834,17 @@
The <paragraph> element contains the text and inline elements of a
single paragraph, a fundamental building block of documents.
+.. class:: run-in
+
:Category: `Simple Body Elements`_
:Analogues: <paragraph> is analogous to the HTML <p> element
and to the DocBook_ <para> elements.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <paragraph>.
-:Children: <paragraph> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <paragraph> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <paragraph>. The `%structure.model`_
- parameter entity indirectly includes <paragraph>.
+: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`_
+:Parameter Entities: `%body.elements`_ directly includes <paragraph>,
+ `%structure.model`_ indirectly includes <paragraph>.
Examples
--------
@@ -2948,12 +2879,9 @@
:Processing: Typically displayed in red colour.
If the refid_ attribute is present, the element should
point to the referenced element.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <problematic>.
-:Children: <problematic> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <problematic> element contains the `common attributes`_
- and refid_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: the `common attributes`_ and refid_.
Examples
--------
@@ -2985,21 +2913,20 @@
The <raw> element contains non-reStructuredText data that is to be passed
untouched to the Writer.
+.. class:: run-in
+
:Category: `Simple Body Elements`_, `Inline Elements`_
:Analogues: The <raw> element has no direct analogues in common DTDs.
:Processing: Passed untouched to the Writer_.
The interpretation is up to the Writer.
A Writer may ignore <raw> elements not matching its format_.
-:Parents: All elements employing the `%body.elements`_,
- `%structure.model`_, or `%text.model`_ parameter entities
- in their content models may contain <raw>.
-:Children: <raw> elements contain text data only.
-:Attributes: The <raw> element contains the `common attributes`_
- plus format_ and `xml:space`_.
-:Parameter Entities:
- The `%body.elements`_ and `%inline.elements`_ parameter
- entities directly include <raw>. The `%structure.model`_
- and `%text.model`_ parameter entities indirectly include <raw>.
+:Parents: all elements employing `%body.elements`_, `%structure.model`_,
+ or `%text.model`_ in their content models
+:Children: only text data
+:Attributes: the `common attributes`_ plus format_ and `xml:space`_
+:Parameter Entities: `%body.elements`_ and `%inline.elements`_
+ directly include <raw>, `%structure.model`_ and
+ `%text.model`_ indirectly include <raw>.
Examples
--------
@@ -3031,6 +2958,8 @@
The <revision> element contains the revision number of the document.
It can be used alone or in conjunction with `\<version>`_.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <revision> is analogous to but simpler than the DocBook_
<revision> element. It closely matches the DocBook
@@ -3037,12 +2966,10 @@
<revnumber> element, but in a simpler context.
:Processing: Often used with the RCS/CVS keyword "Revision".
See `\<docinfo>`_.
-:Parents: Only the `\<docinfo>`_ element contains <revision>.
-:Children: <revision> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <revision> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <revision>.
+:Parent: `\<docinfo>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <revision>.
Examples
--------
@@ -3074,8 +3001,8 @@
<row>
=====
-The <row> element is defined in the `Exchange Table Model`_.
-It represents one row of a `\<table>`_.
+The <row> element represents one row of a `\<table>`_.
+It is defined in the `Exchange Table Model`_.
:Category: `Body Subelements`_
:Analogues: <row> is analogous to the HTML_ <tr> element
@@ -3082,8 +3009,8 @@
and the DocBook_ <row> element.
:Processing: Render content as a table row.
See row__ in the `Exchange Table Model` for details.
-:Parents: The `\<thead>`_ and `\<tbody>`_ elements contain <row> elements.
-:Children: A <row> element contains one or more `\<entry>`_ elements.
+:Parents: `\<thead>`_, `\<tbody>`_
+:Children: one or more `\<entry>`_ elements
:Attributes: The <row> element may contain the rowsep_ and valign_
attributes (ignored by Docutils) and (via the
`%tbl.row.att`_ parameter entity) the `common attributes`_.
@@ -3116,6 +3043,8 @@
The <section> element is the main unit of hierarchy for Docutils documents.
+.. class:: run-in
+
:Category: `Structural Elements`_
:Analogues: <section> is analogous to the section elements in DocBook_ and
@@ -3123,8 +3052,7 @@
``<sect1>`` … ``<sect5>`` in DocBook_, the level is not
incorporated into the element name.
-:Parents: The following elements may contain <section>:
- `\<document>`_, `\<section>`_
+:Parents: `\<document>`_, `\<section>`_
:Children: <section> elements begin with a `\<title>`_,
followed by an optional `\<subtitle>`_.
@@ -3135,14 +3063,13 @@
(title, subtitle?, `%structure.model`_;)
-:Attributes: The <section> element contains only the `common attributes`_.
+:Attributes: only the `common attributes`_
-:Parameter Entities: The `%section.elements`_ parameter entity
- directly includes <section>. The `%structure.model`_
- parameter entity indirectly includes <section>.
+:Parameter Entities: `%section.elements`_ directly includes <section>,
+ `%structure.model`_ indirectly includes <section>.
The Docutils document model uses a simple, recursive model for section
-structure. A `\<document>`_ node may contain <section> elements.
+structure. A `\<document>`_ nodeelements.
Sections in turn may contain other <section> elements, without limit.
The level (depth) of a section element is determined from its physical
nesting level.
@@ -3206,6 +3133,8 @@
documents, providing related or reference material.
Their content is outside of the flow of the document's main text.
+.. class:: run-in
+
:Category: `Structural Elements`_
:Analogues: <sidebar> is analogous to the DocBook_ <sidebar> and
@@ -3216,8 +3145,7 @@
typically "float" to the side of the page and the document's
main text flows around them.
-:Parents: The following elements may contain <sidebar>:
- `\<document>`_, `\<section>`_.
+:Parents: `\<document>`_, `\<section>`_.
:Children: <sidebar> elements begin with optional
`\<title>`_ and `\<subtitle>`_ and contain
@@ -3227,10 +3155,9 @@
((title, subtitle?)?,
(%body.elements; | topic)+)
-:Attributes: The <sidebar> element contains only the `common attributes`_.
+:Attributes: only the `common attributes`_
-:Parameter Entities: The `%structure.model`_ parameter entity
- directly includes <sidebar>.
+:Parameter Entities: `%structure.model`_ 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
@@ -3265,15 +3192,15 @@
The <status> element contains a status statement for the document,
such as "Draft", "Final", "Work In Progress", etc.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <status> is analogous to the DocBook_ <status> element.
:Processing: See `\<docinfo>`_.
-:Parents: Only the `\<docinfo>`_ element contains <status>.
-:Children: <status> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <status> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <status>.
+:Parent: `\<docinfo>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <status>.
Examples
--------
@@ -3308,11 +3235,9 @@
:Category: `Inline Elements`_
:Analogues: <strong> is analogous to the HTML_ <strong> element.
:Processing: Typically displayed in boldface.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <strong>.
-:Children: <strong> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <strong> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -3344,11 +3269,9 @@
:Analogues: <subscript> is analogous to the HTML_ <sub> element
and the DocBook_ <subscript> element.
:Processing: Typically rendered with a lowered baseline using smaller text.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <subscript>.
-:Children: <subscript> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <subscript> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -3393,11 +3316,9 @@
a <hgroup_> element.
:Processing: A document's subtitle is usually rendered smaller
than its `\<title>`_.
-:Parents: The `\<document>`_, `\<section>`_, and `\<sidebar>`_ elements
- may contain <subtitle>.
-:Children: <subtitle> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <subtitle> element contains only the `common attributes`_.
+:Parents: `\<document>`_, `\<section>`_, and `\<sidebar>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -3444,11 +3365,9 @@
:Analogues: <superscript> is analogous to the HTML_ <sup> element
and the DocBook_ <superscript> element.
:Processing: Typically rendered with a raised baseline using smaller text.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <superscript>.
-:Children: <superscript> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <superscript> element contains only the `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -3472,6 +3391,8 @@
The <system_message> element is used for feedback from the processing
system.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <system_message> has no direct analogues in common DTDs.
It can be emulated with primitives and type effects.
@@ -3478,15 +3399,12 @@
:Processing: Rendered similar to an `\<admonition>`_, with the generated
title "System Message", its type_/level_ and, if available,
source_ and line_.
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <system_message>.
-:Children: <system_message> elements contain one or more `body elements`_.
-:Attributes: The <system_message> element accepts the `common
- attributes`_ plus backrefs_, level_, line_, and type_.
-:Parameter Entities: The `%body.elements`_ parameter entity directly includes
- <system_message>. The `%structure.model`_ parameter entity
- indirectly includes <system_message>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: backrefs_, level_, line_, type_, and the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <system_message>,
+ `%structure.model`_ indirectly includes <system_message>.
In Docutils, the generation of system messages can be configured with the
`report_level`_ setting.
@@ -3512,9 +3430,11 @@
<table>
=======
-The <table> element is defined in the `Exchange Table Model`_.
-It represents a data arrangement with rows and columns.
+The <table> element represents a data arrangement with rows and columns.
+It is defined in the `Exchange Table Model`_.
+.. class:: run-in
+
:Category: `Body Elements`_
:Analogues: <table> is analogous to the HTML_ and DocBook_ <table> elements.
@@ -3523,7 +3443,6 @@
See table__ in the `Exchange Table Model` for details.
:Parents: `\<document>`_, `\<section>`_ and all `body elements`_
- may contain <table>.
:Children: <table> elements begin with an optional `\<title>`_ (caption)
and may contain one or more `\<tgroup>`_ elements::
@@ -3535,9 +3454,8 @@
and (via the `%bodyatt`_ parameter entity)
the `common attributes`_, align_, and width_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <table>. The `%structure.model`_
- parameter entity indirectly includes <table>.
+:Parameter Entities: `%body.elements`_ directly includes <table>,
+ `%structure.model`_ indirectly includes <table>.
__ https://www.oasis-open.org/specs/tm9901.html#AEN142
@@ -3585,19 +3503,18 @@
<tbody>
=======
-The <tbody> element is defined in the `Exchange Table Model`_.
-It identifies the rows that form the *body* of a `\<table>`_
-(as distinct from the header rows).
+The <tbody> element identifies the rows that form the *body* of a
+`\<table>`_ (as distinct from the header rows).
+It is defined in the `Exchange Table Model`_.
:Category: `Body Subelements`_
:Analogues: <tbody> is analogous to the HTML_ <tbody> and
the DocBook_ <tbody> (db.cals.tbody) elements.
:Processing: Render content as table body.
-:Parents: Only the `\<tgroup>`_ element contains <tbody>.
-:Children: A <tbody> element contains one or more `\<row>`_ elements.
-:Attributes: The <tbody> element may contain valign_ (ignored by Docutils)
- and (via the `%tbl.tbody.att`_ parameter entity)
- the `common attributes`_.
+:Parent: `\<tgroup>`_
+:Children: one or more `\<row>`_ elements
+:Attributes: valign_ (ignored by Docutils) and the `common attributes`_
+ (via the `%tbl.tbody.att`_ parameter entity).
Examples
--------
@@ -3614,11 +3531,10 @@
:Category: `Body Subelements`_ (simple)
:Analogues: <term> is analogous to the HTML <dt> element
and to the DocBook_ <term> element.
-:Processing: See `\<definition_list_item>`_.
-:Parents: Only the `\<definition_list_item>`_ element contains <term>.
-:Children: <term> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <term> element contains only the `common attributes`_.
+:Processing: see `\<definition_list_item>`_
+:Parent: `\<definition_list_item>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -3629,8 +3545,8 @@
<tgroup>
========
-The <tgroup> element is defined in the `Exchange Table Model`_.
-It identifies a logically complete portion of a `\<table>`_.
+The <tgroup> element identifies a logically complete portion of a `\<table>`_.
+It is defined in the `Exchange Table Model`_.
:Category: `Body Subelements`_
:Analogues: <tgroup> is analogous to the DocBook_ <tgroup> element.
@@ -3637,12 +3553,13 @@
There is no corresponding HTML element (the <colgroup>
element has a different purpose and semantics).
:Processing: See tgroup__ in the `Exchange Table Model`.
-:Parents: Only the `\<table>`_ element contains <tgroup>.
-:Children: <tgroup> elements contain one or more `\<colspec>`_
- elements, followed by an optional `\<thead>`_ and a
- `\<tbody>`_ (cf. the `%tbl.tgroup.mdl`_ parameter entity).
- The number of <colspec>s, must not exceed the value of the cols_
- attribute. Docutils expects one <colspec> per column.
+:Parent: `\<table>`_
+:Children: One or more `\<colspec>`_ elements, followed by an optional
+ `\<thead>`_ and a `\<tbody>`_ (cf. the `%tbl.tgroup.mdl`_
+ parameter entity).
+ The number of <colspec>s, must not exceed
+ the value of the cols_ attribute. Docutils expects one
+ <colspec> per column.
:Attributes: The <tgroup> element must contain a cols_ attribute and may
contain colsep_, rowsep_, and align_ (ignored by Docutils).
Via the `%tbl.tgroup.att`_ parameter entity, <tgroup>
@@ -3665,9 +3582,9 @@
<thead>
=======
-The <thead> element is defined in the `Exchange Table Model`_.
-It identifies the row(s) that form the *head* of a `\<table>`_
-(as distinct from the body rows).
+The <thead> element identifies the row(s) that form the *head* of a
+`\<table>`_ (as distinct from the body rows).
+It is defined in the `Exchange Table Model`_.
:Category: `Body Subelements`_
:Analogues: <thead> is analogous to the HTML_ and DocBook_ <thead> elements.
@@ -3676,11 +3593,11 @@
such as boldface.
In paged media, if a table spans across multiple pages,
header rows are printed at the top of each new page.
-:Parents: Only the `\<tgroup>`_ element contains <thead>.
-:Children: A <thead> element contains one or more `\<row>`_ elements.
-:Attributes: The <thead> element contains the valign_ attribute
- (ignored by Docutils) and (via the `%tbl.thead.att`_
- parameter entity) the `common attributes`_.
+:Parent: `\<tgroup>`_
+:Children: one or more `\<row>`_ elements
+:Attributes: the valign_ attribute (ignored by Docutils) and
+ (via the `%tbl.thead.att`_ parameter entity)
+ the `common attributes`_.
Examples
--------
@@ -3694,18 +3611,18 @@
The <tip> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <tip> is analogous to the `DocBook \<tip>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Tip" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <tip>.
-:Children: <tip> elements contain one or more `body elements`_.
-:Attributes: The <tip> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <tip>. The `%structure.model`_
- parameter entity indirectly includes <tip>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <tip>,
+ `%structure.model`_ indirectly includes <tip>.
See also the generic `\<admonition>`_ and the other `specific admonition
elements`_.
@@ -3737,12 +3654,10 @@
element corresponds to a <document>'s `title attribute`_.
As child of a `\<table>`_, <title> corresponds to
the HTML <caption> element.
-:Parents: The following elements may contain <title>:
- `\<admonition>`_, `\<document>`_, `\<section>`_,
- `\<sidebar>`_, `\<table>`_, `\<topic>`_.
-:Children: <title> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <title> element contains the `common attributes`_
+:Parents: `\<admonition>`_, `\<document>`_, `\<section>`_,
+ `\<sidebar>`_, `\<table>`_, and `\<topic>`_.
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: the `common attributes`_
plus refid_ (used as a backlink to a table of contents entry)
and auto_ (for auto-numbered section titles).
@@ -3789,12 +3704,9 @@
:Analogues: <title_reference> is analogous to the HTML_ <cite> element
and the DocBook_ <citetitle> element.
:Processing: Typically displayed in italic type.
-:Parents: All elements employing the `%text.model`_ parameter
- entity in their content models may contain <title_reference>.
-:Children: <title_reference> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <title_reference> element contains only the
- `common attributes`_.
+:Parents: all elements employing `%text.model`_ in their content models
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_.
Examples
--------
@@ -3820,6 +3732,8 @@
The <topic> element represents a non-recursive section-like construct for
content that is separate from the flow of the document.
+.. class:: run-in
+
:Category: `Structural Elements`_
:Analogues: <topic> is analogous to the DocBook_ <simplesect> element
@@ -3829,8 +3743,7 @@
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>`_
+:Parents: `\<document>`_, `\<section>`_, and `\<sidebar>`_
:Children: <topic> elements may begin with a `\<title>`_ and contain
`body elements`_::
@@ -3837,10 +3750,9 @@
(title?, (%body.elements;)+)
-:Attributes: The <topic> element accepts the `common attributes`_.
+:Attributes: only the `common attributes`_
-:Parameter Entities: The `%structure.model`_ parameter entity
- directly includes <topic>.
+:Parameter Entities: `%structure.model`_ directly includes <topic>.
Topics are terminal, "leaf" mini-sections, like block quotes with titles,
or textual figures. A <topic> is just like a `\<section>`_, except that
@@ -3882,6 +3794,8 @@
The <transition> element separates body elements and sections, dividing a
`\<section>`_ into untitled divisions.
+.. class:: run-in
+
:Category: `Structural Subelements`_
:Analogues: <transition> is analogous to the HTML <hr> element.
:Processing: The <transition> element is typically rendered as vertical
@@ -3889,12 +3803,10 @@
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: The following elements may contain <transition>:
- `\<document>`_, `\<section>`_
-:Children: The <transition> element has no content.
-:Attributes: The <transition> element contains only the `common attributes`_.
-:Parameter Entities: The `%structure.model`_ parameter entity
- directly includes <transition>.
+:Parents: `\<document>`_, `\<section>`_
+:Children: none (empty)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%structure.model`_ directly includes <transition>.
A transition may not begin or end a section [#]_ or document, nor may two
transitions be immediately adjacent.
@@ -3938,17 +3850,17 @@
The <version> element contains the version number of the document.
It can be used alone or in conjunction with `\<revision>`_.
+.. class:: run-in
+
:Category: `Bibliographic Elements`_
:Analogues: <version> may be considered analogous to the DocBook_
<revision>, <revnumber>, or <biblioid> elements.
:Processing: Sometimes used with the RCS/CVS keyword "Revision".
See `\<docinfo>`_ and `\<revision>`_.
-:Parents: Only the `\<docinfo>`_ element contains <version>.
-:Children: <version> elements may contain text data
- plus `inline elements`_ (`%text.model`_).
-:Attributes: The <version> element contains only the `common attributes`_.
-:Parameter Entities: The `%bibliographic.elements`_ parameter entity
- directly includes <version>.
+:Parent: `\<docinfo>`_
+:Children: text data plus `inline elements`_ (`%text.model`_)
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%bibliographic.elements`_ directly includes <version>.
Examples
--------
@@ -3980,18 +3892,18 @@
The <warning> element is a specific *admonition*, a distinctive and
self-contained notice.
+.. class:: run-in
+
:Category: `Compound Body Elements`_
:Analogues: <warning> is analogous to the `DocBook \<warning>`_ element.
:Processing: Rendered distinctly (inset and/or in a box, etc.),
with the generated title "Warning" (or similar).
-:Parents: All elements employing the `%body.elements`_ or
- `%structure.model`_ parameter entities in their content models
- may contain <warning>.
-:Children: <warning> elements contain one or more `body elements`_.
-:Attributes: The <warning> element contains only the `common attributes`_.
-:Parameter Entities: The `%body.elements`_ parameter entity
- directly includes <warning>. The `%structure.model`_
- parameter entity indirectly includes <warning>.
+:Parents: all elements employing `%body.elements`_ or
+ `%structure.model`_ in their content models
+:Children: one or more `body elements`_
+:Attributes: only the `common attributes`_
+:Parameter Entities: `%body.elements`_ directly includes <warning>,
+ `%structure.model`_ indirectly includes <warning>.
See also the generic `\<admonition>`_ and the other
`specific admonition elements`_.
@@ -4267,7 +4179,8 @@
Attribute type: `%classnames.type`_. Default value: none.
The ``classes`` attribute is a space separated list containing zero or
-more `class names`_.
+more `class names`_. It is one of the `common attributes`_, shared by
+all Docutils elements.
The purpose of the attribute is to indicate an "is-a" variant relationship,
to allow an extensible way of defining sub-classes of existing elements.
@@ -4281,9 +4194,6 @@
are not familiar with the variant expressed should be able to ignore
the attribute.
-``classes`` is one of the `common attributes`_, shared by all
-Docutils elements.
-
.. _reader: ../peps/pep-0258.html#readers
.. _writer:
.. _writers: ../peps/pep-0258.html#writers
@@ -4403,9 +4313,9 @@
Attribute type: `%refnames.type`_. Default value: none.
-``dupnames`` is one of the `common attributes`_, shared by all
-Docutils elements. It replaces the `names`_ attribute when there
-has been a naming conflict.
+``dupnames`` replaces the `names`_ attribute when there has been
+a naming conflict.
+It is one of the `common attributes`_, shared by all Docutils elements.
``enumtype``
@@ -4432,10 +4342,8 @@
Attribute type: NMTOKENS_. Default value: none.
-The ``format`` attribute is a string containing one or more space
-separated output format names.
-
The ``format`` attribute is used in the `\<raw>`_ element.
+It contains one or more space separated output format names.
``frame``
@@ -4466,10 +4374,8 @@
The ``ids`` attribute is a space separated list containing one or more
unique `identifiers`_, typically assigned by the system.
+It is one of the `common attributes`_, shared by all Docutils elements.
-``ids`` is one of the `common attributes`_, shared by all Docutils
-elements.
-
.. TODO:
* Use 'id' for primary identifier key?
* Keep additional keys in `ids`
@@ -4560,15 +4466,15 @@
Default value: none.
The ``name`` attribute in the `\<meta>`_ element accepts `NMTOKEN`_ values.
-The output format may limit valid values to a set of keywords
-(EnumeratedType_).
+The output format may limit valid values to a set of keywords (EnumeratedType_).
The ``name`` attribute in the `\<reference>`_ element holds the
`reference name`_ of the referenced element. Whitespace is normalized
-but case is preserved. The attribute will no longer be used with
-<reference> elements in Docutils 1.0.
+but case is preserved.
+The attribute will no longer be used with <reference> elements in Docutils 1.0.
+
``names``
=========
@@ -4647,8 +4553,7 @@
The ``refid`` attribute contains a reference to another element via its
`identifier`_.
-
-``refid`` is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
+It is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
`\<problematic>`_, `\<reference>`_, `\<target>`_, and `\<title>`_ elements
(via the `%refid.att`_ and `%reference.atts`_ parameter entities).
@@ -4660,9 +4565,10 @@
The ``refname`` attribute contains a reference to one of the `names`_ of
another element.
+It is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
+`\<reference>`_, `\<substitution_reference>`_, and `\<target>`_ elements
+(via the `%refname.att`_ and `%reference.atts`_ parameter entities).
-``refname`` is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
-`\<reference>`_, `\<substitution_reference>`_, and `\<target>`_ elements. [#]_
On a `\<target>`_ element, ``refname`` indicates an `indirect target`_
which may resolve to either an internal or external reference.
@@ -4669,9 +4575,7 @@
Docutils transforms_ replace the ``refname`` attribute with a refid_
pointing to the same element.
-.. [#] Via the `%refname.att`_ and `%reference.atts`_ parameter entities.
-
``refuri``
==========
@@ -4719,20 +4623,19 @@
Attribute type: `CDATA`_. Default value: none.
The ``source`` attribute stores the path, URI, or a description
-of the source that was used to produce the document tree. [#]_
-
-``source`` is one of the `common attributes`_ but typically only
+of the source that was used to produce the document tree.
+It is one of the `common attributes`_ but typically only
used with the `\<document>`_ and `\<system_message>`_ elements.
+An element's ``source`` attribute may differ from the main document
+``source`` if the document is assembled from several sources
+(e.g. via the `"include" directive`_).
+
.. note:: All ``docutils.nodes.Node`` instances also support
*internal* ``source`` and ``line`` attributes
for use in diagnostic output.
-.. [#] An element's ``source`` attribute may differ from the main
- document ``source`` if the document is assembled from several
- sources (e.g. via the `"include" directive`_).
-
``start``
=========
@@ -4778,7 +4681,9 @@
Attribute type: `CDATA`_. Default value: none.
-The ``title`` attribute stores the *metadata title* of a `\<document>`_.
+The ``title`` attribute is used in the `\<document>`_ element to store the
+document's *metadata title*.
+
It is set by the `"title" directive`_ or the `DocTitle transform`_.
This title is typically not part of the rendered document.
It is, for example, used as `HTML <title> element`_ and shown in a
@@ -5273,9 +5178,8 @@
``%tbl.entry.mdl``
-------------------
-The ``%tbl.entry.mdl`` parameter entity is defined in
-the `Exchange Table Model`_ to allow customization of
-the `\<entry>`_ element's content model.
+The ``%tbl.entry.mdl`` parameter entity is defined in the `Exchange Table
+Model`_ to allow customization of the `\<entry>`_ element's content model.
The `Docutils Generic DTD`_ changes it to allow all `body elements`_
(including nested tables)::
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