| Author: | David Goodger |
|---|---|
| Contact: | goodger@python.org |
| Revision: | 5492 |
| Date: | 2008-01-01 |
| Copyright: | This document has been placed in the public domain. |
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 DTD XML document type definition, docutils.dtd, which is the definitive source for details of element structural relationships.
This document does not discuss implementation details. Those can be found in internal documentation (docstrings) for the docutils.nodes module, where the document tree data structure is implemented in a class library.
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 Introducing the Extensible Markup Language (XML).
The reStructuredText markup 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.
Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Notes are written in square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc.
+--------------------------------------------------------------------+ | document [may begin with a title, subtitle, decoration, docinfo] | | +--------------------------------------+ | | sections [each begins with a title] | +-----------------------------+-------------------------+------------+ | [body elements:] | (sections) | | | - literal | - lists | | - hyperlink +------------+ | | blocks | - tables | | targets | | para- | - doctest | - block | foot- | - sub. defs | | graphs | blocks | quotes | notes | - comments | +---------+-----------+----------+-------+--------------+ | [text]+ | [text] | (body elements) | [text] | | (inline +-----------+------------------+--------------+ | markup) | +---------+
The Docutils document model uses a simple, recursive model for section structure. A document node may contain body elements and section elements. Sections in turn may contain body elements and sections. The level (depth) of a section element is determined from its physical nesting level; unlike other document models (<h1> in HTML, <sect1> in DocBook, <div1> in XMLSpec) the level is not incorporated into the element name.
The Docutils document model uses strict element content models. Every element has a unique structure and semantics, but elements may be classified into general categories (below). Only elements which are meant to directly contain text data have a mixed content model, where text data and inline elements may be intermixed. This is unlike the much looser HTML document model, where paragraphs and text data may occur at the same level.
Structural elements may only contain child elements; they do not directly contain text data. Structural elements may contain body elements or further structural elements. Structural elements can only be child elements of other structural elements.
Category members: document, section, topic, sidebar
Structural subelements are child elements of structural elements. Simple structuctural subelements (title, subtitle) contain text data; the others are compound and do not directly contain text data.
Category members: title, subtitle, decoration, docinfo, transition
The docinfo element is an optional child of document. It groups bibliographic elements together. All bibliographic elements except authors and field contain text data. authors contains further bibliographic elements (most notably author). field contains field_name and field_body body subelements.
Category members: address, author, authors, contact, copyright, date, field, organization, revision, status, version
The decoration element is also an optional child of document. It groups together elements used to generate page headers and footers.
Body elements are contained within structural elements and compound body elements. There are two subcategories of body elements: simple and compound.
Category members: admonition, attention, block_quote, bullet_list, caution, citation, comment, compound, container, danger, definition_list, doctest_block, enumerated_list, error, field_list, figure, footnote, hint, image, important, line_block, literal_block, note, option_list, paragraph, pending, raw, rubric, substitution_definition, system_message, table, target, tip, warning
Simple body elements are empty or directly contain text data. Those that contain text data may also contain inline elements. Such elements therefore have a "mixed content model".
Category members: comment, doctest_block, image, literal_block, paragraph, pending, raw, rubric, substitution_definition, target
Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data.
Category members: 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
Compound body elements contain specific subelements (e.g. bullet_list contains list_item). Subelements may themselves be compound elements (containing further child elements, like field) or simple data elements (containing text data, like field_name). These subelements always occur within specific parent elements, never at the body element level (beside paragraphs, etc.).
Category members (simple): attribution, caption, classifier, colspec, field_name, label, line, option_argument, option_string, term
Category members (compound): definition, definition_list_item, description, entry, field, field_body, legend, list_item, option, option_group, option_list_item, row, tbody, tgroup, thead
Inline elements directly contain text data, and may also contain further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model".
Category members: abbreviation, acronym, citation_reference, emphasis, footnote_reference, generated, image, inline, literal, problematic, reference, strong, subscript, substitution_reference, superscript, target, title_reference, raw
Each element in the DTD (document type definition) is described in its own section below. Each section contains an introduction plus the following subsections:
Details (of element relationships and semantics):
Content Model:
The formal XML content model from the Docutils DTD, followed by:
Examples: reStructuredText examples are shown along with fragments of the document trees resulting from parsing. Pseudo-XML is used for the results of parsing and processing. Pseudo-XML 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.
Many of the element reference sections below are marked "to be completed". Please help complete this document by contributing to its writing.
The address element holds the surface mailing address information for the author (individual or group) of the document, or a third-party contact address. Its structure is identical to that of the literal_block element: whitespace is significant, especially newlines.
| Category: | |
|---|---|
| Parents: | The following elements may contain address: docinfo, authors |
| Children: | address elements contain text data plus inline elements. |
| Analogues: | address is analogous to the DocBook "address" element. |
| Processing: | As with the literal_block element, newlines and other whitespace is significant and must be preserved. However, a monospaced typeface need not be used. See also docinfo. |
%text.model;
| Attributes: | The address element contains the common attributes (ids, names, dupnames, source, and classes), plus xml:space. |
|---|---|
| Parameter Entities: | The %bibliographic.elements; parameter entity directly includes address. |
reStructuredText source:
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.
This element is a generic, titled admonition. Also see the specific admonition elements Docutils offers (in alphabetical order): caution, danger, error, hint, important, note, tip, warning.
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain admonition. |
| Children: | admonition elements begin with a title and may contain one or more body elements. |
| Analogues: | admonition has no direct analogues in common DTDs. It can be emulated with primitives and type effects. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.). |
(title, (%body.elements;)+)
| Attributes: | The admonition element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes admonition. The %structure.model; parameter entity indirectly includes admonition. |
reStructuredText source:
.. admonition:: And, by the way... You can make up your own admonition too.
Pseudo-XML fragment from simple parsing:
<admonition class="admonition-and-by-the-way">
<title>
And, by the way...
<paragraph>
You can make up your own admonition too.
The attention element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): caution, danger, error, hint, important, note, tip, warning, and the generic admonition.
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain attention. |
| Children: | attention elements contain one or more body elements. |
| Analogues: | attention has no direct analogues in common DTDs. It can be emulated with primitives and type effects. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.), with the generated title "Attention!" (or similar). |
(%body.elements;)+
| Attributes: | The attention element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes attention. The %structure.model; parameter entity indirectly includes attention. |
reStructuredText source:
.. Attention:: All your base are belong to us.
Pseudo-XML fragment from simple parsing:
<attention>
<paragraph>
All your base are belong to us.
The author element holds the name of the author of the document.
| Category: | Bibliographic Elements |
|---|---|
| Parents: | The following elements may contain author: docinfo, authors |
| Children: | author elements may contain text data plus inline elements. |
| Analogues: | author is analogous to the DocBook "author" element. |
| Processing: | See docinfo. |
%text.model;
| Attributes: | The author element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %bibliographic.elements; parameter entity directly includes author. |
reStructuredText source:
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.
The authors element is a container for author information for documents with multiple authors.
| Category: | Bibliographic Elements |
|---|---|
| Parents: | Only the docinfo element contains authors. |
| Children: | authors elements may contain the following elements: author, organization, address, contact |
| Analogues: | authors is analogous to the DocBook "authors" element. |
| Processing: | See docinfo. |
((author, organization?, address?, contact?)+)
| Attributes: | The authors element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %bibliographic.elements; parameter entity directly includes authors. |
reStructuredText source:
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
In reStructuredText, multiple author's names are separated with semicolons (";") or commas (","); semicolons take precedence. There is currently no way to represent the author's organization, address, or contact in a reStructuredText "Authors" field.
See docinfo for a more complete example, including processing context.
The block_quote element is used for quotations set off from the main text (standalone).
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain block_quote. |
| Children: | block_quote elements contain body elements followed by an optional attribution element. |
| Analogues: | block_quote is analogous to the "blockquote" element in both HTML and DocBook. |
| Processing: | block_quote elements serve to set their contents off from the main text, typically with indentation and/or other decoration. |
((%body.elements;)+, attribution?)
| Attributes: | The block_quote element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes block_quote. The %structure.model; parameter entity indirectly includes block_quote. |
reStructuredText source:
As a great paleontologist once said,
This theory, that is mine, is mine.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<paragraph>
As a great paleontologist once said,
<block_quote>
<paragraph>
This theory, that is mine, is mine.
<attribution>
Anne Elk (Miss)
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.
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain bullet_list. |
| Children: | bullet_list elements contain one or more list_item elements. |
| Analogues: | bullet_list is analogous to the HTML "ul" element and to the DocBook "itemizedlist" element. HTML's "ul" is short for "unordered list", which we consider to be a misnomer. "Unordered" implies that the list items may be randomly rearranged without affecting the meaning of the list. Bullet lists are often ordered; the ordering is simply left implicit. |
| Processing: | Each list item should begin a new vertical block, prefaced by a bullet/dingbat. |
(list_item +)
| Attributes: | The bullet_list element contains the common attributes (ids, names, dupnames, source, and classes), plus bullet. bullet is used 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. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes bullet_list. The %structure.model; parameter entity indirectly includes bullet_list. |
reStructuredText source:
- 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.
The caution element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, danger, error, hint, important, note, tip, warning, and the generic admonition.
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain caution. |
| Children: | caution elements contain one or more body elements. |
| Analogues: | caution is analogous to the DocBook "caution" element. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.), with the generated title "Caution" (or similar). |
(%body.elements;)+
| Attributes: | The caution element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes caution. The %structure.model; parameter entity indirectly includes caution. |
reStructuredText source:
.. Caution:: Don't take any wooden nickels.
Pseudo-XML fragment from simple parsing:
<caution>
<paragraph>
Don't take any wooden nickels.
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.
| Category: | Body Subelements (simple) |
|---|---|
| Parents: | Only the definition_list_item element contains classifier. |
| Children: | classifier elements may contain text data plus inline elements. |
| Analogues: | classifier has no direct analogues in common DTDs. It can be emulated with primitives or type effects. |
| Processing: | See definition_list_item. |
%text.model;
| Attributes: | The classifier element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|
Here is a hypothetical data dictionary. reStructuredText source:
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.
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.
| Category: | Bibliographic Elements |
|---|---|
| Parents: | The following elements may contain contact: docinfo, authors |
| Children: | contact elements may contain text data plus inline elements. |
| Analogues: | contact is analogous to the DocBook "email" element. The HTML "address" element serves a similar purpose. |
| Processing: | See docinfo. |
%text.model;
| Attributes: | The contact element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %bibliographic.elements; parameter entity directly includes contact. |
reStructuredText source:
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.
The copyright element contains the document's copyright statement.
| Category: | Bibliographic Elements |
|---|---|
| Parents: | Only the docinfo element contains copyright. |
| Children: | copyright elements may contain text data plus inline elements. |
| Analogues: | copyright is analogous to the DocBook "copyright" element. |
| Processing: | See docinfo. |
%text.model;
| Attributes: | The copyright element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %bibliographic.elements; parameter entity directly includes copyright. |
reStructuredText source:
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.
The danger element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, error, hint, important, note, tip, warning, and the generic admonition.
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain danger. |
| Children: | danger elements contain one or more body elements. |
| Analogues: | danger has no direct analogues in common DTDs. It can be emulated with primitives and type effects. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.), with the generated title "!DANGER!" (or similar). |
(%body.elements;)+
| Attributes: | The danger element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes danger. The %structure.model; parameter entity indirectly includes danger. |
reStructuredText source:
.. DANGER:: Mad scientist at work!
Pseudo-XML fragment from simple parsing:
<danger>
<paragraph>
Mad scientist at work!
The date element contains the date of publication, release, or last modification of the document.
| Category: | Bibliographic Elements |
|---|---|
| Parents: | Only the docinfo element contains date. |
| Children: | date elements may contain text data plus inline elements. |
| Analogues: | date is analogous to the DocBook "date" element. |
| Processing: | Often used with the RCS/CVS keyword "Date". See docinfo. |
%text.model;
| Attributes: | The date element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %bibliographic.elements; parameter entity directly includes date. |
reStructuredText source:
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.
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.
| Category: | Structural Subelements |
|---|---|
| Parents: | Only the document element contains decoration. |
| Children: | decoration elements may contain decorative elements. |
| Analogues: | There are no direct analogies to decoration in HTML or in DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. |
| Processing: | See the individual decorative elements. |
(header?, footer?)
Although the content model doesn't specifically require contents, no empty decoration elements are ever created.
| Attributes: | The decoration element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|
reStructuredText source:
A paragraph.
Complete pseudo-XML result after parsing and applying transforms, assuming that the datestamp command-line option or configuration setting has been supplied:
<document>
<decoration>
<footer>
<paragraph>
Generated on: 2002-08-20.
<paragraph>
A paragraph.
The definition element is a container for the body elements used to define a term in a definition_list.
| Category: | Body Subelements (compound) |
|---|---|
| Parents: | Only definition_list_item elements contain definition. |
| Children: | definition elements may contain body elements. |
| Analogues: | definition is analogous to the HTML "dd" element and to the DocBook "listitem" element (inside a "variablelistentry" element). |
| Processing: | See definition_list_item. |
(%body.elements;)+
| Attributes: | The definition element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|
See the examples for the definition_list, definition_list_item, and classifier elements.
The definition_list element contains a list of terms and their definitions. It can be used for glossaries or dictionaries, to describe or classify things, for dialogues, or to itemize subtopics (such as in this reference).
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain definition_list. |
| Children: | definition_list elements contain one or more definition_list_item elements. |
| Analogues: | definition_list is analogous to the HTML "dl" element and to the DocBook "variablelist" element. |
| Processing: | See definition_list_item. |
(definition_list_item +)
| Attributes: | The definition_list element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes definition_list. The %structure.model; parameter entity indirectly includes definition_list. |
reStructuredText source:
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.
The definition_list_item element contains a single term/definition pair (with optional classifier).
| Category: | Body Subelements (compound) |
|---|---|
| Parents: | Only the definition_list element contains definition_list_item. |
| Children: | definition_list_item elements each contain a single term, an optional classifier, and a definition. |
| Analogues: | definition_list_item is analogous to the DocBook "variablelistentry" element. |
| Processing: | The optional classifier can be rendered differently from the term. They should be separated visually, typically by spaces plus a colon or dash. |
(term, classifier?, definition)
| Attributes: | The definition_list_item element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|
reStructuredText source:
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>
<paragraph>
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
<paragraph>
-- Anne Elk (Miss)
See definition_list and classifier for further examples.
The description element contains body elements, describing the purpose or effect of a command-line option or group of options.
| Category: | Body Subelements |
|---|---|
| Parents: | Only the option_list_item element contains description. |
| Children: | description elements may contain body elements. |
| Analogues: | description has no direct analogues in common DTDs. |
| Processing: | See option_list. |
(%body.elements;)+
| Attributes: | The description element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|
See the examples for the option_list element.
The docinfo element is a container for 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.
| Category: | |
|---|---|
| Parents: | Only the document element contains docinfo. |
| Children: | docinfo elements contain bibliographic elements. |
| Analogues: | docinfo is analogous to DocBook "info" elements ("bookinfo" etc.). There are no directly analogous HTML elements; the "meta" element carries some of the same information, albeit invisibly. |
| Processing: | 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. |
(%bibliographic.elements;)+
| Attributes: | The docinfo element contains only the common attributes: ids, names, dupnames, source, and classes. |
|---|
Docinfo is represented in reStructuredText by a field_list in a bibliographic context: the first non-comment element of a document, after any document title/subtitle. The field list is transformed into a docinfo element and its children by a transform. 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>
<field_name>
Filename
<field_body>
<paragraph>
doctree.txt
<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 an example in a non-bibliographic context. Also see the individual examples for the various bibliographic elements.
The doctest_block element is a Python-specific variant of literal_block. It is a block of text where line breaks and whitespace are significant and must be preserved. doctest_block elements are used for interactive Python interpreter sessions, which are distinguished by their input prompt: >>>. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.
| Category: | Simple Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain doctest_block. |
| Children: | doctest_block elements may contain text data plus inline elements. |
| Analogues: | doctest_block is analogous to the HTML "pre" element and to the DocBook "programlisting" and "screen" elements. |
| Processing: | 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. |
%text.model;
| Attributes: | The doctest_block element contains the common attributes (ids, names, dupnames, source, and classes), plus xml:space. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes doctest_block. The %structure.model; parameter entity indirectly includes doctest_block. |
reStructuredText source:
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 document element is the root (topmost) element of the Docutils document tree. document is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document.
| Category: | Structural Elements |
|---|---|
| Parents: | The document element has no parents. |
| Children: | document elements may contain structural subelements, structural elements, and body elements. |
| Analogues: | document is analogous to the HTML "html" element and to several DocBook elements such as "book". |
( (title, subtitle?)?, decoration?, (docinfo, transition?)?, %structure.model; )
Depending on the source of the data and the stage of processing, the "document" may not initially contain a "title". A document title is not directly representable in reStructuredText. Instead, a lone top-level section may have its title promoted to become the document title, and similarly for a lone second-level (sub)section's title to become the document subtitle.
The contents of "decoration" may be specified in a document, constructed programmatically, or both. The "docinfo" may be transformed from an initial field_list.
See the %structure.model; parameter entity for details of the body of a document.
| Attributes: | The document element contains the common attributes (ids, names, dupnames, source, and classes), plus an optional title attribute which stores the document title metadata. |
|---|
reStructuredText source:
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.
The enumerated_list element contains list_item elements which are uniformly marked with enumerator labels.
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain enumerated_list. |
| Children: | enumerated_list elements contain one or more list_item elements. |
| Analogues: | enumerated_list is analogous to the HTML "ol" element and to the DocBook "orderedlist" element. |
| Processing: | Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1."). |
(list_item +)
| Attributes: | The enumerated_list element contains the common attributes (ids, names, dupnames, source, and classes), plus enumtype, prefix, suffix, and start. enumtype is used to record the intended enumeration sequence, one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., MMMMCMXCIX [4999]). prefix stores the formatting characters used before the enumerator. In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). It may or may not affect processing. suffix stores 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. start contains the ordinal value of the first item in the list, in decimal. For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted. |
|---|---|
| Parameter Entities: | The %body.elements; parameter entity directly includes enumerated_list. The %structure.model; parameter entity indirectly includes enumerated_list. |
reStructuredText source:
1. Item 1. (A) Item A. (B) Item B. (C) Item C. 2. Item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list e