A Guide to the Docutils Generic DTD
David Goodger
This document describes the XML data structure of Docutils documents: the relationships and semantics of elements and attributes.
The Docutils document structure is formally defined by the Docutils Generic XML document type definition (DTD) docutils.dtd, which is the definitive source for details of element structural relationships. It should be used in conjunction with the description of the semantics of the elements, attributes, and parameter entities in this document.
The reader is assumed to have some familiarity with XML or SGML, and an understanding of the data structure meaning of "tree". For a list of introductory articles, see, e.g., Introducing the Extensible Markup Language (XML).
Docutils implements the Document tree data structure in the Python module docutils.nodes. For details, see its internal API documentation ("docstrings") and the source nodes.py.
The reStructuredText markup language is used for illustrative examples throughout this document. For a gentle introduction, see A ReStructuredText Primer. For complete technical details, see the reStructuredText Markup Specification.
Element HierarchyThe Docutils document model uses strict element content models.
Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain elements immediately below it in the diagram. Element types in square brackets indicate recursive or one-to-many relationships: structural elements (sections) may contain sub-sections, some body elements may contain other body elements, etc. The element reference details valid parents and children for each element.
Every element has a unique structure and semantics, but elements may be classified into general categories according to their place and role in the document. Some elements belong to more than one category.
Alternatively, we may classify elements by their content model:
may contain child elements but no text data.
contain neither child elements nor text.
Every Docutils document contains exactly one root element. The root element has no parent. It may contain structural elements, all structural subelements, and body elements. It does not directly contain text.
nodes.Root
Structural elements group other elements to provide a document structure. They are child elements of the root element or other structural elements. Structural elements may contain specific structural elements, structural subelements, or body elements.
nodes.Structural
%structure.model directly or indirectly includes all structural elements.
Structural subelements are child elements of the root element or specific structural elements. Their content model varies (see the respective element reference section for details).
nodes.SubStructural
Decorative elements are used to generate page headers and footers. They are child elements of <decoration> and contain body elements.
Bibliographic ElementsBibliographic elements store document meta-data like title or author. They are child elements of <docinfo>. Their content model varies (see the respective element reference section).
<address>, <author>, <contact>, <copyright>, <date>, <organization>, <revision>, <status>, <version>
nodes.Bibliographic
Body elements are children of the root element, structural elements, or compound body elements. Simple body elements may contain text and inline elements or text data only (see the respective element reference section). Compound body elements may contain body subelements or further body elements.
<comment>, <doctest_block>, <literal_block>, <math_block>, <paragraph>, <raw>, <reference>, <rubric>, <substitution_definition>, <target>
<admonition>, <attention>, <block_quote>, <bullet_list>, <caution>, <citation>, <compound>, <container>, <danger>, <definition_list>, <enumerated_list>, <error>, <field_list>, <figure>, <footnote>, <hint>, <important>, <line_block>, <note>, <option_list>, <system_message>, <table>, <tip>, <warning>
nodes.Body
%body.elements directly includes all body elements, %structure.model indirectly includes all body elements.
Body subelements always occur within specific parent elements (e.g. <bullet_list> contains <list_item>), never at the body element level (beside paragraphs, etc.). Body subelements may be compound elements (containing body elements or further body subelements) or simple elements.
<attribution>, <caption>, <classifier>, <field_name>, <label>, <line>, <option_argument>, <option_string>, <term>, <title>
<definition>, <definition_list_item>, <description>, <entry>, <field>, <field_body>, <legend>, <list_item>, <option>, <option_group>, <option_list_item>, <row>, <tbody>, <tgroup>, <thead>
nodes.Part
Inline elements are contained within simple body elements or other inline elements. Inline elements are simple elements: All inline elements may contain text data, most inline elements may also contain further inline elements.
<abbreviation>, <acronym>, <citation_reference>, <emphasis>, <footnote_reference>, <generated>, <image>, <inline>, <literal>, <math>, <problematic>, <raw>, <reference>, <strong>, <subscript>, <substitution_reference>, <superscript>, <target>, <title_reference>
nodes.Inline
%inline.elements directly includes all inline elements, %text.model indirectly includes all inline elements.
Each element in the Docutils Generic DTD is described in its own section below. Each section contains the following items:
Summary description (up to two sentences).
Details (of element relationships and semantics):
One or more references to the element categories in the Element Hierarchy above. Some elements belong to more than one category.
Analogous elements in well-known document models such as HTML [html.spec] or DocBook [tdg5.1]. Describes similarities and differences.
Formatting or rendering recommendations for the element.
Elements which may contain the element.
Elements which may occur within the element. Optionally followed by the formal XML content model from the Docutils Generic DTD.
XML Attributes that are defined for this element.
Parameter entities which directly or indirectly include the element (if applicable and not already implied by the element category).
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 to display the results of parsing and processing.
Note
Some element reference sections below are marked "to be completed". Please help complete this document by contributing to its writing.
<abbreviation>The <abbreviation> element is an inline element representing an abbreviation, a shortened or contracted form of a word or phrase used to represent the whole.
<abbreviation> is analogous to the DocBook <abbrev> element. The HTML <abbr> element is used for both, abbreviations and acronyms.
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.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText "abbreviation" role creates an <abbreviation> element:
:abbreviation:`St` is a common abbreviation for "street".
Pseudo-XML fragment from simple parsing:
<paragraph>
<abbreviation>
St
is a common abbreviation for "street".<acronym>
The <acronym> element is an inline element used to represent an acronym (abbreviation formed by the initial letters of other words).
<acronym> is analogous to the DocBook <acronym> element. The HTML <abbr> element is used for both, abbreviations and acronyms.
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.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText "acronym" role creates an <acronym> element:
`WWW`:acronym: is the acronym for the world wide web.
Pseudo-XML fragment from simple parsing:
<paragraph>
<acronym>
WWW
is the acronym for the world wide web.<address>
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.
<address> is analogous to the DocBook <address> element.
As with the <literal_block> element, newlines are significant and must be preserved. However, a monospaced typeface should not be used.
text data plus inline elements (%text.model)
the common attributes and xml:space.
The <address> element is only valid in the bibliographic data (<docinfo>). You may use a <line_block> to format addresses in the document body.
ExamplesIn reStructuredText, "address" is one of the registered bibliographic fields:
Document Title
==============
:Address: 123 Example Ave.
Example, EX
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<address>
123 Example Ave.
Example, EX
See <docinfo> for a more complete example, including processing context.
<admonition>The <admonition> element is a generic, titled admonition, a distinctive and self-contained notice.
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.
Rendered distinctly (inset and/or in a box, etc.).
all elements employing %body.elements or %structure.model in their content models
<admonition> elements begin with a <title> and may contain one or more body elements.
only the common attributes.
See also the specific admonition elements <attention> <caution>, <danger>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.
ExamplesThe reStructuredText "admonition" directive creates a generic <admonition> element:
.. admonition:: By the way... You can make up your own admonition too.
Pseudo-XML fragment from simple parsing:
<admonition class="admonition-by-the-way">
<title>
By the way...
<paragraph>
You can make up your own admonition too.<attention>
The <attention> element is a specific admonition, a distinctive and self-contained notice.
<attention> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Attention!" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "attention" directive:
.. Attention:: All your base are belong to us.
Pseudo-XML fragment from simple parsing:
<attention>
<paragraph>
All your base are belong to us.<attribution>
The <attribution> element identifies the source of a <block_quote>.
Body Subelements (simple)
<attribution> is analogous to the DocBook <attribution> element.
Placed below the block quote, usually be preceded by a dash, right aligned, or otherwise set apart from the quotation.
text data plus inline elements (%text.model)
only the common attributes.
The Docutils HTML and LaTeX writers provide the "attribution" setting to configure the formatting of the <attribution>.
ExamplesSee <block_quote>.
<author>The <author> element holds the name of the author (or one of the authors) of the document.
<author> is analogous to the DocBook <personname> element.
see <docinfo>
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "author" is one of the registered bibliographic fields:
Document Title ============== :Author: J. Random Hacker
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<author>
J. Random Hacker
See <docinfo> for a more complete example, including processing context.
<authors>The <authors> element is a container for author information for documents with multiple authors.
<authors> is analogous to the DocBook <authorgroup> element.
See <docinfo>.
<author>, <organization>, <address>, <contact>:
((author, organization?, address?, contact?)+)
only the common attributes.
In reStructuredText, the "authors" field is one of the registered bibliographic fields:
Document Title ============== :Authors: J. Random Hacker; Jane Doe
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<authors>
<author>
J. Random Hacker
<author>
Jane Doe
There is currently no way to represent an individual author's <organization>, <address>, or <contact> in a reStructuredText "authors" field.
See <docinfo> for a more complete example, including processing context.
<block_quote>The <block_quote> element is used for quotations set off from the main text (standalone).
<block_quote> is analogous to the <blockquote> element in both HTML and DocBook.
<block_quote> elements serve to set their contents off from the main text, typically with indentation and/or other decoration.
all elements employing %body.elements or %structure.model in their content models
body elements followed by an optional <attribution>
only the common attributes.
In reStructuredText, an indented text block without preceding markup is a block quote:
As a great palaeontologist once said,
This theory, that is mine, is mine.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<paragraph>
As a great palaeontologist once said,
<block_quote>
<paragraph>
This theory, that is mine, is mine.
<attribution>
Anne Elk (Miss)
The "epigraph" and "pull-quote" directives produce <block_quote> elements, too.
<bullet_list>The <bullet_list> element contains <list_item> elements which are uniformly marked with bullets. Bullets are typically simple dingbats (symbols) such as circles and squares.
<bullet_list> is analogous to the HTML <ul> element [2] and to the DocBook <itemizedlist> element.
Each list item should begin a new vertical block, prefaced by a bullet/dingbat.
all elements employing %body.elements or %structure.model in their content models
one or more <list_item> elements
the common attributes and bullet.
A reStructuredText bullet list:
- Item 1, paragraph 1. Item 1, paragraph 2. - Item 2.
Pseudo-XML fragment from simple parsing:
<bullet_list bullet="-">
<list_item>
<paragraph>
Item 1, paragraph 1.
<paragraph>
Item 1, paragraph 2.
<list_item>
<paragraph>
Item 2.
See <list_item> for another example.
<caption>The <caption> element represents the title/caption of a <figure>. [3]
Body Subelements (simple)
The <caption> element is analogous to the DocBook <title> element (but specific to a <figure>). The HTML <figcaption> element combines <caption> and <legend>.
Placed above, below, or besides the image it describes. Often preceded by a figure number. May be repeated in a generated "list of figures".
text data plus inline elements (%text.model)
only the common attributes.
See <figure>.
<caution>The <caution> element is a specific admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements.
<caution> is analogous to the DocBook <caution> element.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Caution" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
A reStructuredText "caution" directive:
.. Caution:: Don't take any wooden nickels.
Pseudo-XML fragment from simple parsing:
<caution>
<paragraph>
Don't take any wooden nickels.<citation>
The <citation> element contains a description of an external bibliographic source. It is usually paired with one or more <citation_reference> elements that represent corresponding reference marks in the running text.
<citation> is analogous to the DocBook <bibliomixed> element. [4]
The "doc-biblioentry" DPub ARIA role (deprecated in version 1.1) can be used to mark a conforming HTML emulation. The corresponding type in the EPUB 3 Structural Semantics Vocabulary is "biblioentry".
Formatted as entry in a bibliography or similar to a <footnote>.
all elements employing %body.elements or %structure.model in their content models
<citation> elements begin with a <label> and contain body elements:
(label, (%body.elements;)+)
the common attributes and backrefs.
See <citation_reference>.
<citation_reference>The <citation_reference> element represents a cross reference to a <citation>.
The <citation_reference> element is analogous to the DocBook <citation> element. There is no equivalent in HTML. The <a> element can be used to provide a link to the corresponding citation.
Typically enclosed in square brackets.
all elements employing %text.model in their content models
only text data
refid, refname, and the common attributes.
reStructuredText syntax for citation references is similar to a footnote reference except for the use of a simple reference name instead of a numerical or symbolic label:
For details on brontosauruses, see [Elk:70]_.
.. [Elk:70] `My Theory on Brontosauruses`,
Anne Elk, London, 1972.
Pseudo-XML fragment simple parsing:
<paragraph>
For details on brontosauruses, see
<citation_reference ids="citation-reference-1" refname="elk:70">
Elk:70
.
<citation ids="elk-70" names="elk:70">
<label>
Elk:70
<paragraph>
<title_reference>
My Theory on Brontosauruses
,
Anne Elk, London, 1972.
The references.Footnotes Docutils transform resolves this to:
<paragraph>
For details on brontosauruses, see
<citation_reference ids="citation-reference-1" refid="elk-70">
Elk:70
.
<citation backrefs="citation-reference-1" ids="elk-70" names="elk:70">
<label>
Elk:70
<paragraph>
<title_reference>
My Theory on Brontosauruses
,
Anne Elk, London, 1972.<classifier>
The <classifier> element contains the classification or type of the <term> being defined in a <definition_list>. For example, it can be used to indicate the type of a variable.
Body Subelements (simple)
<classifier> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.
text data plus inline elements (%text.model)
only the common attributes.
A reStructuredText definition list with classifiers:
name : string
Customer name.
i : int
Temporary index variable.
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
name
<classifier>
string
<definition>
<paragraph>
Customer name.
<definition_list_item>
<term>
i
<classifier>
int
<definition>
<paragraph>
Temporary index variable.<colspec>
The <colspec> element contains specifications for a column in a <table>. It is defined in the Exchange Table Model.
Body Subelements (empty)
<colspec> is analogous to the DocBook <colspec> element. The HTML <col> element is related but has different semantics.
See colspec in the Exchange Table Model.
none (empty)
The Exchange Table Model defines the attributes align, char, charoff, colname, colnum, colsep, colwidth, and rowsep. [5] Via the %tbl.colspec.att parameter entity, <colspec> also accepts the common attributes and stub.
See <table>.
<compound>The <compound> element combines multiple body elements to a single logical paragraph.
The <compound> element has no direct analogues in common DTDs. In HTML, it can be emulated with <div> and CSS styling. [8]
Typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity (cf. the "compound" directive).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
The reStructuredText "compound" directive creates a <compound> element:
.. compound::
The 'rm' command is very dangerous. If you are logged
in as root and enter ::
cd /
rm -rf *
you will erase the entire contents of your file system.
Pseudo-XML fragment from simple parsing:
<compound>
<paragraph>
The 'rm' command is very dangerous. If you are logged
in as root and enter
<literal_block xml:space="preserve">
cd /
rm -rf *
<paragraph>
you will erase the entire contents of your file system.<contact>
The <contact> element holds contact information for the author (individual or group) of the document, or a third-party contact. It is typically used for an email or web address.
<contact> is analogous to the DocBook <email> element. The HTML <address> element serves a similar purpose.
See <docinfo>.
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "contact" is one of the registered bibliographic fields:
Document Title ============== :Contact: jrh@example.com
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
See <docinfo> for a more complete example, including processing context.
<container>The <container> element groups multiple body elements for user- or application-specific purposes.
The <container> element is analogous to the HTML <div> element or the SVG <g> element.
Can be used for styling or scripting purposes. An example is a frame or background colour based on the value of the classes attribute.
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
The reStructuredText "container" directive creates a <container> element:
.. container:: green boxed-equation .. math:: -1^2 = 1 This paragraph is in the box, too.
Pseudo-XML fragment from simple parsing:
<container classes="framed square">
<math_block xml:space="preserve">
-1^2 = 1
<paragraph>
This paragraph is in the box, too.
The HTML output can be placed in a common box with the custom CSS rule
div.framed {border: solid;
padding: 1em;}<copyright>
The <copyright> element contains the document's copyright statement.
<copyright> is analogous to the DocBook <copyright> element.
see <docinfo>
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "copyright" is one of the registered bibliographic fields:
Document Title ============== :Copyright: This document has been placed in the public domain.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<copyright>
This document has been placed in the public domain.
See <docinfo> for a more complete example, including processing context.
<danger>The <danger> element is a specific admonition, a distinctive and self-contained notice.
<danger> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "!DANGER!" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "danger" directive:
.. DANGER:: Mad scientist at work!
Pseudo-XML fragment from simple parsing:
<danger>
<paragraph>
Mad scientist at work!<date>
The <date> element contains the date of publication, release, or last modification of the document.
<date> is analogous to the DocBook <date> element.
Often used with the RCS/CVS keyword "Date". See <docinfo>.
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "date" is one of the registered bibliographic fields:
Document Title ============== :Date: 2002-08-20
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<date>
2002-08-20
See <docinfo> for a more complete example, including processing context.
<decoration>The <decoration> element is a container for <header> and <footer> elements and potential future extensions. These elements are used for notes, time/datestamp, processing information, etc.
There are no direct analogies to <decoration> in HTML or DocBook.
See the individual decorative elements.
The decorative elements <header> and/or <footer>. Although the content model doesn't specifically require contents, no empty <decoration> elements are ever created.
only the common attributes.
The <definition> element is a container for the body elements used to define a <term> in a <definition_list>.
Body Subelements (compound)
<definition> is analogous to the HTML <dd> element and to the DocBook <listitem> element (inside a <variablelistentry> element).
only the common attributes.
See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.
<definition_list>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.
<definition_list> is analogous to the HTML <dl> element and to the DocBook <variablelist> element.
all elements employing %body.elements or %structure.model in their content models
one or more <definition_list_item> elements
only the common attributes.
See also <field_list>.
ExamplesA reStructuredText definition list. The classifier is optional.
Term
Definition.
Term : classifier
The ' : ' indicates a classifier in
definition list item terms only.
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
Term
<definition>
<paragraph>
Definition.
<definition_list_item>
<term>
Term
<classifier>
classifier
<definition>
<paragraph>
The ' : ' indicates a classifier in
definition list item terms only.
See <definition_list_item> and <classifier> for further examples.
<definition_list_item>A wrapper for a set of terms (with optional classifiers) and the associated definition in a <definition_list>.
Body Subelements (compound)
<definition_list_item> is analogous to the DocBook <variablelistentry> element.
The optional <classifier>s can be rendered differently from the <term>. They should be separated visually, typically by spaces plus a colon or dash.
<definition_list_item> elements each contain one or more <term> elements, zero or more <classifier> elements, and a <definition>:
((term, classifier*)+, definition)
Changed in Docutils 0.22: allow multiple terms.
only the common attributes.
A complex reStructuredText definition list:
Tyrannosaurus Rex : carnivore
Big and scary; the "Tyrant King".
Brontosaurus : herbivore
..
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
Tyrannosaurus Rex
<classifier>
carnivore
<definition>
<paragraph>
Big and scary; the "Tyrant King".
<definition_list_item>
<term>
Brontosaurus
<classifier>
herbivore
<definition>
<comment xml:space="preserve">
<block_quote>
<paragraph>
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
<attribution>
Anne Elk (Miss)
See <definition_list> and <classifier> for further examples.
<description>The <description> element is the part of an <option_list> item that contains the description of a command-line option or group of options.
Body Subelements (compound)
<description> has no direct analogues in common DTDs.
see <option_list>
only the common attributes.
See <option_list>.
<docinfo>The <docinfo> element is a container for displayed document bibliographic 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.
There are no directly analogous HTML or DocBook elements. The DocBook <info> element is related but ususally suppressed in the output.
The <docinfo> element may be rendered as a two-column table or in other styles. It may even be invisible or omitted from the processed output. Meta-data may be extracted from <docinfo> children; for example, HTML <meta> tags may be constructed.
When Docutils transforms a reStructuredText <field_list> into a <docinfo> element (see the examples below), RCS/CVS keywords are normally stripped from simple (one paragraph) field bodies. For complete details, please see RCS Keywords in the reStructuredText Markup Specification.
only the common attributes.
See also the <meta> element (for hidden meta-data).
ExamplesBibliographic data is represented in reStructuredText by a field list as the first visible element of a document (after optional document title and subtitle). The field list is transformed into a <docinfo> element and its children by the DocInfo transform. [9]
Source:
Docinfo Example =============== :Author: J. Random Hacker :Contact: jrh@example.com :Date: 2002-08-18 :Status: Work In Progress :Version: 1 :Filename: $RCSfile$ :Copyright: This document has been placed in the public domain.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="docinfo-example" names="docinfo example">
<title>
Docinfo Example
<docinfo>
<author>
J. Random Hacker
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
<date>
2002-08-18
<status>
Work In Progress
<version>
1
<field classes="filename">
<field_name>
Filename
<field_body>
<paragraph>
doctree.rst
<copyright>
This document has been placed in the public domain.
Note that "Filename" is a non-standard <docinfo> field, so becomes a generic field element. Also note that the "RCSfile" keyword syntax has been stripped from the "Filename" data.
See <field_list> for a reStructuredText field list example in a non-bibliographic context. Also see the individual examples for the various bibliographic elements.
<doctest_block>The <doctest_block> element is a Python-specific variant of a <literal_block>.
<doctest_block> is analogous to the HTML <pre> element and the DocBook <programlisting> and <screen> elements.
As with <literal_block>, <doctest_block> elements are typically rendered in a monospaced typeface. It is crucial that all whitespace and line breaks are preserved in the rendered form.
all elements employing %body.elements or %structure.model in their content models
text data plus inline elements (%text.model)
the common attributes and xml:space.
A reStructuredText doctest block:
This is an ordinary paragraph.
>>> print('this is a Doctest block')
this is a Doctest block
Pseudo-XML fragment from simple parsing:
<paragraph>
This is an ordinary paragraph.
<doctest_block xml:space="preserve">
>>> print('this is a Doctest block')
this is a Doctest block
The <doctest_block> will be deprecated in Docutils 1.0, the reStructuredText parser will use a <literal_block> instead.
<document>The <document> element is the root (topmost) element of the Docutils document tree.
<document> is analogous to the HTML <html> element and to several DocBook elements such as <book>.
The <document> element has no parents.
structural elements, structural subelements, and body elements
( (title, subtitle?)?, meta*, decoration?, (docinfo, transition?)?, %structure.model; )
See the %structure.model parameter entity for details of the body of a <document>.
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 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>.
ExamplesA minimal reStructuredText document with title:
A Title ======= A paragraph.
Complete pseudo-XML result from simple parsing:
<document>
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
After applying transforms, the section title is promoted to become the document title:
<document ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.<emphasis>
The <emphasis> element is an inline element representing text that has stress emphasis.
<emphasis> is analogous to the HTML <em> element and the DocBook <emphasis> element.
Typically displayed in italic type.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText there are two emphasis markup alternatives:
There are :emphasis:`two` ways to *emphasize* text.
Pseudo-XML fragment from simple parsing:
<paragraph>
There are
<emphasis>
two
ways to
<emphasis>
emphasize
text.<entry>
The <entry> element represents one cell of a <table>. It is defined in the Exchange Table Model.
Body Subelements (compound)
<entry> is analogous to the DocBook <entry> element. HTML differentiates between header entries <th> and data entries <td>.
Render content in a table cell. The morecols and morerows attributes may be used to define an entry spanning several table cells. See entry in the Exchange Table Model for details.
body elements (via the %tbl.entry.mdl parameter entity)
The <entry> element accepts the colname, namest, nameend, morerows, colsep, rowsep, align, char, charoff, and valign attributes (ignored by Docutils) and (via the %tbl.entry.att parameter entity) the common attributes and morecols.
See <table>.
<enumerated_list>The <enumerated_list> element contains <list_item> elements which are uniformly marked with enumerator labels.
<enumerated_list> is analogous to the HTML <ol> element and to the DocBook <orderedlist> element.
Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1.").
all elements employing %body.elements or %structure.model in their content models
one or more <list_item> elements
enumtype, prefix, suffix, start, and the common attributes.
A reStructuredText enumerated list:
1. Item 1. (A) Item A. (B) Item B. (C) Item C. 2. Item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Item 1.
<enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
<list_item>
<paragraph>
Item A.
<list_item>
<paragraph>
Item B.
<list_item>
<paragraph>
Item C.
<list_item>
<paragraph>
Item 2.
See <list_item> for another example.
<error>The <error> element is a specific admonition, a distinctive and self-contained notice.
<error> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Error" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "error" directive:
.. Error:: Does not compute.
Pseudo-XML fragment from simple parsing:
<error>
<paragraph>
Does not compute.<field>
The <field> element contains one item of a <field_list>, a pair of <field_name> and <field_body> elements.
Body Subelements (compound), Bibliographic Elements
<field> has no direct analogues in common DTDs. HTML uses <div> elements inside <dl> lists for grouping <dt>/<dd> pairs.
See <field_list>.
one <field_name> and one <field_body> element
only the common attributes.
See the examples for the <field_list> and <docinfo> elements.
<field_body>The <field_body> element is analogous to a database field's data.
Body Subelements (compound)
<field_body> is analogous to the HTML <dd> element.
see <field_list>
only the common attributes.
See the examples for the <field_list> and <docinfo> elements.
<field_list>The <field_list> element contains two-column table-like structures resembling database records (label & data pairs).
<field_list> is analogue to the HTML <dl> element.
A <field_list> is typically rendered as a two-column list, where the first column contains "labels" (usually with a 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.
all elements employing %body.elements or %structure.model in their content models
one or more <field> elements
only the common attributes.
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.
ExamplesA reStructuredText field list:
:Author: Me :Version: 1 :Date: 2001-08-11 :Parameter i: integer
Pseudo-XML fragment from simple parsing:
<field_list>
<field>
<field_name>
Author
<field_body>
<paragraph>
Me
<field>
<field_name>
Version
<field_body>
<paragraph>
1
<field>
<field_name>
Date
<field_body>
<paragraph>
2001-08-11
<field>
<field_name>
Parameter i
<field_body>
<paragraph>
integer<field_name>
The <field_name> element is analogous to a database field's name.
Body Subelements (simple)
<field_name> is analogous to the HTML <dt> element.
See <field_list>.
text data plus inline elements (%text.model)
only the common attributes.
See the examples for the <field_list> and <docinfo> elements.
<figure>The <figure> element groups an <image> with a <caption> and/or <legend>.
The <figure> element is analogous to the HTML <figure> element and the DocBook <figure> and <informalfigure> elements but limited to images (while HTML and DocBook allow also other main content).
On paged media, figures may float to a different position if this helps the page layout.
all elements employing %body.elements or %structure.model in their content models
<image> or <reference> (with nested <image>) followed by <caption> or <legend> or both.
align (via %align-h.att) , width, and the common attributes.
The reStructuredText "figure" directive creates a <figure> element:
.. figure:: larch-mini.jpg :alt: a larch :target: larch.jpg :class: thumbnail :figclass: numbered The larch. Larix decidua in Aletschwald.
Pseudo-XML fragment from simple parsing:
<figure classes="numbered">
<reference refuri="larch.jpg">
<image alt="a larch" classes="thumbnail" uri="larch-mini.jpg">
<caption>
The larch.
<legend>
<paragraph>
Larix decidua in Aletschwald.<generated>
The <generated> element represents text that is not present in the document source but inserted by the processing system.
No special handling required.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText "sectnum" directive automatically numbers sections and subsections in a document:
.. section-numbering:: Anagram quiz ============
Docutils wraps the generated section numbers in <generated> elements:
<section ids="anagram-quiz" names="anagram\ quiz">
<title auto="1">
<generated classes="sectnum">
1
Anagram quiz<hint>
The <hint> element is a specific admonition, a distinctive and self-contained notice.
<hint> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Hint" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "hint" directive:
.. Hint:: It's bigger than a bread box.
Pseudo-XML fragment from simple parsing:
<hint>
<paragraph>
It's bigger than a bread box.<image>
The <image> element refers to an image resource that should be included in the document.
<image> is analogous to the HTML <img>, DocBook <imagedata>, and SVG <image> elements.
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.
all elements employing %body.elements, %text.model, or %structure.model in their content models
none (empty)
uri, alt, align, height, width, scale, loading, and the common attributes.
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.
ExamplesA reStructuredText "image" directive:
.. image:: picture.jpeg :width: 20 mm :alt: alternate text
Pseudo-XML fragment from simple parsing:
<image alt="alternate text" uri="picture.jpeg" width="20mm"><important>
The <important> element is a specific admonition, a distinctive and self-contained notice.
<important> is analogous to the DocBook <important> element.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Important" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "important" directive:
.. Important:: * Wash behind your ears. * Clean up your room. * Back up your data.
Pseudo-XML fragment from simple parsing:
<important>
<bullet_list>
<list_item>
<paragraph>
Wash behind your ears.
<list_item>
<paragraph>
Clean up your room.
<list_item>
<paragraph>
Back up your data.<inline>
The <inline> element is a generic inline container.
<inline> is analogous to the HTML <span> element and the DocBook <phrase> element.
Writers typically pass the classes attribute to the output document and leave styling to the backend or a custom stylesheet. They may also process the classes attribute and convert the <inline> element to a specific element or render the content distinctly for specific class values. Moreover, writers may ignore the element and just render the content.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
Custom interpreted text roles create <inline> elements (unless they are based on a standard role).
This reStructuredText source fragment creates and uses a custom role:
.. role:: custom An example of using :custom:`interpreted text`
Pseudo-XML fragment from simple parsing:
<paragraph>
An example of using
<inline classes="custom">
interpreted text<label>
The <label> element represents the reference label of a <footnote> or <citation>.
Body Subelements (simple)
The <label> element has no direct analogues in HTML. In DocBook, the label of a footnote is stored as attribute of the <footnote> element and the label of a bibliographic entry is represented by an <abbrev> element.
Rendered prominently, as first token of the footnote or citation. Often enclosed in square brackets.
only text data
only the common attributes.
See <footnote>, <footnote_reference>, and <citation_reference>.
<legend>The <legend> element contains an extended description of a <figure>. It may complement or replace the figure <caption>.
Body Subelements (compound)
The <legend> element is analogous to the DocBook <caption> element (but specific to a <figure>). The HTML <figcaption> element combines <caption> and <legend>.
Formatted as a displayed block.
only the common attributes.
See <figure>.
<line>The <line> element contains a single line of text, part of a <line_block>.
Body Subelements (simple)
<line> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.
See <line_block>.
text data plus inline elements
only the common attributes.
See <line_block>.
<line_block>The <line_block> element is a âplain listâ of lines and nested line blocks. It is commonly used for verse and addresses.
<line_block> has no direct analogues in common DTDs. Is is related to the DocBook <literallayout> element, however <literallayout> is a verbatim environment which directly contains text.
Each <line> should begin a new vertical block, without markers or additional spacing. Nested <line_blocks> should be indented.
all elements employing %body.elements or %structure.model in their content models
<line>, <line_block>
only the common attributes.
See <literal_block> for an alternative useful for program listings and interactive computer sessions.
ExamplesA reStructuredText line block:
Take it away, Eric the Orchestra Leader! | A one, two, a one two three four | | Half a bee, philosophically, | must, *ipso facto*, half not be. | But half the bee has got to be, | *vis a vis* its entity. D'you see? | | But can a bee be said to be | or not to be an entire bee, | when half the bee is not a bee, | due to some ancient injury? | | Singing...
Pseudo-XML fragment from simple parsing:
<paragraph>
Take it away, Eric the Orchestra Leader!
<line_block>
<line>
A one, two, a one two three four
<line>
<line>
Half a bee, philosophically,
<line_block>
<line>
must,
<emphasis>
ipso facto
, half not be.
<line>
But half the bee has got to be,
<line_block>
<line>
<emphasis>
vis a vis
its entity. D'you see?
<line>
<line>
But can a bee be said to be
<line_block>
<line>
or not to be an entire bee,
<line_block>
<line>
when half the bee is not a bee,
<line_block>
<line>
due to some ancient injury?
<line>
<line>
Singing...<list_item>
The <list_item> element is a container for the elements of a list item.
Body Subelements (compound)
<list_item> is analogous to the HTML <li> element and to the DocBook <listitem> element.
See <bullet_list> or <enumerated_list>.
only the common attributes.
A reStructuredText enumerated list with a nested bullet list:
1. Outer list, item 1. * Inner list, item 1. * Inner list, item 2. 2. Outer list, item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Outer list, item 1.
<bullet_list bullet="*">
<list_item>
<paragraph>
Inner list, item 1.
<list_item>
<paragraph>
Inner list, item 2.
<list_item>
<paragraph>
Outer list, item 2.
See <bullet_list> or <enumerated_list> for further examples.
<literal>The <literal> element represents inline text that is some literal value.
<literal> is analogous to the DocBook <literal> element. HTML uses the specific elements <code>, <kbd>, and <samp> for code, input, and output.
Typically rendered in a monospace font. Preservation of line breaks and sequences of whitespace characters is not guaranteed.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, inline literals, the "literal" role, and the "code" role create <literal> elements. So do custom roles derived from "literal" or "code":
.. role:: python(code)
:language: python
The statement :python:`print("hello world")`
writes ``"hello world"`` to standard output.
Pseudo-XML fragment from simple parsing:
<paragraph>
The statement
<literal classes="code python">
<inline classes="name builtin">
print
<inline classes="punctuation">
(
<inline classes="literal string double">
"hello world"
<inline classes="punctuation">
)
writes
<literal>
"hello world"
to standard output.<literal_block>
The <literal_block> element contains a block of text where line breaks and whitespace are significant and must be preserved.
Details<literal_block> is analogous to the HTML <pre> element and to the DocBook <programlisting> and <screen> elements.
<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.
all elements employing %body.elements or %structure.model in their content models
text data plus inline elements (%text.model)
the common attributes and xml:space.
<literal_block> elements are commonly used for program listings and interactive computer sessions. See <line_block> for an alternative useful for verse and addresses.
ExamplesA reStructuredText "parsed-literal" directive:
.. parsed-literal::
if parsed_literal:
text = 'is parsed for reStructuredText_ markup'
spaces_and_linebreaks = 'are preserved'
markup_processing = **True**
Pseudo-XML fragment from simple parsing:
<literal_block xml:space="preserve">
if parsed_literal:
text = 'is parsed for
<reference name="reStructuredText" refid="restructuredtext">
reStructuredText
markup'
spaces_and_linebreaks = 'are preserved'
markup_processing =
<strong>
True
<literal-block> elements are also generated by a literal block and the "code" directive, e.g.
.. code:: python
print(8/2)
Pseudo-XML fragment from simple parsing (with the "syntax_highlight" setting at its default value "long"):
<literal_block classes="code python" xml:space="preserve">
<inline classes="name builtin">
print
<inline classes="punctuation">
(
<inline classes="literal number integer">
8
<inline classes="operator">
/
<inline classes="literal number integer">
2
<inline classes="punctuation">
)<math>
The <math> element contains text in LaTeX math format [11] that is typeset as mathematical notation (inline formula).
<math> is related to the <math> element in MathML and HTML. However, it contains text data only.
Rendered as mathematical notation. If the output format does not support math typesetting, the content may be inserted verbatim.
all elements employing %text.model in their content models
only text data
only the common attributes.
reStructuredText source:
Euler's identity is :math:`e^{\mathrm{i}\pi} + 1 = 0`.
Pseudo-XML fragment from simple parsing:
<paragraph>
Eulerâs identity is
<math>
e^{\mathrm{i}\pi} + 1 = 0
.<math_block>
The <math_block> element contains a block of text in LaTeX math format [11] that is typeset as mathematical notation (display formula).
<math_block> is analogous to a HTML/MathML <math> element displayed as block-level element or a LaTeX equation* environment.
Rendered in a block as mathematical notation, typically centered or with indentation If the output format does not support math typesetting, the content may be inserted verbatim.
all elements employing %body.elements or %structure.model in their content models
only text data
the common attributes and xml:space.
The reStructuredText "math" directive generates a <math_block> element:
Euler's identity is the equation
.. math:: e^{\mathrm{i}\pi} + 1 = 0
Pseudo-XML fragment from simple parsing:
<paragraph>
Eulerâs identity is the equation
<math_block xml:space="preserve">
e^{\mathrm{i}\pi} + 1 = 0<meta>
The <meta> element is a container for "hidden" document bibliographic data, or meta-data (data about the document).
<meta> is analogous to the HTML <meta> element or the file properties in ODT or PDF documents.
The <meta> element is stored as metadata if the export format supports this. It is typically invisible and may be omitted from the processed output.
Meta-data may also be extracted from <docinfo> children or the <document> attributes (title).
none (empty)
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.
ExampleA reStructuredText "meta" directive:
.. meta:: :description lang=en: An amusing story :description lang=fr: Un histoire amusant
Pseudo-XML fragment from simple parsing:
<meta content="An amusing story" lang="en" name="description"> <meta content="Un histoire amusant" lang="fr" name="description"><note>
The <note> element is a specific admonition, a distinctive and self-contained notice.
<note> is analogous to the DocBook <note> element.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Note" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "note" directive:
.. Note:: Admonitions can be handy to break up a long boring technical document.
Pseudo-XML fragment from simple parsing:
<note>
<paragraph>
Admonitions can be handy to break up a
long boring technical document.<option>
The <option> element groups an option string together with zero or more option argument placeholders.
Body Subelements (compound)
<option> has no direct analogues in common DTDs.
See <option_list>.
<option> elements start with an <option_string> and may contain <option_argument> elements:
(option_string, option_argument*)
only the common attributes.
Note that reStructuredText currently supports only one argument per option.
ExamplesSee the examples for the <option_list> element.
<option_argument>The <option_argument> element contains placeholder text for option arguments.
Body Subelements (simple)
<option_argument> has no direct analogues in common DTDs.
The value of the "delimiter" attribute is prefixed to the <option_argument>, separating it from its <option_string> or a preceding <option_argument>. The <option_argument> text is typically rendered in a monospaced typeface, possibly italicized or otherwise altered to indicate its placeholder nature.
only text data
the common attributes and delimiter.
See the examples for the <option_list> element.
<option_group>The <option_group> element groups together one or more <option> elements, all synonyms.
Body Subelements (compound)
<option_group> has no direct analogues in common DTDs.
Typically <option> elements within an <option_group> are joined together in a comma-separated list.
one or more <option> elements
only the common attributes.
See the examples for the <option_list> element.
<option_list>Each <option_list> element contains a two-column list of command-line options and descriptions, documenting a program's options.
<option_list> has no direct analogues in common DTDs. It can be emulated with primitives such as tables.
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.
all elements employing %body.elements or %structure.model in their content models
one or more <option_list_item> elements
only the common attributes.
A reStructuredText option list:
-a command-line option "a"
-1 file, --one=file, --two file
Multiple options with arguments.
Pseudo-XML fragment from simple parsing:
<option_list>
<option_list_item>
<option_group>
<option>
<option_string>
-a
<description>
<paragraph>
command-line option "a"
<option_list_item>
<option_group>
<option>
<option_string>
-1
<option_argument delimiter=" ">
file
<option>
<option_string>
--one
<option_argument delimiter="=">
file
<option>
<option_string>
--two
<option_argument delimiter=" ">
file
<description>
<paragraph>
Multiple options with arguments.<option_list_item>
The <option_list_item> element is a container for a pair of <option_group> and <description> elements.
Body Subelements (compound)
<option_list_item> has no direct analogues in common DTDs.
see <option_list>
one <option_group> and one <description>
only the common attributes.
See the examples for the <option_list> element.
<option_string>The <option_string> element contains the text of a command-line option.
Body Subelements (simple)
<option_string> has no direct analogues in common DTDs.
The <option_string> text is typically rendered in a monospaced typeface.
only text data
only the common attributes.
See the examples for the <option_list> element.
<organization>The <organization> element contains the name of document author's organization, or the organization responsible for the document.
<organization> is analogous to the <orgname>, <corpname>, or <publishername> DocBook elements.
See <docinfo>.
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "organization" is one of the registered bibliographic fields:
Document Title ============== :Organization: Humankind
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<organization>
Humankind
See <docinfo> for a more complete example, including processing context.
<paragraph>The <paragraph> element contains the text and inline elements of a single paragraph, a fundamental building block of documents.
<paragraph> is analogous to the HTML <p> element and to the DocBook <para> element.
all elements employing %body.elements or %structure.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, blocks of left-aligned text are paragraphs unless marked up as another body element:
A paragraph must be left-aligned.
Pseudo-XML fragment from simple parsing:
<paragraph>
A paragraph must be
left-aligned.<pending>
The <pending> element is a placeholder for a pending transform.
Body Elements (empty)
<pending> has no direct analogues in common DTDs.
Usually replaced or removed by the associated transform. Writers may ignore remaining <pending> elements.
all elements employing %body.elements or %structure.model in their content models
none (empty)
only the common attributes.
The reStructuredText "contents" directive indicates that an auto-generated table of contents (ToC) should be inserted at this point:
.. contents:: :depth: 1 first section ============= second section ==============
As the ToC can't be generated until the entire document has been parsed, simple parsing adds a <topic> with a <pending> element as placeholder:
<topic classes="contents" ids="contents" names="contents">
<title>
Contents
<pending>
.. internal attributes:
.transform: docutils.transforms.parts.Contents
.details:
depth: 1
<section ids="first-section" names="first\ section">
<title>
first section
<section ids="second-section" names="second\ section">
<title>
second section
After parsing is completed, the associated parts.Contents transform replaces the <pending> node with the table of contents:
<topic classes="contents" ids="contents" names="contents">
<title>
Contents
<bullet_list>
<list_item>
<paragraph>
<reference ids="toc-entry-1" refid="first-section">
first section
<list_item>
<paragraph>
<reference ids="toc-entry-2" refid="second-section">
second section
<section ids="first-section" names="first\ section">
<title refid="toc-entry-1">
first section
<section ids="second-section" names="second\ section">
<title refid="toc-entry-2">
second section<problematic>
The <problematic> element highlights a source part that caused a parsing problem.
<problematic> has no direct analogues in common DTDs.
Typically displayed in red colour. If the refid attribute is present, the element should point to the referenced element.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
the common attributes and refid.
The reStructuredText parser marks ambiguous or invalid inline syntax as <problematic> and adds a reference to the associated <system_message>. The behaviour can be configured with the "report_level" setting.
The following paragraph contains unbalanced inline markup:
a single *star
Pseudo-XML fragment from simple parsing:
<paragraph>
a single
<problematic ids="problematic-1" refid="system-message-1">
*
star
<system_message backrefs="problematic-1" ids="system-message-1"
level="2" line="1" source="example.rst" type="WARNING">
<paragraph>
Inline emphasis start-string without end-string.<raw>
The <raw> element contains non-reStructuredText data that is to be passed untouched to the Writer.
The <raw> element has no direct analogues in common DTDs.
Passed untouched to the Writer. The interpretation is up to the Writer. A Writer may ignore <raw> elements not matching its format.
all elements employing %body.elements, %structure.model, or %text.model in their content models
only text data
format, xml:space and the common attributes.
The reStructuredText "raw" directive [12] creates a <raw> element:
.. raw:: html <hr width=50 size=10>
Pseudo-XML fragment from simple parsing:
<raw format="html" xml:space="preserve">
<hr width=50 size=10><reference>
The <reference> element represents a cross reference to another element of the document or to an external ressource.
The <reference> element is analogous to the DocBook <link> element and the HTML <a> (anchor) element.
If possible, make the content of the link element an active link. In print media, the target might be ignored, printed after the text of the <reference>, printed as a footnote [13], or rendered in some other way.
all elements employing %body.elements, %text.model, or %structure.model in their content models
text data plus inline elements (%text.model)
anonymous, name (deprecated), refid, refname, refuri, and the common attributes.
In reStructuredText hyperlink references are indicated by a trailing underscore:
References may use simple_ reference names, `phrase references`_, or `no reference name`__. Matching targets must exist in the document, e.g., a _`simple` inline target or the explicit targets below. .. _phrase references: doctree.rst __ http://example.org
Pseudo-XML fragment from simple parsing:
<paragraph>
References may use
<reference refname="simple">
simple
reference names,
<reference refname="phrase references">
phrase references
, or
<reference anonymous="1">
no reference name
.
<paragraph>
Matching targets must exist in the document, e.g., a
<target ids="simple" names="simple">
simple
inline target or the explicit targets below.
<target ids="phrase-refs" names="phrase\ refs" refuri="doctree.rst">
<target anonymous="1" ids="target-1" refuri="http://example.org">
Docutils uses transforms to match references and targets and replace the refname with a refid or refuri:
<paragraph>
References may use
<reference refid="simple">
simple
reference names,
<reference refuri="doctree.rst">
phrase references
, or
<reference anonymous="1" refuri="http://example.org">
no reference name
.
<paragraph>
Matching targets must exist in the document, e.g., a
<target ids="simple" names="simple">
simple
inline target or the explicit targets below.
<target ids="phrase-refs" names="phrase\ refs" refuri="doctree.rst">
<target anonymous="1" ids="target-1" refuri="http://example.org">
Standalone hyperlinks and clickable images generate <reference> elements, too:
Visit https://hamburg.de. .. image:: michel.jpg :target: https://hamburg.de
Pseudo-XML fragment from simple parsing:
<paragraph>
Visit
<reference refuri="https://hamburg.de">
https://hamburg.de
.
<reference refuri="https://hamburg.de">
<image uri="michel.jpg"><revision>
The <revision> element contains the revision number of the document. It can be used alone or in conjunction with <version>.
<revision> is similar to (but simpler than) the DocBook <revision> element. It closely matches the DocBook <revnumber> element, but in a simpler context.
Often used with the RCS/CVS keyword "Revision". See <docinfo>.
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "revision" is one of the registered bibliographic fields:
Document Title ============== :Version: 1 :Revision: b
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1
<revision>
b
See <docinfo> for a more complete example, including processing context.
<row>The <row> element represents one row of a <table>. It is defined in the Exchange Table Model.
Body Subelements (compound)
<row> is analogous to the HTML <tr> element and the DocBook <row> element.
Render content as a table row. See row in the Exchange Table Model for details.
one or more <entry> elements
The <row> element may contain the rowsep and valign attributes (ignored by Docutils) and (via the %tbl.row.att parameter entity) the common attributes.
See <table>.
<rubric>rubric n. 1. a title, heading, or the like, in a manuscript, book, statute, etc., written or printed in red or otherwise distinguished from the rest of the text. ...
âRandom House Webster's College Dictionary, 1991
A rubric is like an informal heading that doesn't correspond to the document's structure.
<section>The <section> element is the main unit of hierarchy for Docutils documents.
<section> is analogous to the <section> elements in HTML and DocBook.
<section> elements begin with a <title>, followed by an optional <subtitle>. They may contain structural elements, body elements, and <transition> elements:
(title, subtitle?, %structure.model;)
only the common attributes
%section.elements directly includes <section>, %structure.model indirectly includes <section>.
The Docutils document model uses a simple, recursive model for section 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.
Paragraphs and other body elements may occur before a <section>, but not after it.
ExamplesreStructuredText does not impose a fixed number and order of section title adornment styles. The order enforced will be the order as encountered.
Title 1 ======= Paragraph 1. Title 2 ------- Paragraph 2. Title 3 ======= Paragraph 3. Title 4 ------- Paragraph 4.
Complete pseudo-XML result after parsing:
<document>
<section ids="title-1" names="title 1">
<title>
Title 1
<paragraph>
Paragraph 1.
<section ids="title-2" names="title 2">
<title>
Title 2
<paragraph>
Paragraph 2.
<section ids="title-3" names="title 3">
<title>
Title 3
<paragraph>
Paragraph 3.
<section ids="title-4" names="title 4">
<title>
Title 4
<paragraph>
Paragraph 4.<status>
The <status> element contains a status statement for the document, such as "Draft", "Final", "Work In Progress", etc.
<status> is analogous to the DocBook <status> element.
See <docinfo>.
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "status" is one of the registered bibliographic fields:
Document Title ============== :Status: Work In Progress
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<status>
Work In Progress
See <docinfo> for a more complete example, including processing context.
<strong>The <strong> element is an inline element representing text that has strong importance, seriousness, or urgency.
<strong> is analogous to the HTML <strong> element.
Typically displayed in boldface.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText there are two alternatives to mark text with strong emphasis:
There are :strong:`two` ways to **strongly emphasize** text.
Pseudo-XML fragment from simple parsing:
<paragraph>
There are
<strong>
two
ways to
<strong>
strongly emphasize
text.<subscript>
The <subscript> element is an inline element representing text which should be displayed as subscript.
<subscript> is analogous to the HTML <sub> element and the DocBook <subscript> element.
Typically rendered with a lowered baseline using smaller text.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText "subscript" role creates a <subscript> element:
The chemical formula for water is H\ :sub:`2`\ O.
Pseudo-XML fragment from simple parsing:
<paragraph>
The chemical formula for water is H
<subscript>
2
O.<substitution_definition>
The <substitution_definition> element stores a reStructuredText substitution definition.
<substitution_reference> <subtitle>The <subtitle> element stores the subtitle of a <document>, <section>, or <sidebar>.
<subtitle> is analogous to the DocBook <subtitle> element. In HTML, subtitles are represented by a <p> element inside a <hgroup> element.
A document's subtitle is usually rendered smaller than its <title>.
<document>, <section>, and <sidebar>
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, a lone second-level section title immediately after the âdocument titleâ can become the document subtitle:
======= Title ======= ---------- Subtitle ---------- A paragraph.
Complete pseudo-XML result after parsing and applying the DocTitle transform:
<document ids="title" names="title">
<title>
Title
<subtitle ids="subtitle" names="subtitle">
Subtitle
<paragraph>
A paragraph.
Note how two section levels have collapsed, promoting their titles to become the document's title and subtitle. Since there is only one structural element (document), the subsection's ids and names attributes are stored in the <subtitle> element.
<superscript>The <superscript> element is an inline element representing text which should be displayed as superscript.
<superscript> is analogous to the HTML <sup> element and the DocBook <superscript> element.
Typically rendered with a raised baseline using smaller text.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText "superscript" role creates a <superscript> element:
Key events of the 20\ :sup:`th` century.
Pseudo-XML fragment from simple parsing:
<paragraph>
Key events of the 20
<superscript>
th
century.<system_message>
The <system_message> element is used for feedback from the processing system.
<system_message> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.
Rendered similar to an <admonition>, with the generated title "System Message", its type/level and, if available, source and line.
all elements employing %body.elements or %structure.model in their content models
one or more body elements
backrefs, level, line, type, and the common attributes.
In Docutils, the generation of system messages can be configured with the "report_level" setting.
ExamplesAn undefined or misspelled directive generates an error message:
.. contants::
Pseudo-XML fragment from simple parsing:
<system_message level="3" line="8" source="example.rst" type="ERROR">
<paragraph>
Unknown directive type "contants".
<literal_block xml:space="preserve">
.. contants::
See also <problematic>.
<table>The <table> element represents a data arrangement with rows and columns. It is defined in the Exchange Table Model.
<table> is analogous to the <table> element in HTML and DocBook.
Content is arranged in rows and columns forming a grid. See table in the Exchange Table Model for details.
<document>, <section> and all body elements
<table> elements begin with an optional <title> (caption) and may contain one or more <tgroup> elements:
(title?, tgroup+)
The <table> element may contain the frame, colsep, rowsep, and pgwide attributes (ignored by Docutils) and (via the %bodyatt parameter entity) the common attributes, align, and width.
In reStructuredText, tables can be specified via the "table", "csv-table", or "list-table" directives or directly as grid table or simple table, e.g.
======== ==== bread £2 butter £30 ======== ====
Pseudo-XML fragment from simple parsing:
<table>
<tgroup cols="2">
<colspec colwidth="8">
<colspec colwidth="4">
<tbody>
<row>
<entry>
<paragraph>
bread
<entry>
<paragraph>
£2
<row>
<entry>
<paragraph>
butter
<entry>
<paragraph>
£30<target>
<tbody>
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.
Body Subelements (compound)
<tbody> is analogous to the <tbody> element in HTML and DocBook.
Render content as table body.
one or more <row> elements
valign (ignored by Docutils) and the common attributes (via the %tbl.tbody.att parameter entity).
See <table>.
<term>The <term> element contains a word or phrase being defined in a <definition_list>.
Body Subelements (simple)
<term> is analogous to the HTML <dt> element and to the DocBook <term> element.
text data plus inline elements (%text.model)
only the common attributes.
See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.
<tgroup>The <tgroup> element identifies a logically complete portion of a <table>. It is defined in the Exchange Table Model.
Body Subelements (compound)
<tgroup> is analogous to the DocBook <tgroup> element. There is no corresponding HTML element (the <colgroup> element has a different purpose and semantics).
See tgroup in the Exchange Table Model.
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.
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> 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 and Docutils table handling routines.
ExamplesSee <table>.
<thead>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.
Body Subelements (compound)
<thead> is analogous to the <thead> element in HTML and DocBook.
Header rows are always rendered at the beginning of the table and often presented in an alternate typographic style, such as boldface. In paged media, if a table spans across multiple pages, header rows are printed at the top of each new page.
one or more <row> elements
the valign attribute (ignored by Docutils) and (via the %tbl.thead.att parameter entity) the common attributes.
See <table>.
<tip>The <tip> element is a specific admonition, a distinctive and self-contained notice.
<tip> is analogous to the DocBook <tip> element.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Tip" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "tip" directive:
.. Tip:: 15% if the service is good.
Pseudo-XML fragment from simple parsing:
<tip>
<paragraph>
15% if the service is good.<title>
The <title> element stores the heading of a <document>, structural elements, or a generic <admonition>. It is also used for the caption of a <table>.
Structural Subelements, Body Subelements (simple)
<title> is analogous to the DocBook <title> element. In difference to the HTML section heading elements (<h1>, â¦, <h6>), the heading level is solely determined by the nesting level of the parent <section>. As child of a <table>, <title> corresponds to the HTML <caption> element.
Note
The HTML <title> element corresponds to the document's title attribute (metadata title).
<admonition>, <document>, <section>, <sidebar>, <table>, and <topic>
text data plus inline elements (%text.model)
refid (used as a backlink to a table of contents entry), auto (for auto-numbered section titles), and the common attributes.
The displayed <title> of a <document> may differ from its metadata title that is stored in the title attribute.
ExamplesSection titles are marked up with "underlines" below the title text (or underlines and matching overlines):
A Title ======= A paragraph. Next section's title ====================
Pseudo-XML fragment from simple parsing:
<section ids="a-title" names="a\ title">
<title>
A Title
<paragraph>
A paragraph.
<section ids="next-section-s-title" names="next\ section's\ title">
<title>
Next sectionâs title
See also the examples for <admonition>, <document>, <section>, <sidebar>, <subtitle>, <table>, and <topic>.
<title_reference>The <title_reference> element is an inline element representing the titles of a cited creative work.
<title_reference> is analogous to the HTML <cite> element and the DocBook <citetitle> element.
Typically displayed in italic type.
all elements employing %text.model in their content models
text data plus inline elements (%text.model)
only the common attributes.
The reStructuredText "title-reference" role creates a <title_reference> element:
The term "spam" is derived from the 1970 :title:`Spam` sketch.
Pseudo-XML fragment from simple parsing:
<paragraph>
The term âspamâ is derived from the 1970
<title_reference>
Spam
sketch.<topic>
The <topic> element represents a non-recursive section-like construct for content that is separate from the flow of the document.
<topic> is analogous to the DocBook <simplesect> element and the HTML <aside> element.
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.
<document>, <section>, and <sidebar>
<topic> elements may begin with a <title> and contain body elements:
(title?, (%body.elements;)+)
only the common attributes
%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 it has no subsections, it does not get listed in the ToC, and it doesn't have to conform to section placement rules. You may place a <topic> in the middle of a <section> and continue the same section after it --- something that cannot be done with a nested <section>.
Topics cannot nest inside topics, or body elements (tables, lists, block quotes, etc).
Tip
Use a <rubric> element to get an informal heading inside a table, list, or inside another <topic>.
Docutils uses the <topic> element also for a generated table of contents, and the "abstract" and "dedication" bibliographic fields.
ExamplesA reStructuredText "topic" directive:
.. topic:: Title Body.
Pseudo-XML fragment from simple parsing:
<topic>
<title>
Title
<paragraph>
Body.<transition>
The <transition> element separates body elements and sections, dividing a <section> into untitled divisions.
<transition> is analogous to the HTML <hr> element.
The <transition> element is typically rendered as vertical whitespace (more than that separating paragraphs), with or without a horizontal line or row of asterisks. In novels, transitions are often represented as a row of three well-spaced asterisks with vertical space above and below.
none (empty)
only the common attributes
%structure.model directly includes <transition>.
A transition may not begin or end a section [14] or document, nor may two transitions be immediately adjacent.
See also Doctree Representation of Transitions in A Record of reStructuredText Syntax Alternatives.
ExamplesA transition in the reStructuredText source:
Paragraph 1. -------- Paragraph 2.
Complete pseudo-XML result after parsing:
<document>
<paragraph>
Paragraph 1.
<transition>
<paragraph>
Paragraph 2.<version>
The <version> element contains the version number of the document. It can be used alone or in conjunction with <revision>.
<version> may be considered analogous to the <revision>, <revnumber>, or <biblioid> DocBook elements.
Sometimes used with the RCS/CVS keyword "Revision". See <docinfo> and <revision>.
text data plus inline elements (%text.model)
only the common attributes.
In reStructuredText, "version" is one of the registered bibliographic fields:
Document Title ============== :Version: 1.1
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1.1
See <docinfo> for a more complete example, including processing context.
<warning>The <warning> element is a specific admonition, a distinctive and self-contained notice.
<warning> is analogous to the DocBook <warning> element.
Rendered distinctly (inset and/or in a box, etc.), with the generated title "Warning" (or similar).
all elements employing %body.elements or %structure.model in their content models
one or more body elements
only the common attributes.
See also the generic <admonition> and the other specific admonition elements.
ExamplesA reStructuredText "warning" directive:
.. WARNING:: Reader discretion is strongly advised.
Pseudo-XML fragment from simple parsing:
<warning>
<paragraph>
Reader discretion is strongly advised.Attribute Types
Standard Attribute Types
Standard attribute types are defined in the attribute types section of the XML 1.0 specification [xml1.0].
Character data. CDATA attributes may contain arbitrary text.
A "name token". One or more of letters, digits, ".", "-", and "_".
One or more space-separated NMTOKEN values.
The attribute value may be one of a specified list of values.
To highlight specific attribute value constraints, the Docutils Generic DTD defines custom attribute types via parameter entities that resolve to standard attribute types. In the docutils.nodes Python module, values are stored using the specified data types.
Used in the
classesattribute. Python data type:
list[str].
Used in the
refidattribute. Python data type:
str.
Used in the
backrefsattribute. Python data type:
list[str].
Used in the
idsattribute. Python data type:
list[str].
A number which may be immediately followed by a unit or percent sign. ReStructuredText supports
CSS3 length units. Attributes may restrict the value to some range. Handling of values without unit depends on the writer/output format (see the writer-specific documentation in the
user documentationfor details). Resolves to
CDATA.
Used in the
heightand
widthattributes. Python data type:
str.
The attribute value must be a positive interger. Resolves to
NMTOKEN.
Used in the
refnameattribute. Python data type:
str.
Space-separated list of
reference names. (Backslash escaping is used for space characters inside a
reference name.) Resolves to
CDATA.
Used in the
namesand
dupnamesattributes. Python data type:
list[str].
Boolean: False if zero ("0"), true for any other value. Resolves to
NMTOKEN.
Through the %basic.atts parameter entity, all elements except <meta> support the attributes ids, names or dupnames, source, and classes.
Attribute ReferenceAttribute type: CDATA. Default value: none.
The alt attribute is used to store a text description in the <image> element.
alignAttribute type: EnumeratedType. Default value: none (inherit).
The align attribute is used in the <figure> and <table> elements via the %align-h.att parameter entity and in <image> via the %align-hv.att parameter entity to specify the alignment of the element within its parent element.
The Exchange Table Model uses align in the <colspec>, <entry>, and <tgroup> elements to specify the text alignment in table cells. It cannot be specified in reStructuredText and is ignored by Docutils.
anonymousAttribute type: %yesorno. Default value: none (implies no).
The anonymous attribute is used for unnamed hyperlinks in the <target> and <reference> elements (via the %anonymous.att parameter entity).
autoAttribute type: CDATA. Default value: none.
The auto attribute is used to indicate automatically-numbered <footnote>, <footnote_reference> and <title> elements (via the %auto.att parameter entity). In <footnote> and <footnote_reference> elements, it also carries information about the label type: "1": auto-numbered, "*": auto-symbol.
backrefsAttribute type: %idrefs.type. Default value: none.
The backrefs attribute contains a space-separated list of identifier references, used for backlinks in <footnote>, <citation>, and <system_message> elements (via the %backrefs.att parameter entity).
bulletAttribute type: CDATA. Default value: none.
The bullet attribute is used in the <bullet_list> element to record the style of bullet from the input data. In documents processed from reStructuredText, it contains one of "-", "+", or "*". It may be ignored in processing.
classesAttribute type: %classnames.type. Default value: none.
The classes attribute is a space separated list containing zero or 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. It can be used to carry context forward between a Docutils Reader and Writer, when a custom structure is reduced to a standardized document tree. One common use is in conjunction with stylesheets, to add selection criteria. It should not be used to carry formatting instructions or arbitrary content.
The classes attribute's contents should be ignorable. Writers that are not familiar with the variant expressed should be able to ignore the attribute.
charAttribute type: CDATA. Default value: "" (no aligning character).
The char attribute is used in the <colspec> and <entry> elements to specify an alignment character.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
charoffAttribute type: NMTOKEN. Default value: "50" (i.e. 50%).
The charoff attribute is used in <colspec> and <entry> elements to specify the horizontal offset of the alignment character when align is "char".
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
colnameAttribute type: NMTOKEN. Default value: none.
The colname attribute is used in the <colspec> element to name a table column and in the <entry> element to reference a named column.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
colnumAttribute type: NMTOKEN. Default value: none.
The colnum attribute is defined for the <colspec> element by the Exchange Table Model. It serves no functional purpose other than a consistency check.
colsAttribute type: NMTOKEN. Default value: none.
The cols attribute is used in the <tgroup> element to store the number of columns in a table group.
The attribute is defined in the Exchange Table Model (which see for details).
colsepAttribute type: %yesorno. Default value: none.
The colsep attribute is used in the <colspec>, <entry>, <table>, and <tgroup> elements to specify the presence or absence of a column separator (vertical ruling).
The attribute is defined in the Exchange Table Model It cannot be specified in reStructuredText and is ignored by Docutils.
colwidthAttribute type: CDATA. Default value: "1*"
The colwidth attribute is used in the <colspec> element to specify the column width.
The attribute is defined in the Exchange Table Model (which see for details) as either a proportional measure (positive number followed by "*", e.g., "5*" for 5 times the unit proportion, or just "*" for one unit proportion) or a fixed measure (e.g., 2.5cm). Docutils supports only proportional measures.
Important
Currently, Docutils stores "colwidth" values as numbers and interprets unitless values as proportional measures while the Exchange Table Model uses the default unit "pt". This will change in future versions of Docutils.
delimiterAttribute type: CDATA. Default value: none.
The delimiter attribute is used in the <option_argument> element and contains the text preceding the <option_argument>: either the text separating it from the <option_string> (typically either "=" or " ") or the text between option arguments (typically either "," or " ").
dupnamesAttribute type: %refnames.type. Default value: none.
dupnames replaces the names attribute when there has been a naming conflict. It is one of the common attributes, shared by all Docutils elements.
enumtypeAttribute type: EnumeratedType, one of "arabic", "loweralpha", "upperalpha", "lowerroman", or "upperroman". Default value: none.
The enumtype attribute is used in the <enumerated_list> element to record the intended enumeration sequence.
1, 2, 3, ...
a, b, c, ..., z
A, B, C, ..., Z
i, ii, iii, iv, ..., mmmmcmxcix [4999]
I, II, III, IV, ..., MMMMCMXCIX [4999]
Attribute type: NMTOKENS. Default value: none.
The format attribute is used in the <raw> element. It contains one or more space separated output format names.
frameDefault value: none (implied).
The frame attribute may be used in the <table> element to specify the table's outer frame.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
heightAttribute type: %measure. Default value: none.
The height attribute is used in the <image> element.
idsAttribute type: %ids.type. Default value: none.
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.
levelAttribute type: %number. Default value: none.
The level attribute is used in the <system_message> element to indicate the message's severity level. See also the "type" attribute.
lineAttribute type: %number. Default value: none.
The line attribute is used in the <system_message> element to indicate the position of the reported problem in the document source. See also the source attribute.
ltrimAttribute type: %yesorno. Default value: none (implies no).
The ltrim attribute is used in the <substitution_definition> element.
loadingAttribute type: EnumeratedType, one of "embed", "link", or "lazy". Default value: none.
The loading attribute is used in the <image> and <figure> elements to indicate the preferred handling by the Docutils writer. [15] The default depends on the writer and the "image_loading" configuration setting.
New in Docutils 0.21
morecolsAttribute type: %number. Default value: none.
The morecols attribute is used in the <entry> element to specify an entry that spans several physical table columns. It is similar to the colspan attribute of HTML table cells (<th> and <td>).
The morecols attribute is defined in the %tbl.entry.att parameter entity.
morerowsAttribute type: %number. Default value: none.
The morerows attribute is used in the <entry> element to specify an entry that spans several physical table rows. It is similar to the rowspan attribute of HTML table cells (<th> and <td>).
The attribute is defined in the Exchange Table Model (which see for details).
nameAttribute type: NMTOKEN or CDATA. 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 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.
namesAttribute type: %refnames.type. Default value: none.
The names attribute is a space-separated list containing reference names of an element (spaces inside a name are backslash-escaped). It is one of the common attributes, shared by all Docutils elements.
Each name in the list must be unique; if there are name conflicts (two or more elements want to use the same name), the contents will be transferred to the dupnames attribute on the duplicate elements. [16]
namestAttribute type: NMTOKEN. Default value: none.
The namest attribute is used in the <entry> element to specify the leftmost column of a span.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils which uses the morecols attribute instead.
nameendAttribute type: NMTOKEN. Default value: none.
The nameend attribute is used in the <entry> element to specify the rightmost column of a span.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils which uses the morecols attribute instead.
pgwideAttribute type: %yesorno. Default value: none (implies no).
The pgwide attribute is used in the <table> element to make the table span the full page width.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
prefixAttribute type: CDATA. Default value: none.
The prefix attribute is used in the <enumerated_list> element to store the formatting characters used before the enumerator.
In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). Writers may ignore this attribute.
refidAttribute type: %idref.type. Default value: none.
The refid attribute contains a reference to another element via its identifier. It is used by the <citation_reference>, <footnote_reference>, <problematic>, <reference>, <target>, and <title> elements (via the %refid.att and %reference.atts parameter entities).
refnameAttribute type: %refname.type. Default value: none.
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).
On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference. Docutils transforms replace the refname attribute with a refid (refering to the same element) or a refuri (refering to an external ressource).
refuriAttribute type: CDATA. Default value: none.
The refuri attribute contains an external reference to a URI. It is used by the <target>, <reference>, <footnote_reference>, and <citation_reference> elements (via the %reference.atts parameter entity).
rowsepAttribute type: %yesorno. Default value: none (implies no).
The rowsep attribute may be used in the <colspec>, <entry>, <row>, <table>, and <tgroup> elements to specify the presence or absence of row separators (horizontal ruling).
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
rtrimAttribute type: %yesorno. Default value: none (implies no).
The rtrim attribute is used in the <substitution_definition> element.
scaleAttribute type: %number. Default value: none.
The scale attribute is used in the <image> element to store a uniform scaling factor (integer percentage value).
sourceAttribute 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. 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.
startAttribute type: %number. Default value: none (implies 1).
The start attribute is used in the <enumerated_list> element to store the ordinal value of the first item in the list, in decimal notation.
For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted.
stubAttribute type: %yesorno. Default value: none.
The stub attribute is used in the <colspec> element to mark a table column as containing stubs (row titles, on the left). See also the "csv-table" and "list-table" directives.
The attribute is defined in the %tbl.colspec.att parameter entity.
suffixAttribute type: CDATA. Default value: none.
The suffix attribute is used in the <enumerated_list> element to store the formatting characters used after the enumerator.
In documents originating from reStructuredText data, it will contain either "." (period) or ")" (right parenthesis). Depending on the capabilities of the output format, this attribute may or may not affect processing.
titleAttribute type: CDATA. Default value: none.
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 browser's title bar, in a user's history or bookmarks, or in search results.
typeAttribute type: NMTOKEN. Default value: none.
The type attribute is used in the <system_message> element. It holds the name of the message's severity level (cf. the "level" attribute).
uriAttribute type: CDATA. Default value: none.
The uri attribute is used in the <image> and <figure> elements to refer to the image via a URI Reference [17]. [rfc3986]
Docutils applies the "root_prefix" configuration setting when a URI Reference starting with "/" is converted to a local filesystem path.
valignDefault value: none (inherit).
The valign attribute is used in the <entry>, <row>, <tbody>, and <thead> elements to specify the vertical text alignment within entries.
The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.
widthAttribute type: %measure. Default value: none.
The width attribute is used in the <figure>, <image>, and <table> elements.
xml:spaceDefault value: "preserve" (fixed).
The xml:space attribute is a standard XML attribute for whitespace-preserving elements. It is used by the <address>, <comment>, <doctest_block>, <literal_block>, <math_block>, and <raw> elements (via the %fixedspace.att parameter entity). It is a fixed attribute, meant to communicate to an XML parser that the element contains significant whitespace. The attribute value should not be set in a document instance.
Parameter Entity ReferenceParameter entities are used to simplify the Docutils Generic DTD (share definitions and reduce duplication) and to allow it to be customized by wrapper DTDs (external client DTDs that use or import the`Docutils Generic` DTD).
Parameter entities may be overridden by wrapper DTDs, replacing the definitions below with custom definitions.
In addition, the Docutils Generic DTD defines parameter entities for custom attribute types.
Attribute Entities %align-h.attThe %align-h.att parameter entity contains the align attribute for horizontal alignment.
Entity definition:
align (left | center | right) #IMPLIED
The <figure> and <table> elements directly employ the %align-h.att parameter entity in their attribute lists.
%align-hv.attThe %align-hv.att parameter entity contains the align attribute for horizontal and vertical alignment.
Entity definition:
align (top | middle | bottom | left | center | right) #IMPLIED
The <image> element directly employs the %align-hv.att parameter entity in its attribute list.
%anonymous.attThe %anonymous.att parameter entity contains the anonymous attribute, used for unnamed hyperlinks.
Entity definition:
anonymous %yesorno; #IMPLIED
The <reference> and <target> elements directly employ the %anonymous.att parameter entity in their attribute lists.
%auto.attThe %auto.att parameter entity contains the auto attribute, used to indicate an automatically-numbered footnote or title.
Entity definition:
auto CDATA #IMPLIED
The <footnote>, <footnote_reference>, and <title> elements directly employ the %auto.att parameter entity in their attribute lists.
%backrefs.attThe %backrefs.att parameter entity contains the backrefs attribute, a space-separated list of id references, for backlinks.
Entity definition:
backrefs %idrefs.type; #IMPLIED
The <citation>, <footnote>, and <system_message> elements directly employ the %backrefs.att parameter entity in their attribute lists.
%basic.attsThe %basic.atts parameter entity lists the common attributes. The %additional.basic.atts placeholder can be used by wrapper DTDs to extend %basic.atts.
Entity definition:
ids NMTOKENS #IMPLIED names CDATA #IMPLIED dupnames CDATA #IMPLIED source CDATA #IMPLIED classes NMTOKENS #IMPLIED %additional.basic.atts;
All elements except <meta> directly employ the %basic.atts parameter entity in their attribute lists.
%bodyattThe %bodyatt parameter entity is defined in the Exchange Table Model to allow customization of the <table> element's attribute list.
The Docutils Generic DTD redefines it to add align, width, and the common attributes. (In Docutils versions ⥠1.0, the %tbl.table.att parameter entity will be redefined instead.)
%fixedspace.attThe %fixedspace.att parameter entity contains the xml:space attribute, a standard XML attribute for whitespace-preserving elements.
Entity definition:
xml:space (default | preserve) #FIXED 'preserve'
The %fixedspace.att parameter entity is directly employed in the attribute lists of the following elements: <address>, <comment>, <doctest_block>, <literal_block>, <math_block>, <raw>.
%reference.attsThe %reference.atts parameter entity groups together the refuri, refid, and refname attributes. The %additional.reference.atts placeholder can be used by wrapper DTDs to extend %reference.atts.
Entity definition:
%refuri.att; %refid.att; %refname.att; %additional.reference.atts;
The <citation_reference>, <footnote_reference>, <reference>, and <target> elements directly employ the %reference.att parameter entity in their attribute lists.
%refid.attThe %refid.att parameter entity contains the refid attribute, an internal reference to the ids attribute of another element.
Entity definition:
refid %idref.type; #IMPLIED
The <title> and <problematic> elements directly employ the %refid.att parameter entity in their attribute lists.
Via %reference.atts, the %refid.att parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.
%refname.attThe %refname.att parameter entity contains the refname attribute, an internal reference to the names attribute of another element. On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference.
Entity definition:
refname %refname.type; #IMPLIED
The <substitution_reference> element directly employs the %refname.att parameter entity in its attribute list.
Via %reference.atts, the %refname.att parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.
%refuri.attThe %refuri.att parameter entity contains the refuri attribute, an external reference to a URI.
Entity definition:
refuri CDATA #IMPLIED
Via %reference.atts, the %refuri.att parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.
%tbl.colspec.attThe %tbl.colspec.att parameter entity is defined in the Exchange Table Model to allow customization of the <colspec> element's attribute list.
The Docutils Generic DTD redefines it to add stub and the common attributes.
%tbl.entry.attThe %tbl.entry.att parameter entity is defined in the Exchange Table Model to allow customization of the <entry> element's attribute list.
The Docutils Generic DTD redefines it to add morecols and the common attributes.
%tbl.row.attThe %tbl.row.att parameter entity is defined in the Exchange Table Model to allow customization of the <row> element's attribute list.
The Docutils Generic DTD redefines it to add the common attributes.
%tbl.table.attThe %tbl.table.att parameter entity is defined in the Exchange Table Model to allow customization of the <table> element's attribute list.
Docutils versions ⥠1.0 will use %tbl.table.att (instead of the obsolete %bodyatt) to add align, width, and the common attributes.
%tbl.tbody.attThe %tbl.tbody.att parameter entity is defined in the Exchange Table Model to allow customization of the <tbody> element's attribute list.
The Docutils Generic DTD redefines it to add the common attributes.
%tbl.tgroup.attThe %tbl.tgroup.att parameter entity is defined in the Exchange Table Model to allow customization of the <tgroup> element's attribute list.
The Docutils Generic DTD redefines it to add the common attributes.
%tbl.thead.attThe %tbl.thead.att parameter entity is defined in the Exchange Table Model to allow customization of the <thead> element's attribute list.
The Docutils Generic DTD redefines it to add the common attributes.
Element Category Entities %bibliographic.elementsThe %bibliographic.elements parameter entity contains an OR-list of all Bibliographic Elements. The %additional.bibliographic.elements placeholder can be used by wrapper DTDs to extend %bibliographic.elements.
Only the <docinfo> element directly employs the %bibliographic.elements parameter entity in its content model.
%body.elementsThe %body.elements parameter entity contains an OR-list of all Body Elements.
The %additional.body.elements placeholder can be used by wrapper DTDs to extend %body.elements.
The %body.elements parameter entity is directly employed in the content models of the following elements: <admonition>, <attention>, <block_quote>, <caution>, <citation>, <compound>, <danger>, <definition>, <description>, <entry>, <error>, <field_body>, <footer>, <footnote>, <header>, <hint>, <important>, <legend>, <list_item>, <note>, <sidebar>, <system_message>, <tip>, <topic>, and <warning>
Via %structure.model, the %body.elements parameter entity is indirectly employed in the content models of the <document> and <section> elements.
%inline.elementsThe %inline.elements parameter entity contains an OR-list of all Inline Elements. The %additional.inline.elements placeholder can be used by wrapper DTDs to extend %inline.elements.
The %inline.elements parameter entity is employed in the %text.model parameter entity.
%section.elementsThe %section.elements parameter entity contains the <section> element. The %additional.section.elements placeholder can be used by wrapper DTDs to extend %section.elements.
Via %structure.model, the %section.elements parameter entity is indirectly employed in the content models of the <document> and <section> elements.
Model Entities %calstblxThe Docutils Generic DTD includes via the %calstblx parameter entity the XML Exchange Table Model DTD [tm9901] as an external DTD subset to define the elements <colspec>, <entry>, <row>, <table>, <tbody>, <tgroup>, and <thead>.
Entity definition:
<!ENTITY % calstblx PUBLIC
"-//OASIS//DTD XML Exchange Table Model 19990315//EN"
"soextblx.dtd">%structure.model
The %structure.model parameter entity encapsulates the hierarchical structure of a document and of its constituent parts. It contains body elements, structural elements, and the <transition> element. See the discussion in section Element Hierarchy above.
Simplified entity definition:
( ( %body.elements; | topic | sidebar | transition )*, ( %section.elements; | transition )* )
Each <document> or <section> contains zero or more body elements, topics, sidebars, or transitions, followed by zero or more sections (whose contents include this model), or transitions.
The actual entity definition is more complex,
( ( (%body.elements; | topic | sidebar)+, transition? )*,
( (%section.elements;),
(transition?, (%section.elements;) )* )? )
to impose the following restrictions:
A <transition> may not be the first element (i.e. it may not occur at the beginning of a document or directly after a title, subtitle, meta or decoration element).
Transitions must be separated by other elements (body elements, sections, etc.). In other words, a transition may not be immediately adjacent to another transition.
An additional restriction cannot be easily expressed in the language of DTDs: [18]
A transition may not occur at the end of a document or section.
The %structure.model parameter entity is directly employed in the content models of the <document> and <section> elements.
%tbl.entry.mdlThe %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):
(%body.elements;)*%tbl.tgroup.mdl
The %tbl.tgroup.mdl parameter entity is defined in the Exchange Table Model to allow customization of the <tgroup> element's content model.
The Docutils Generic DTD changes it to require at least one <colspec> element:
colspec+,thead?,tbody%text.model
The %text.model parameter entity is used by simple elements that may contain phrasing content, i.e. text data mixed with inline elements.
Entity definition:
(#PCDATA | %inline.elements;)*
The %text.model parameter entity is directly employed in the content models of the following elements: <abbreviation>, <acronym>, <address>, <attribution>, <author>, <caption>, <classifier>, <contact>, <copyright>, <date>, <doctest_block>, <emphasis>, <field_name>, <generated>, <inline>, <line>, <literal>, <literal_block>, <organization>, <paragraph>, <problematic>, <reference>, <revision>, <rubric>, <status>, <strong>, <subscript>, <substitution_definition>, <substitution_reference>, <subtitle>, <superscript>, <target>, <term>, <title>, <title_reference>, <version>
PlaceholdersThe following empty placeholders are employed to allow easy extension of the corresponding parameter entity by wrapper DTDs:
Glossarydefine sub-classes of existing elements.
Class names are used in the classes attribute (%classnames.type).
Docutils employs the identifier normalization to ensure class names conform to both, HTML4.1 and CSS1.0 name requirements (the regular expression [a-z](-?[a-z0-9]+)*).
In reStructuredText, custom class names can be specified using the "class" directive, a directive's class option, or custom interpreted text roles.
are used for cross references in generated documents.
Identifiers are used in the ids, refid, and backrefs attributes (%ids.type, %idref.type, or %idrefs.type) [19].
Docutils employs the identifier normalization to comply with restrictions in the supported output formats (HTML4.1, HTML5, polyglot HTML, LaTeX, ODT, manpage, XML).
Identifiers cannot be specified directly in reStructuredText. Docutils generates them from reference names or from the "auto_id_prefix" (prepending the "id_prefix" and appending numbers for disambiguation if required).
is text data that may be intermixed with inline elements (cf. the %text.model parameter entity).
is a representation of XML where nesting is indicated by indentation and end-tags are not shown. Some of the precision of real XML is given up in exchange for easier readability. For example, the following are equivalent:
Real XML:
<document> <section ids="a-title" names="a title"> <title>A Title</title> <paragraph>A paragraph.</paragraph> </section> </document>
Pseudo-XML:
<document>
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
are identifiers assigned in the markup.
Reference names are used in the name, names, refname, and dupnames attributes (%refname.type or %refnames.type).
Reference names may consist of any text. Whitespace is normalized. [20] Hyperlinks, footnotes, and citations all share the same namespace for reference names. Comparison ignores case. Substitutions use a distinct namespace. Comparison is case-sensitive but forgiving.
In reStructuredText, reference names originate from internal hyperlink targets, a directive's name option, or the element's title or content and are used for internal cross-references.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4