`_, `\<subtitle>`_ :compound: `\<decoration>`_, `\<docinfo>`_ :Docutils class: ``nodes.SubStructural`` Decorative Elements ------------------- Decorative elements are used to generate page headers and footers. They are child elements of `\<decoration>`_ and contain `body elements`_. .. class:: field-indent-11em :Category members: `\<footer>`_, `\<header>`_ :Docutils class: ``nodes.Decorative`` Bibliographic Elements ---------------------- Bibliographic 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). .. class:: narrow run-in :Category members: .. class:: narrow run-in :simple: `\<address>`_, `\<author>`_, `\<contact>`_, `\<copyright>`_, `\<date>`_, `\<organization>`_, `\<revision>`_, `\<status>`_, `\<version>`_ :compound: `\<authors>`_, `\<field>`_ :Docutils class: ``nodes.Bibliographic`` :Parameter entity: `%bibliographic.elements`_ Body Elements ------------- 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. .. class:: narrow run-in :Category members: .. class:: narrow run-in :empty: `\<image>`_ , `\<pending>`_, `\<target>`_ :simple: `\<comment>`_, `\<doctest_block>`_, `\<literal_block>`_, `\<math_block>`_, `\<paragraph>`_, `\<raw>`_, `\<reference>`_, `\<rubric>`_, `\<substitution_definition>`_ :compound: `\<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>`_ :Docutils class: ``nodes.Body`` :Parameter Entities: `%body.elements`_ directly includes all body elements, `%structure.model`_ indirectly includes all body elements. Body Subelements ---------------- 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`_. .. class:: narrow run-in :Category members: .. class:: narrow run-in :empty: `\<colspec>`_ :simple: `\<attribution>`_, `\<caption>`_, `\<classifier>`_, `\<field_name>`_, `\<label>`_, `\<line>`_, `\<option_argument>`_, `\<option_string>`_, `\<term>`_, `\<title>`_ :compound: `\<definition>`_, `\<definition_list_item>`_, `\<description>`_, `\<entry>`_, `\<field>`_, `\<field_body>`_, `\<legend>`_, `\<list_item>`_, `\<option>`_, `\<option_group>`_, `\<option_list_item>`_, `\<row>`_, `\<tbody>`_, `\<tgroup>`_, `\<thead>`_ :Docutils class: ``nodes.Part`` Inline Elements --------------- 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. .. class:: narrow run-in :Category members: `\<abbreviation>`_, `\<acronym>`_, `\<citation_reference>`_, `\<emphasis>`_, `\<footnote_reference>`_, `\<generated>`_, `\<image>`_, `\<inline>`_, `\<literal>`_, `\<math>`_, `\<problematic>`_, `\<raw>`_, `\<reference>`_, `\<strong>`_, `\<subscript>`_, `\<substitution_reference>`_, `\<superscript>`_, `\<target>`_, `\<title_reference>`_ :Docutils class: ``nodes.Inline`` :Parameter Entities: `%inline.elements`_ directly includes all inline elements, `%text.model`_ indirectly includes all inline elements. ------------------- Element Reference ------------------- .. contents:: :local: :depth: 1 Introduction ============ 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): :Category: One or more references to the element categories in the `Element Hierarchy`_ above. Some elements belong to more than one category. :Analogues: Analogous elements in well-known document models such as `HTML` [html.spec]_ or `DocBook` [tdg5.1]_. Describes similarities and differences. :Processing: Formatting or rendering recommendations for the element. :Parents: Elements which may contain the element. :Children: Elements which may occur within the element. Optionally followed by the formal XML content model from the `Docutils Generic DTD`_. :Attributes: XML Attributes that are defined for this element. :Parameter Entities: `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. <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. :Category: `Inline Elements`_ :Analogues: <abbreviation> is analogous to the DocBook_ <abbrev> element. The HTML_ <abbr> element is used for both, abbreviations and acronyms. :Processing: May be used to semantically mark the presence of an abbreviation in the text for styling or scripting purposes. Writers_ may ignore the element and just render its contents. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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). :Category: `Inline Elements`_ :Analogues: <acronym> is analogous to the DocBook_ <acronym> element. The HTML_ <abbr> element is used for both, abbreviations and acronyms. :Processing: May be used to semantically mark the presence of an acronym in the text for styling or scripting purposes. Writers_ may ignore the element and just render its contents. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <address> is analogous to the DocBook_ <address> element. :Processing: As with the `\<literal_block>`_ element, newlines are significant and must be preserved. However, a monospaced typeface should not be used. :Parents: `\<docinfo>`_, `\<authors>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: 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. Examples -------- In 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. :Category: `Compound Body Elements`_ :Analogues: The generic <admonition> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. The specific admonitions `\<caution>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_ are analogous to the respective DocBook_ elements. :Processing: Rendered distinctly (inset and/or in a box, etc.). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: <admonition> elements begin with a `\<title>`_ and may contain one or more `body elements`_. :Attributes: only the `common attributes`_. See also the _`specific admonition elements` `\<attention>`_ `\<caution>`_, `\<danger>`_, `\<error>`_, `\<hint>`_, `\<important>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_. Examples -------- The 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. :Category: `Compound Body Elements`_ :Analogues: <attention> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Attention!" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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>`_. :Category: `Body Subelements`_ (simple) :Analogues: <attribution> is analogous to the DocBook_ <attribution> element. :Processing: Placed below the block quote, usually be preceded by a dash, right aligned, or otherwise set apart from the quotation. :Parent: `\<block_quote>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. The Docutils HTML and LaTeX writers provide the `"attribution"`_ setting to configure the formatting of the `\<attribution>`_. Examples -------- See `\<block_quote>`_. <author> ======== The <author> element holds the name of the author (or one of the authors) of the document. :Category: `Bibliographic Elements`_ :Analogues: <author> is analogous to the DocBook_ <personname> element. :Processing: see `\<docinfo>`_ :Parents: `\<docinfo>`_, `\<authors>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <authors> is analogous to the DocBook_ <authorgroup> element. :Processing: See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: `\<author>`_, `\<organization>`_, `\<address>`_, `\<contact>`_:: ((author, organization?, address?, contact?)+) :Attributes: only the `common attributes`_. Examples -------- 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). :Category: `Compound Body Elements`_ :Analogues: <block_quote> is analogous to the <blockquote> element in both HTML_ and DocBook_. :Processing: <block_quote> elements serve to set their contents off from the main text, typically with indentation and/or other decoration. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: `body elements`_ followed by an optional `\<attribution>`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <bullet_list> is analogous to the HTML_ <ul> element [#]_ and to the DocBook_ <itemizedlist> element. :Processing: Each list item should begin a new vertical block, prefaced by a bullet/dingbat. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<list_item>`_ elements :Attributes: the `common attributes`_ and bullet_. .. [#] 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. Examples -------- 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>`_. [#]_ :Category: `Body Subelements`_ (simple) :Analogues: The <caption> element is analogous to the DocBook_ <title> element (but specific to a `\<figure>`_). The HTML_ <figcaption> element combines <caption> and `\<legend>`_. :Processing: Placed above, below, or besides the image it describes. Often preceded by a figure number. May be repeated in a generated "list of figures". :Parent: `\<figure>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- See `\<figure>`_. .. [#] The title/caption of a `\<table>`_ is represented by a `\<title>`_ element. <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`_. :Category: `Compound Body Elements`_ :Analogues: <caution> is analogous to the `DocBook \<caution>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Caution" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <citation> is analogous to the DocBook_ <bibliomixed> element. [#]_ 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". :Processing: Formatted as entry in a bibliography or similar to a `\<footnote>`_. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: <citation> elements begin with a `\<label>`_ and contain `body elements`_:: (label, (%body.elements;)+) :Attributes: the `common attributes`_ and backrefs_. .. [#] The DocBook_ <citation> element resembles a `\<citation_reference>`_. Example ------- See `\<citation_reference>`_. <citation_reference> ==================== The <citation_reference> element represents a cross reference to a `\<citation>`_. :Category: `Inline Elements`_ :Analogues: 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. :Processing: Typically enclosed in square brackets. :Parents: all elements employing `%text.model`_ in their content models :Children: only text data :Attributes: refid_, refname_, and the `common attributes`_. Example ------- 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. :Category: `Body Subelements`_ (simple) :Analogues: <classifier> has no direct analogues in common DTDs. It can be emulated with primitives or type effects. :Processing: see `\<definition_list_item>`_ :Parent: `\<definition_list_item>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (empty) :Analogues: <colspec> is analogous to the DocBook_ <colspec> element. The HTML_ <col> element is related but has different semantics. :Processing: See `colspec`__ in the `Exchange Table Model`. :Parent: `\<tgroup>`_ :Children: none (empty) :Attributes: The `Exchange Table Model` defines the attributes align_, char_, charoff_, colname_, colnum_, colsep_, colwidth_, and rowsep_. [#]_ Via the `%tbl.colspec.att`_ parameter entity, <colspec> also accepts the `common attributes`_ and `stub`_. .. [#] Docutils ignores all attributes except colwidth_. __ https://www.oasis-open.org/specs/tm9901.html#AEN446 Examples -------- See `\<table>`_. <comment> ========= The <comment> element is used for explanatory notes that should not be visible in the document rendering. :Category: `Simple Body Elements`_ :Analogues: While most markup languages provide a syntax for comments, the <comment> element has no direct analogues in HTML or DocBook. :Processing: Included as comment or skipped in translations to other markup languages. [#]_ Hidden from the document rendering. :Parents: all elements employing `%body.elements`_, `%structure.model`_, or `%text.model`_ in their content models :Children: only text data :Attributes: the `common attributes`_ and `xml:space`_. Examples -------- In reStructuredText, a comment_ block [#]_ is started by two full stops. No processing is done on the content but beware of a misinterpretation as `explicit markup construct`_:: .. This is a *comment*. .. [This] is a *citation*. .. [This] is another *comment*. Pseudo-XML_ fragment from simple parsing:: <comment xml:space="preserve"> This is a *comment*. <citation ids="this" names="this"> <label> This <paragraph> is a <emphasis> citation . <comment xml:space="preserve"> [This] is another *comment*. .. [#] In Docutils, the `"strip_comments"`_ configuration setting triggers the removal of comment elements from the document tree. .. [#] There is no syntax for inline comments in reStructuredText. <compound> ========== The <compound> element combines multiple `body elements`_ to a single logical paragraph. :Category: `Compound Body Elements`_ :Analogues: The <compound> element has no direct analogues in common DTDs. In HTML, it can be emulated with <div> and CSS styling. [#]_ :Processing: Typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity (cf. the `"compound" directive`_). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. .. [#] The Docutils counterpart to HTML’s <div> is the `\<container>`_ element. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <contact> is analogous to the DocBook_ <email> element. The HTML_ <address> element serves a similar purpose. :Processing: See `\<docinfo>`_. :Parents: `\<docinfo>`_, `\<authors>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: The <container> element is analogous to the HTML_ <div> element or the SVG <g> element. :Processing: Can be used for styling or scripting purposes. An example is a frame or background colour based on the value of the classes_ attribute. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <copyright> is analogous to the DocBook_ <copyright> element. :Processing: see `\<docinfo>`_ :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <danger> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "!DANGER!" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Bibliographic Elements`_ :Analogues: <date> is analogous to the DocBook_ <date> element. :Processing: Often used with the RCS/CVS keyword "Date". See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Structural Subelements`_ :Analogues: There are no direct analogies to <decoration> in HTML or DocBook. :Processing: See the individual `decorative elements`_. :Parent: `\<document>`_ :Children: The `decorative elements`_ `\<header>`_ and/or `\<footer>`_. Although the content model doesn't specifically require contents, no empty <decoration> elements are ever created. :Attributes: only the `common attributes`_. Examples -------- See `\<header>`_ and `\<footer>`_. <definition> ============ The <definition> element is a container for the body elements used to define a `\<term>`_ in a `\<definition_list>`_. :Category: `Body Subelements`_ (compound) :Analogues: <definition> is analogous to the HTML_ <dd> element and to the DocBook_ <listitem> element (inside a <variablelistentry> element). :Processing: see `\<definition_list_item>`_ :Parent: `\<definition_list_item>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <definition_list> is analogous to the HTML_ <dl> element and to the DocBook_ <variablelist> element. :Processing: see `\<definition_list_item>`_ :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<definition_list_item>`_ elements :Attributes: only the `common attributes`_. See also `\<field_list>`_. Examples -------- A 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>`_. :Category: `Body Subelements`_ (compound) :Analogues: <definition_list_item> is analogous to the DocBook_ <variablelistentry> element. :Processing: The optional `\<classifier>`_\ s can be rendered differently from the `\<term>`_. They should be separated visually, typically by spaces plus a colon or dash. :Parent: `\<definition_list>`_ :Children: <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. :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Body Subelements`_ (compound) :Analogues: <description> has no direct analogues in common DTDs. :Processing: see `\<option_list>`_ :Parent: `\<option_list_item>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Structural Subelements`_ :Analogues: There are no directly analogous HTML or DocBook elements. The DocBook_ <info> element is related but ususally suppressed in the output. :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`_. :Parent: `\<document>`_ :Children: `bibliographic elements`_ :Attributes: only the `common attributes`_. See also the `\<meta>`_ element (for hidden meta-data). Examples -------- `Bibliographic data`_ is represented in reStructuredText by a `field list <rST field list_>`__ as the first visible element of a `document <rST document_>`__ (after optional document title and subtitle). The field list is transformed into a <docinfo> element and its children by the `DocInfo transform`_. [#abstract-dedication]_ 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`_. .. [#abstract-dedication] Exceptions are the fields "abstract" and "dedication" that are transformed to `\<topic>`_ elements adjacent to the <docinfo>. <doctest_block> =============== The <doctest_block> element is a Python-specific variant of a `\<literal_block>`_. :Category: `Simple Body Elements`_ :Analogues: <doctest_block> is analogous to the HTML_ <pre> element and 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. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: the `common attributes`_ and `xml:space`_. Examples -------- 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. :Category: `Root Element`_ :Analogues: <document> is analogous to the HTML_ <html> element and to several DocBook_ elements such as <book>. :Parents: The <document> element has no parents. :Children: `structural elements`_, `structural subelements`_, and `body elements`_ .. parsed-literal:: ( (title, subtitle?)?, meta*, decoration?, (docinfo, transition?)?, `%structure.model`_; ) See the `%structure.model`_ parameter entity for details of the body of a <document>. :Attributes: the `common attributes`_ and title_. <document> is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document. Depending on the source of the data and the stage of processing, the <document> may not initially contain a `\<title>`_. A document title is not directly representable in reStructuredText_. Instead, the `DocTitle transform`_ may promote a lone top-level section title to become the document `\<title>`_, and similarly a lone second-level (sub)section's title to become the document `\<subtitle>`_. The contents of "`\<decoration>`_" may be specified in a document, constructed programmatically, or both. The "`\<docinfo>`_" may be transformed from an initial `\<field_list>`_. Examples -------- A 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*. :Category: `Inline Elements`_ :Analogues: <emphasis> is analogous to the HTML_ <em> element and the DocBook_ <emphasis> element. :Processing: Typically displayed in italic type. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (compound) :Analogues: <entry> is analogous to the DocBook_ <entry> element. HTML_ differentiates between header entries <th> and data entries <td>. :Processing: 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. :Parents: `\<thead>`_, `\<tbody>`_ :Children: `body elements`_ (via the `%tbl.entry.mdl`_ parameter entity) :Attributes: The <entry> element accepts the colname_, namest_, nameend_, morerows_, colsep_, rowsep_, align_, char_, charoff_, and valign_ attributes (ignored by Docutils) and (via the `%tbl.entry.att`_ parameter entity) the `common attributes`_ and morecols_. __ https://www.oasis-open.org/specs/tm9901.html#AEN827 Examples -------- See `\<table>`_. <enumerated_list> ================= The <enumerated_list> element contains `\<list_item>`_ elements which are uniformly marked with enumerator labels. :Category: `Compound Body Elements`_ :Analogues: <enumerated_list> is analogous to the HTML_ <ol> element and to the DocBook_ <orderedlist> element. :Processing: Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1."). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<list_item>`_ elements :Attributes: enumtype_, prefix_, suffix_, start_, and the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <error> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Error" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Body Subelements`_ (compound), `Bibliographic Elements`_ :Analogues: <field> has no direct analogues in common DTDs. HTML_ uses <div> elements inside <dl> lists for grouping <dt>/<dd> pairs. :Processing: See `\<field_list>`_. :Parents: `\<docinfo>`_, `\<field_list>`_ :Children: one `\<field_name>`_ and one `\<field_body>`_ element :Attributes: only the `common attributes`_. Examples -------- See the examples for the `\<field_list>`_ and `\<docinfo>`_ elements. <field_body> ============ The <field_body> element is analogous to a database field's data. :Category: `Body Subelements`_ (compound) :Analogues: <field_body> is analogous to the HTML_ <dd> element. :Processing: see `\<field_list>`_ :Parent: `\<field>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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). :Category: `Compound Body Elements`_ :Analogues: <field_list> is analogue to the HTML_ <dl> element. :Processing: A <field_list> is typically rendered as a two-column list, 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. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<field>`_ elements :Attributes: 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. Examples -------- A reStructuredText `field list <rST 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. :Category: `Body Subelements`_ (simple) :Analogues: <field_name> is analogous to the HTML_ <dt> element. :Processing: See `\<field_list>`_. :Parent: `\<field>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- See the examples for the `\<field_list>`_ and `\<docinfo>`_ elements. <figure> ======== The <figure> element groups an `\<image>`_ with a `\<caption>`_ and/or `\<legend>`_. :Category: `Compound Body Elements`_ :Analogues: 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). :Processing: On paged media, figures may float to a different position if this helps the page layout. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: `\<image>`_ or `\<reference>`_ (with nested <image>) followed by `\<caption>`_ or `\<legend>`_ or both. :Attributes: align_ (via `%align-h.att`_) , width_, and the `common attributes`_. Examples -------- 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. <footer> ======== The <footer> element is a container element whose contents are meant to appear at the bottom of a web page, or repeated at the bottom of every printed page. :Category: `Decorative Elements`_ :Analogues: <footer> is analogous to the HTML_ <footer> element. There are no direct analogies to <footer> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. :Parent: `\<decoration>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. The <footer> element may contain processing information (datestamp, a link to Docutils_, etc.) as well as custom content. Examples -------- A document may get a <footer> decoration even without use of the reStructuredText `"footer" directive`_:: A paragraph. Complete pseudo-XML_ result after parsing and applying transforms_, assuming that the ``--date`` command-line option or `"datestamp"`_ configuration setting has been supplied:: <document> <decoration> <footer> <paragraph> Generated on: 2002-08-20. <paragraph> A paragraph. <footnote> ========== The <footnote> element is used for labelled notes_ that provide additional context to a passage of text (*footnotes* or *endnotes*). The corresponding footnote mark in running text is set by the `\<footnote_reference>`_ element. .. _notes: https://en.wikipedia.org/wiki/Note_(typography) :Category: `Compound Body Elements`_ :Analogues: <footnote> has no direct analogues in DocBook or HTML. The `DocBook \<footnote>`_ element combines features of <footnote> and `\<footnote_reference>`_. The HTML standard lists suggestions to `emulate footnotes`_. The `DPub ARIA`_ role "doc-footnote" may be used to mark a `conforming HTML emulation`_ (for collections of notes that occur at the end of a section, "doc-endnotes" is more appropriate). The corresponding types in the `EPUB 3 Structural Semantics Vocabulary`_ are "footnote" and "endnote". :Processing: A <footnote> element should be set off from the rest of the document, e.g. with a border or using a smaller font size. Footnotes may "float" to the bottom or margin of a page or a dedicated section. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: <footnote> elements begin with an optional [#]_ `\<label>`_ and contain `body elements`_:: (label?, (%body.elements;)+) :Attributes: the `common attributes`_ plus auto_ and backrefs_. .. [#] The footnote label will become mandatory in Docutils 1.0. Examples -------- reStructuredText uses `explicit markup blocks`_ for `footnotes`_:: .. [1] This is a footnote. Pseudo-XML_ fragment from simple parsing:: <footnote ids="id1" names="1"> <label> 1 <paragraph> This is a footnote. <footnote_reference> ==================== The <footnote_reference> element is an inline element representing a cross reference to a `\<footnote>`_ (a footnote mark). :Category: `Inline Elements`_ :Analogues: The <footnote_reference> element resembles the `DocBook \<footnoteref>`_ element or the LaTeX ``\footnotemark`` command. There is no equivalent in HTML. The <a> element can be used to provide a link to the corresponding footnote. :Processing: A <footnote_reference> should generate a mark matching the `\<label>`_ of the referenced footnote. The mark is typically formatted as superscript or enclosed in square brackets. :Parents: all elements employing `%text.model`_ in their content models :Children: only text data :Attributes: auto_, refid_, refname_, and the `common attributes`_. Examples -------- A reStructuredText `footnote reference`_ and footnote_:: [#]_ is an auto-numbered footnote reference. .. [#] First auto-numbered footnote. Pseudo-XML_ fragment from simple parsing:: <paragraph> <footnote_reference auto="1" ids="id1"> is an auto-numbered footnote reference. <footnote auto="1" ids="id3"> <paragraph> First auto-numbered footnote. The ``references.Footnotes`` Docutils transform_ resolves this to:: <paragraph> <footnote_reference auto="1" ids="id1" refid="id2"> 1 is an auto-numbered footnote reference. <footnote auto="1" backrefs="id1" ids="id2" names="1"> <label> 1 <paragraph> First auto-numbered footnote. <generated> =========== The <generated> element represents text that is not present in the document source but inserted by the processing system. :Category: `Inline Elements`_ :Analogues: There are no analogies to <generated> in HTML_ or DocBook_. :Processing: No special handling required. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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 <header> ======== The <header> element is a container element whose contents are meant to appear at the top of a web page, or at the top of every printed page. :Category: `Decorative Elements`_ :Analogues: <header> is analogous to the HTML_ <header> element. There are no direct analogies to <header> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. :Parent: `\<decoration>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- A reStructuredText `"header" directive`_:: .. header:: This space for rent. Pseudo-XML_ fragment from simple parsing:: <document> <decoration> <header> <paragraph> This space for rent. <hint> ====== The <hint> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <hint> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Hint" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Categories: `Body Elements`_, `Inline Elements`_ :Analogues: <image> is analogous to the `HTML \<img>`_, `DocBook \<imagedata>`_, and `SVG \<image>`_ elements. :Processing: The specified image is included into the output document. Depending on the output format, this is done by referring to the image URI or by embedding the image data. :Parents: all elements employing `%body.elements`_, `%text.model`_, or `%structure.model`_ in their content models :Children: none (empty) :Attributes: uri_, alt_, align_, height_, width_, scale_, loading_, and the `common attributes`_. It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX engine, HTML browser, ...). The `reStructuredText Directives` documentation contains a non exhaustive `table of compatible image formats`_. Examples -------- A 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"> .. _HTML <img>: https://html.spec.whatwg.org/multipage/embedded-content.html #the-img-element .. _SVG <image>: https://svgwg.org/svg2-draft/embedded.html#ImageElement <important> =========== The <important> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <important> is analogous to the `DocBook \<important>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Important" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Inline Elements`_ :Analogues: <inline> is analogous to the HTML_ <span> element and the DocBook_ <phrase> element. :Processing: 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. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- `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>`_. :Category: `Body Subelements`_ (simple) :Analogues: 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. :Processing: Rendered prominently, as first token of the footnote or citation. Often enclosed in square brackets. :Parents: `\<footnote>`_, `\<citation>`_ :Children: only text data :Attributes: only the `common attributes`_. Examples -------- 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>`_. :Category: `Body Subelements`_ (compound) :Analogues: The <legend> element is analogous to the DocBook_ <caption> element (but specific to a `\<figure>`_). The HTML_ <figcaption> element combines `\<caption>`_ and <legend>. :Processing: Formatted as a displayed block. :Parent: `\<figure>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- See `\<figure>`_. <line> ====== The <line> element contains a single line of text, part of a `\<line_block>`_. :Category: `Body Subelements`_ (simple) :Analogues: <line> has no direct analogues in common DTDs. It can be emulated with primitives or type effects. :Processing: See `\<line_block>`_. :Parent: `\<line_block>`_ :Children: text data plus `inline elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <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. :Processing: Each <line> should begin a new vertical block, without markers or additional spacing. Nested <line_blocks> should be indented. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: `\<line>`_, <line_block> :Attributes: only the `common attributes`_. See `\<literal_block>`_ for an alternative useful for program listings and interactive computer sessions. Examples -------- A 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. :Category: `Body Subelements`_ (compound) :Analogues: <list_item> is analogous to the HTML_ <li> element and to the DocBook_ <listitem> element. :Processing: See `\<bullet_list>`_ or `\<enumerated_list>`_. :Parents: `\<bullet_list>`_, `\<enumerated_list>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Inline Elements`_ :Analogues: <literal> is analogous to the DocBook_ <literal> element. HTML_ uses the specific elements <code>, <kbd>, and <samp> for code, input, and output. :Processing: Typically rendered in a monospace font. Preservation of line breaks and sequences of whitespace characters is not guaranteed. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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 ------- :Category: `Simple Body Elements`_ :Analogues: <literal_block> is analogous to the HTML_ <pre> element and to the DocBook_ <programlisting> and <screen> elements. :Processing: <literal_block> elements are typically rendered in a monospaced typeface. It is crucial that all whitespace and line breaks are preserved in the rendered form. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: 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. Examples -------- A 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` [#latex-math]_ that is typeset as mathematical notation (inline formula). :Category: `Inline Elements`_ :Analogues: <math> is related to the <math> element in MathML and HTML. However, it contains text data only. :Processing: Rendered as mathematical notation. If the output format does not support math typesetting, the content may be inserted verbatim. :Parents: all elements employing `%text.model`_ in their content models :Children: only text data :Attributes: only the `common attributes`_. Example ------- 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 . .. [#latex-math] For details of the supported mathematical language, see the `"math" directive`_ <math_block> ============ The <math_block> element contains a block of text in `LaTeX math format` [#latex-math]_ that is typeset as mathematical notation (display formula). :Category: `Simple Body Elements`_ :Analogues: <math_block> is analogous to a HTML/MathML <math> element displayed as block-level element or a LaTeX ``equation*`` environment. :Processing: 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. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: only text data :Attributes: the `common attributes`_ and `xml:space`_. Example ------- 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). :Category: `Structural Subelements`_ :Analogues: <meta> is analogous to the `HTML <meta> element`_ or the file properties in ODT or PDF documents. :Processing: 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). :Parent: `\<document>`_ :Children: none (empty) :Attributes: the attributes *content*, *dir*, *http-equiv*, *lang*, *media*, name_, and *scheme* that correspond to the respective attributes of the `HTML <meta> element`_. See also the `\<docinfo>`_ element for displayed meta-data. The document's `title attribute`_ stores the metadata document title. Example ------- A 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"> .. _HTML <meta> element: https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element <note> ====== The <note> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <note> is analogous to the `DocBook \<note>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Note" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Body Subelements`_ (compound) :Analogues: <option> has no direct analogues in common DTDs. :Processing: See `\<option_list>`_. :Parent: `\<option_group>`_ :Children: <option> elements start with an `\<option_string>`_ and may contain `\<option_argument>`_ elements:: (option_string, option_argument*) :Attributes: only the `common attributes`_. Note that reStructuredText_ currently supports only one argument per option. Examples -------- See the examples for the `\<option_list>`_ element. <option_argument> ================= The <option_argument> element contains placeholder text for option arguments. :Category: `Body Subelements`_ (simple) :Analogues: <option_argument> has no direct analogues in common DTDs. :Processing: 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. :Parent: `\<option>`_ :Children: only text data :Attributes: the `common attributes`_ and delimiter_. Examples -------- See the examples for the `\<option_list>`_ element. <option_group> ============== The <option_group> element groups together one or more `\<option>`_ elements, all synonyms. :Category: `Body Subelements`_ (compound) :Analogues: <option_group> has no direct analogues in common DTDs. :Processing: Typically `\<option>`_ elements within an <option_group> are joined together in a comma-separated list. :Parent: `\<option_list_item>`_ :Children: one or more `\<option>`_ elements :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <option_list> has no direct analogues in common DTDs. It can be emulated with primitives such as tables. :Processing: An <option_list> is typically rendered as a two-column list, where the first column contains option strings and arguments, and the second column contains descriptions. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<option_list_item>`_ elements :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Body Subelements`_ (compound) :Analogues: <option_list_item> has no direct analogues in common DTDs. :Processing: see `\<option_list>`_ :Parent: `\<option_list>`_ :Children: one `\<option_group>`_ and one `\<description>`_ :Attributes: only the `common attributes`_. Examples -------- See the examples for the `\<option_list>`_ element. <option_string> =============== The <option_string> element contains the text of a command-line option. :Category: `Body Subelements`_ (simple) :Analogues: <option_string> has no direct analogues in common DTDs. :Processing: The <option_string> text is typically rendered in a monospaced typeface. :Parent: `\<option>`_ :Children: only text data :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <organization> is analogous to the <orgname>, <corpname>, or <publishername> DocBook_ elements. :Processing: See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Simple Body Elements`_ :Analogues: <paragraph> is analogous to the HTML_ <p> element and to the DocBook_ <para> element. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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_. :Category: `Body Elements`_ (empty) :Analogues: <pending> has no direct analogues in common DTDs. :Processing: Usually replaced or removed by the associated transform_. Writers may ignore remaining <pending> elements. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: none (empty) :Attributes: only the `common attributes`_. Example ------- 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. :Category: `Inline Elements`_ :Analogues: <problematic> has no direct analogues in common DTDs. :Processing: Typically displayed in red colour. If the refid_ attribute is present, the element should point to the referenced element. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: the `common attributes`_ and refid_. Examples -------- 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. :Category: `Simple Body Elements`_, `Inline Elements`_ :Analogues: The <raw> element has no direct analogues in common DTDs. :Processing: Passed untouched to the Writer_. The interpretation is up to the Writer. A Writer may ignore <raw> elements not matching its format_. :Parents: all elements employing `%body.elements`_, `%structure.model`_, or `%text.model`_ in their content models :Children: only text data :Attributes: format_, `xml:space`_ and the `common attributes`_. Examples -------- The reStructuredText `"raw" directive`_ [#]_ 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> .. [#] For raw data pass-through in inline context, use `custom interpreted text roles`_ derived from the `"raw" role`_. <reference> =========== The <reference> element represents a cross reference to another element of the document or to an external ressource. :Category: `Simple Body Elements`_, `Inline Elements`_ :Analogues: The <reference> element is analogous to the DocBook_ <link> element and the HTML_ <a> (anchor) element. :Processing: 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 [#]_, or rendered in some other way. :Parents: all elements employing `%body.elements`_, `%text.model`_, or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: anonymous_, name_ (deprecated), refid_, refname_, refuri_, and the `common attributes`_. .. [#] See the `"target-notes" directive`_. Examples -------- 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 <rst/directives.html#target>`__ 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>`_. :Category: `Bibliographic Elements`_ :Analogues: <revision> is similar to (but simpler than) the DocBook_ <revision> element. It closely matches the DocBook_ <revnumber> element, but in a simpler context. :Processing: Often used with the RCS/CVS keyword "Revision". See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (compound) :Analogues: <row> is analogous to the HTML_ <tr> element and the DocBook_ <row> element. :Processing: Render content as a table row. See row__ in the `Exchange Table Model` for details. :Parents: `\<thead>`_, `\<tbody>`_ :Children: one or more `\<entry>`_ elements :Attributes: The <row> element may contain the rowsep_ and valign_ attributes (ignored by Docutils) and (via the `%tbl.row.att`_ parameter entity) the `common attributes`_. __ https://www.oasis-open.org/specs/tm9901.html#AEN741 Examples -------- See `\<table>`_. <rubric> ======== A <rubric> is an informal heading outside the document's section structure. :Category: `Simple Body Elements`_ :Analogues: <rubric> has no direct analogues in common DTDs. It shares some features with the <bridgehead> DocBook_ element. :Processing: Rendered similar to a section heading, traditionally highlighted in red (hence the name). Rubrics are not (auto)numbered and not included in the document's table of contents. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Example ------- The reStructuredText `"rubric" directive`_ can be used to get a heading at places where a section is not allowed:: .. sidebar:: Sidebar Title This is a sidebar. It is for text outside the flow of the main text. .. rubric:: A heading inside a sidebar Sections are not supported in a sidebar. A rubric can be used to structure the content instead. Pseudo-XML_ fragment from simple parsing:: <sidebar> <title> Sidebar Title <paragraph> This is a sidebar. It is for text outside the flow of the main text. <rubric> A heading inside a sidebar <paragraph> Sections are not supported in a sidebar. A rubric can be used to structure the content instead. <section> ========= The <section> element is the main unit of hierarchy for Docutils documents. .. class:: run-in :Category: `Structural Elements`_ :Analogues: <section> is analogous to the <section> elements in HTML_ and DocBook_. :Parents: `\<document>`_, `\<section>`_ :Children: <section> elements begin with a `\<title>`_, followed by an optional `\<subtitle>`_. They may contain `structural elements`_, `body elements`_, and `\<transition>`_ elements: .. parsed-literal:: (title, subtitle?, `%structure.model`_;) :Attributes: only the `common attributes`_ :Parameter Entities: `%section.elements`_ directly includes <section>, `%structure.model`_ indirectly includes <section>. The Docutils document model uses a simple, recursive model for section structure. A `\<document>`_ element may contain <section> elements. Sections in turn may contain other <section> elements, without limit. The level (depth) of a section element is determined from its physical nesting level. Paragraphs and other `body elements`_ may occur before a <section>, but not after it. Examples -------- reStructuredText 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. <sidebar> ========= Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. Their content is outside of the flow of the document's main text. .. class:: run-in :Category: `Structural Elements`_ :Analogues: <sidebar> is analogous to the DocBook_ <sidebar> element and the HTML_ <aside> element. :Processing: A <sidebar> element should be set off from the rest of the document somehow, typically with a border. Sidebars typically "float" to the side of the page and the document's main text flows around them. :Parents: `\<document>`_, `\<section>`_. :Children: <sidebar> elements begin with optional `\<title>`_ and `\<subtitle>`_ and contain `body elements`_ and `\<topic>`_ elements. There must not be a <subtitle> without title. :: ((title, subtitle?)?, (%body.elements; | topic)+) :Attributes: only the `common attributes`_ :Parameter Entities: `%structure.model`_ directly includes <sidebar>. The <sidebar> element is a non-recursive `\<section>`_-like construct. <sidebar> elements cannot nest inside body elements, so you can't have a <sidebar> inside a `\<table>`_ or a list, or inside another <sidebar> or `\<topic>`_. Examples -------- A reStructuredText `"sidebar" directive`_:: .. sidebar:: Optional Title :subtitle: If Desired Body. Pseudo-XML_ fragment from simple parsing:: <sidebar> <title> Optional Title <subtitle> If Desired <paragraph> Body. <status> ======== The <status> element contains a status statement for the document, such as "Draft", "Final", "Work In Progress", etc. :Category: `Bibliographic Elements`_ :Analogues: <status> is analogous to the DocBook_ <status> element. :Processing: See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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**. :Category: `Inline Elements`_ :Analogues: <strong> is analogous to the HTML_ <strong> element. :Processing: Typically displayed in boldface. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Inline Elements`_ :Analogues: <subscript> is analogous to the HTML_ <sub> element and the DocBook_ <subscript> element. :Processing: Typically rendered with a lowered baseline using smaller text. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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 content that shall replace matching `\<substitution_reference>`_ elements. :Category: `Simple Body Elements`_ :Analogues: Substitution definitions are analog to XML’s `internal entities`_ or programming language macros. :Processing: A <substitution_definition> is not directly rendered. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: ltrim_, rtrim_, and the `common attributes`_. The names_ attribute uses the "substitution" namespace_. Examples -------- A reStructuredText `substitution definition`_ allows to include complex inline structures within text while keeping the details out of the text flow:: The chemical formula for water is |H2O|. .. |H2O| replace:: H\ :sub:`2`\ O Pseudo-XML_ fragment from simple parsing:: <paragraph> The chemical formula for water is <substitution_reference refname="H2O"> H2O . <substitution_definition names="H2O"> H <subscript> 2 O The `references.Substitutions` transform_ replaces the `\<substitution_reference>`_ with the content of the <substitution_definition>:: <paragraph> The chemical formula for water is H <subscript> 2 O . <substitution_definition names="H2O"> H <subscript> 2 O A substitution definition can also supply an `\<image>`_ for inline use:: The |biohazard| symbol must be used on medical waste containers. .. |biohazard| image:: biohazard.png Pseudo-XML_ fragment from simple parsing:: <paragraph> The <substitution_reference refname="biohazard"> biohazard symbol must be used on medical waste containers. <substitution_definition names="biohazard"> <image alt="biohazard" uri="biohazard.png"> After running the `references.Substitutions` transform_, we get:: <paragraph> The <image alt="biohazard" uri="biohazard.png"> symbol must be used on medical waste containers. <substitution_definition names="biohazard"> <image alt="biohazard" uri="biohazard.png"> For more usage examples, see `Substitution Definitions`_ in the `reStructuredText Markup Specification`_. <substitution_reference> ======================== The <substitution_reference> element is a placeholder for the content of the matching <substitution_definition>. :Category: `Inline Elements`_ :Analogues: A <substitution_reference> is analogue to an XML `entity reference`_. :Processing: Replaced by the content of a matching `\<substitution_definition>`_. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: the `common attributes`_ plus refname_. The refname_ attribute uses the "substitution" namespace_. Examples -------- See `\<substitution_definition>`_. <subtitle> ========== The <subtitle> element stores the subtitle of a `\<document>`_, `\<section>`_, or `\<sidebar>`_. :Category: `Structural Subelements`_ :Analogues: <subtitle> is analogous to the DocBook_ <subtitle> element. In HTML, subtitles are represented by a <p> element inside a <hgroup_> element. :Processing: A document's subtitle is usually rendered smaller than its `\<title>`_. :Parents: `\<document>`_, `\<section>`_, and `\<sidebar>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. .. _hgroup: https://html.spec.whatwg.org/multipage/sections.html #the-hgroup-element <superscript> ============= The <superscript> element is an inline element representing text which should be displayed as superscript. :Category: `Inline Elements`_ :Analogues: <superscript> is analogous to the HTML_ <sup> element and the DocBook_ <superscript> element. :Processing: Typically rendered with a raised baseline using smaller text. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <system_message> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered similar to an `\<admonition>`_, with the generated title "System Message", its type_/level_ and, if available, source_ and line_. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: backrefs_, level_, line_, type_, and the `common attributes`_. In Docutils, system messages with a level lower than the `"report_level"`_ setting are removed by the `universal.FilterMessages` transform_. Examples -------- An 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`_. :Category: `Compound Body Elements`_ :Analogues: <table> is analogous to the <table> element in HTML_ and DocBook_. :Processing: Content is arranged in rows and columns forming a grid. See table__ in the `Exchange Table Model` for details. :Parents: `\<document>`_, `\<section>`_ and all `body elements`_ :Children: <table> elements begin with an optional `\<title>`_ (caption) and may contain one or more `\<tgroup>`_ elements:: (title?, tgroup+) :Attributes: 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_. __ https://www.oasis-open.org/specs/tm9901.html#AEN142 Examples -------- In reStructuredText, tables can be specified via the `"table" <"table" directive_>`__, `"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> ======== The <target> element provides an end-point for a hypertext `\<reference>`_. :Category: Empty `Body Elements`_, `Inline Elements`_ [#inline-targets]_ :Analogues: As body element, <target> is similar to the DocBook_ <anchor> element. An inline <target> can be represented by a DocBook <phrase> or HTML_ <span> element. :Processing: <target> elements with refid_, refname_, or refuri_ attribute (indirect targets) act as a relay for links to one of the target's ids_ or names_. A <target> without refid_, refname_, or refuri_ attributes provides ids_ or names_ for its content or, if empty, the next element. :Parents: all elements employing `%body.elements`_, `%structure.model`_, or `%text.model`_ in their content models :Children: only text data [#target-content]_ :Attributes: anonymous_, refid_, refname_, refuri_, and the `common attributes`_. .. [#inline-targets] Inline <target> elements will be deprecated in Docutils 1.0 and invalid in Docutils 2.0. The "rst" parser will use `\<inline>`_ elements for inline targets. .. [#target-content] <target> elements with content will be deprecated in Docutils 1.0 and invalid in Docutils 2.0. Examples -------- In reStructuredText, `hyperlink targets`_ are indicated by a leading underscore:: .. _inline: `inline target`_ .. _example: https//:example.org .. _alias: .. _explicit target: The hyperlink target above points to this paragraph with an _`inline target`. Pseudo-XML_ fragment from simple parsing:: <target ids="inline" names="inline" refname="inline target"> <target ids="example" names="example" refuri="https//:example.org"> <target ids="alias" names="alias"> <target ids="explicit-target" names="explicit\ target"> <paragraph> The hyperlink target above points to this paragraph with an <target ids="inline-target" names="inline\ target"> inline target . After applying transforms_, the paragraph has two reference names and two IDs, transferred from the preceding targets:: <target ids="inline" names="inline" refid="inline-target"> <target ids="example" names="example" refuri="https//:example.org"> <target refid="alias"> <target refid="explicit-target"> <paragraph ids="explicit-target alias" names="explicit\ target alias"> The hyperlink target above points to this paragraph with an <target ids="inline-target" names="inline\ target"> inline target . For more examples, see `\<reference>`_. <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`_. :Category: `Body Subelements`_ (compound) :Analogues: <tbody> is analogous to the <tbody> element in HTML_ and DocBook_. :Processing: Render content as table body. :Parent: `\<tgroup>`_ :Children: one or more `\<row>`_ elements :Attributes: valign_ (ignored by Docutils) and the `common attributes`_ (via the `%tbl.tbody.att`_ parameter entity). Examples -------- See `\<table>`_. <term> ====== The <term> element contains a word or phrase being defined in a `\<definition_list>`_. :Category: `Body Subelements`_ (simple) :Analogues: <term> is analogous to the HTML_ <dt> element and to the DocBook_ <term> element. :Processing: see `\<definition_list_item>`_ :Parent: `\<definition_list_item>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (compound) :Analogues: <tgroup> is analogous to the DocBook_ <tgroup> element. There is no corresponding HTML element (the <colgroup> element has a different purpose and semantics). :Processing: See tgroup__ in the `Exchange Table Model`. :Parent: `\<table>`_ :Children: One or more `\<colspec>`_ elements, followed by an optional `\<thead>`_ and a `\<tbody>`_ (cf. the `%tbl.tgroup.mdl`_ parameter entity). The number of <colspec>s, must not exceed the value of the cols_ attribute. Docutils expects one <colspec> per column. :Attributes: The <tgroup> element must contain a cols_ attribute and may contain colsep_, rowsep_, and align_ (ignored by Docutils). Via the `%tbl.tgroup.att`_ parameter entity, <tgroup> supports the `common attributes`_. __ https://www.oasis-open.org/specs/tm9901.html#AEN282 Tables usually consist of a single <tgroup>. Complex tables with widely varying column specifications may be easier to code using multiple <tgroup>s. However, this is not supported by `table markup in reStructuredText <rST tables_>`__ and Docutils table handling routines. Examples -------- See `\<table>`_. <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`_. :Category: `Body Subelements`_ (compound) :Analogues: <thead> is analogous to the <thead> element in HTML_ and DocBook_. :Processing: 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. :Parent: `\<tgroup>`_ :Children: one or more `\<row>`_ elements :Attributes: the valign_ attribute (ignored by Docutils) and (via the `%tbl.thead.att`_ parameter entity) the `common attributes`_. Examples -------- See `\<table>`_. <tip> ===== The <tip> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <tip> is analogous to the `DocBook \<tip>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Tip" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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>`_. :Category: `Structural Subelements`_, `Body Subelements`_ (simple) :Analogues: <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). :Parents: `\<admonition>`_, `\<document>`_, `\<section>`_, `\<sidebar>`_, `\<table>`_, and `\<topic>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: 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`_. Examples -------- Section_ 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. :Category: `Inline Elements`_ :Analogues: <title_reference> is analogous to the HTML_ <cite> element and the DocBook_ <citetitle> element. :Processing: Typically displayed in italic type. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. .. class:: run-in :Category: `Structural Elements`_ :Analogues: <topic> is analogous to the HTML_ <aside> element. The DocBook_ <simplesect> element is similar, but you cannot place `body elements`_ after a <simplesect>. :Processing: A <topic> element should be set off from the rest of the document somehow, such as with indentation or a border. In contrast to a `\<sidebar>`_, it should not float. :Parents: `\<document>`_, `\<section>`_, and `\<sidebar>`_ :Children: <topic> elements may begin with a `\<title>`_ and contain `body elements`_:: (title?, (%body.elements;)+) :Attributes: only the `common attributes`_ :Parameter Entities: `%structure.model`_ directly includes <topic>. Topics are terminal, "leaf" mini-sections, like block quotes with titles, or textual figures. A <topic> is just like a `\<section>`_, except that 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`_. Examples -------- A 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. .. class:: run-in :Category: `Structural Subelements`_ :Analogues: <transition> is analogous to the HTML_ <hr> element. :Processing: 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 or a vignette with vertical space above and below. :Parents: `\<document>`_, `\<section>`_ (cf. `%structure.model`_) :Children: none (empty) :Attributes: only the `common attributes`_ :Parameter Entities: The `%structure.model`_ directly includes <transition>. The document model sets additional restrictions on the placement of <transitions>: [#extra-rule]_ * A transition may not be immediately adjacent to another transition, i.e., <transition> elements must be separated by other elements. * A transition may not start the text of a document or section, i.e., a <transition> is invalid as first child or preceded by only `\<title>`_, `\<subtitle>`_, or invisible elements [#invisible-or-moving]_. * A transition may not occur at the end of a document or section. [#]_ In other words, a <transition> is invalid as last child element or followed by only invisible elements [#invisible-or-moving]_. See also `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. .. [#invisible-or-moving] The elements `\<meta>`_, `\<pending>`_, `\<substitution_definition>`_, and `\<target>`_ are not visible in the output document. The `\<decoration>`_ element contains `\<header>`_ and `\<footer>`_ which move to the respective places. .. [#] In reStructuredText markup, a transition may appear to fall at the end of a section immediately before another section. The `misc.Transitions` transform_ recognizes this case and moves the transition so it separates the sections. __ ../dev/rst/alternatives.html#doctree-representation-of-transitions __ ../dev/rst/alternatives.html Examples -------- A 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>`_. :Category: `Bibliographic Elements`_ :Analogues: <version> may be considered analogous to the <revision>, <revnumber>, or <biblioid> DocBook_ elements. :Processing: Sometimes used with the RCS/CVS keyword "Revision". See `\<docinfo>`_ and `\<revision>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <warning> is analogous to the `DocBook \<warning>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Warning" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A reStructuredText `"warning" directive`_:: .. WARNING:: Reader discretion is strongly advised. Pseudo-XML_ fragment from simple parsing:: <warning> <paragraph> Reader discretion is strongly advised. --------------- Attribute Types --------------- .. contents:: :local: Standard Attribute Types ======================== *Standard attribute types* are defined in the `attribute types <XML attribute types_>`__ section of the `XML 1.0 specification` [xml1.0]_. _`CDATA` Character data. CDATA attributes may contain arbitrary text. _`NMTOKEN` A "name token". One or more of letters, digits, ".", "-", and "_". _`NMTOKENS` One or more space-separated NMTOKEN_ values. _`EnumeratedType` The attribute value may be one of a specified list of values. Custom Attribute Types ====================== 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. _`%classnames.type` | Space-separated list of `class names`_. Resolves to NMTOKEN_. | Used in the `classes`_ attribute. Python data type: ``list[str]``. _`%idref.type` | A reference to another element by one of its identifiers_. Resolves to NMTOKEN_. [#id-vc]_ | Used in the `refid`_ attribute. Python data type: ``str``. .. _identifier: identifiers_ _`%idrefs.type` | Space separated list of references to other elements by their identifiers_. Resolves to NMTOKENS_. [#id-vc]_ | Used in the `backrefs`_ attribute. Python data type: ``list[str]``. _`%ids.type` | A space-separated list of unique `identifiers`_. Resolves to NMTOKENS_. [#id-vc]_ | Used in the `ids`_ attribute. Python data type: ``list[str]``. _`%measure` | 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 documentation`__ for details). Resolves to CDATA_. | Used in the `height`_ and `width`_ attributes. Python data type: ``str``. __ ../index.html#writer-specific _`%number` | The attribute value must be a positive interger. Resolves to NMTOKEN_. | Used in the level_, morecols_, morerows_, scale_, and start_ attributes. Python data type: ``int``. _`%refname.type` | A `reference name`_. Resolves to CDATA_. | Used in the `refname`_ attribute. Python data type: ``str``. _`%refnames.type` | Space-separated list of `reference names`_. (Backslash escaping is used for space characters inside a `reference name`.) Resolves to CDATA_. | Used in the `names`_ and `dupnames`_ attributes. Python data type: ``list[str]``. _`%yesorno` | Boolean: False if zero ("0"), true for any other value. Resolves to NMTOKEN_. | Used in the anonymous_, colsep_, ltrim_, rtrim_, rowsep_, and `stub`_ attributes. Python data type: ``bool``. Common Attributes ================= Through the `%basic.atts`_ parameter entity, all elements except `\<meta>`_ support the attributes ids_, names_ or dupnames_, source_, and classes_. --------------------- Attribute Reference --------------------- .. contents:: :local: :depth: 1 ``alt`` ======= Attribute type: `CDATA`_. Default value: none. The ``alt`` attribute is used to store a text description in the `\<image>`_ element. ``align`` ========= Attribute 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. ``anonymous`` ============= Attribute 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). ``auto`` ======== Attribute 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_). ``backrefs`` ============ Attribute 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). ``bullet`` ========== Attribute 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. ``classes`` =========== Attribute 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. ``char`` ======== Attribute 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. ``charoff`` =========== Attribute 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. ``colname`` =========== Attribute 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. ``colnum`` =========== Attribute 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. ``cols`` ========= Attribute 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`__). __ http://www.oasis-open.org/html/tm9901.html#AEN350 ``colsep`` ========== Attribute 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. ``colwidth`` ============ Attribute 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. __ https://www.oasis-open.org/specs/tm9901.html#AEN530 __ ../../RELEASE-NOTES.html#document-tree-docutils-dtd ``delimiter`` ============= Attribute 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 " "). ``dupnames`` ============ Attribute 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. ``enumtype`` ============ Attribute 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. Supported values: .. class:: field-indent-8em :arabic: 1, 2, 3, ... :loweralpha: a, b, c, ..., z :upperalpha: A, B, C, ..., Z :lowerroman: i, ii, iii, iv, ..., mmmmcmxcix [4999] :upperroman: I, II, III, IV, ..., MMMMCMXCIX [4999] ``format`` ========== 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. ``frame`` ========= | Attribute type: EnumeratedType_ (top|bottom|topbot|all|sides|none). | Default 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. ``height`` ========== Attribute type: `%measure`_. Default value: none. The ``height`` attribute is used in the `\<image>`_ element. ``ids`` ======= Attribute 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. An XPath_ expression to select the element with identifier `test` is :: //*[contains(concat(' ', @ids, ' '), ' test ')] (similar to `selecting an element by CSS class`__). .. TODO: * Use 'id' for primary identifier key? * Keep additional keys in `ids` or in the preceding target elements? __ https://stackoverflow.com/questions/1604471/how-can-i-find-an-element-by-css-class-with-xpath ``level`` ========= Attribute 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. ``line`` ========= Attribute 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. ``ltrim`` ========= Attribute type: `%yesorno`_. Default value: none (implies no). The ``ltrim`` attribute is used in the `\<substitution_definition>`_ element. ``loading`` =========== Attribute 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_. [#]_ The default depends on the writer and the `"image_loading"`_ configuration setting. New in Docutils 0.21 .. [#] Currently only recognized by the HTML5 writer. The ODF/ODT writer always embeds images in the output document, XML and LaTeX writers link to the image. The behaviour may change for the ODT and XML writers (images cannot be embedded in a LaTeX source). ``morecols`` ============ Attribute 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. ``morerows`` ============ Attribute 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`__). __ http://www.oasis-open.org/html/tm9901.html#AEN997 ``name`` ========= Attribute 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. ``names`` ========= Attribute 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. .. _reference name removal: Each reference name must be unique in its namespace_; if there are name conflicts (two or more elements want to use the same name), the affected name will be transferred to the `dupnames`_ attribute on the duplicate element(s). The element can no longer be used as hyperlink target. [#]_ An element may have both ``names`` and ``dupnames`` attributes, if the ``dupnames`` are from conflicting `implicit hyperlink targets`_ and the ``names`` from `explicit hyperlink targets`_ or a directive's `name option`_. .. [#] See `Implicit Hyperlink Targets`_ for details of conflict resolution. ``namest`` ========== Attribute 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. ``nameend`` =========== Attribute 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. ``pgwide`` ========== Attribute 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. ``prefix`` ========== Attribute 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. ``refid`` ========= Attribute type: `%idref.type`_. Default value: none. The ``refid`` attribute contains a reference to another element via one of its `identifiers`_. It is used by the `\<citation_reference>`_, `\<footnote_reference>`_, `\<problematic>`_, `\<reference>`_, `\<target>`_, and `\<title>`_ elements (via the `%refid.att`_ and `%reference.atts`_ parameter entities). ``refname`` =========== Attribute 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). ``refuri`` ========== Attribute 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). ``rowsep`` ========== Attribute 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. ``rtrim`` ========= Attribute type: `%yesorno`_. Default value: none (implies no). The ``rtrim`` attribute is used in the `\<substitution_definition>`_ element. ``scale`` ========== Attribute type: `%number`_. Default value: none. The ``scale`` attribute is used in the `\<image>`_ element to store a uniform scaling factor (integer percentage value). ``source`` ========== Attribute type: `CDATA`_. Default value: none. The ``source`` attribute stores the path, URI, or a description of the source that was used to produce the document tree. 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. ``start`` ========= Attribute 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. ``stub`` ========= Attribute 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. ``suffix`` ========== Attribute 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. .. _title attribute: ``title`` ========= Attribute type: `CDATA`_. Default value: none. The ``title`` attribute is used in the `\<document>`_ element to store the document's *metadata title*. The attribute is set by the `"title" directive`_ or the `DocTitle transform`_. It is typically not part of the rendered document but, for example, used as `HTML <title> element`_ and shown in a browser's title bar, a user's history or bookmarks, or search results. Its value may may differ from the *displayed title* which is stored in a `\<title>`_ element. .. _HTML <title> element: https://html.spec.whatwg.org/multipage/semantics.html#the-title-element ``type`` ========= Attribute 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). ``uri`` ======= Attribute 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`_ [#]_. [rfc3986]_ Docutils applies the `"root_prefix"`_ configuration setting when a URI Reference starting with "/" is converted to a local filesystem path. .. [#] Examples are a full URI, an *absolute-path reference* (begins with a single slash character) or a *relative-path reference* (does not begin with a slash character). .. _URI reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1 ``valign`` ========== | Attribute type: `EnumeratedType`_ (top|middle|bottom). | Default 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. ``width`` ========== Attribute type: `%measure`_. Default value: none. The ``width`` attribute is used in the `\<figure>`_, `\<image>`_, and `\<table>`_ elements. ``xml:space`` ============= | Attribute type: `EnumeratedType`_, one of "default" or "preserve". | Default 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 entities: ---------------------------- Parameter Entity Reference ---------------------------- `Parameter entities <https://www.w3.org/TR/REC-xml/#dt-PE>`__ 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. .. contents:: :local: In addition, the `Docutils Generic` DTD defines parameter entities for `custom attribute types`_. Attribute Entities ================== ``%align-h.att`` ---------------- The ``%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.att`` ----------------- The ``%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.att`` ------------------ The ``%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.att`` ------------- The ``%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.att`` ----------------- The ``%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.atts`` --------------- The ``%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: .. parsed-literal:: 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. ``%bodyatt`` ------------ The ``%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.att`` ------------------- The ``%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.atts`` ------------------- The ``%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: .. parsed-literal:: `%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.att`` -------------- The ``%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.att`` ---------------- The ``%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.att`` --------------- The ``%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.att`` -------------------- The ``%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.att`` ------------------ The ``%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.att`` ---------------- The ``%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.att`` ------------------ The ``%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.att`` ------------------ The ``%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.att`` ------------------- The ``%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.att`` ------------------ The ``%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.elements`` --------------------------- The ``%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.elements`` ------------------ The ``%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.elements`` -------------------- The ``%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.elements`` --------------------- The ``%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 ============== %calstblx --------- .. _Exchange Table Model: The `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: .. parsed-literal:: ( ( `%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, .. parsed-literal:: ( ( (`%body.elements`_; | topic | sidebar)+, transition? )*, ( (`%section.elements`_;), (transition?, (`%section.elements`_;) )* )? ) because there are additional restrictions on `\<transition>`_\ s. [#extra-rule]_ The ``%structure.model`` parameter entity is directly employed in the content models of the `\<document>`_ and `\<section>`_ elements. .. [#extra-rule] The restrictions cannot be fully expressed in the language of DTDs without making the definition overly complicated. Docutils checks them in the `misc.Transitions` transform_. ``%tbl.entry.mdl`` ------------------- The ``%tbl.entry.mdl`` parameter entity is defined in the `Exchange Table Model`_ to allow customization of the `\<entry>`_ element's content model. The `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: .. parsed-literal:: (#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>`_ .. _%additional.basic.atts: .. _%additional.bibliographic.elements: .. _%additional.body.elements: .. _%additional.inline.elements: .. _%additional.reference.atts: .. _%additional.section.elements: Placeholders ============ The following empty placeholders are employed to allow easy extension of the corresponding parameter entity by wrapper DTDs: | ``%additional.basic.atts`` in `%basic.atts`_, | ``%additional.bibliographic.elements`` in `%bibliographic.elements`_, | ``%additional.body.elements`` in `%body.elements`_, | ``%additional.inline.elements`` in `%inline.elements`_, | ``%additional.reference.atts`` in `%reference.atts`_, and | ``%additional.section.elements`` in `%section.elements`_. -------- Glossary -------- .. class:: description _`Class names` define 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`_. _`Identifiers` 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`_) [#id-vc]_. 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). .. [#id-vc] The `Docutils Generic DTD`_ cannot use the ID, IDREF, and IDREFS standard types because elements do not adhere to the `One ID per Element Type`_ validity constraint. __ https://www.w3.org/TR/html401/types.html#type-name __ https://html.spec.whatwg.org/multipage/dom.html #global-attributes:the-id-attribute-2 __ https://www.w3.org/TR/html-polyglot/#id-attribute __ https://tex.stackexchange.com/questions/18311/ what-are-the-valid-names-as-labels __ https://help.libreoffice.org/6.3/en-US/text/swriter/01/04040000.html ?DbPAR=WRITER#bm_id4974211 __ `XML attribute types`_ _`Phrasing content` is text data that may be intermixed with `inline elements`_ (cf. the `%text.model`_ parameter entity). _`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

`_, `\`_, `\`_ :Docutils class: ``nodes.Structural`` :Parameter Entities: `%structure.model`_ directly or indirectly includes all structural elements. Structural Subelements ---------------------- 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). .. class:: narrow run-in :Category members: .. class:: narrow run-in :empty: `\`_, `\`_ :simple: `\`_, `\<subtitle>`_ :compound: `\<decoration>`_, `\<docinfo>`_ :Docutils class: ``nodes.SubStructural`` Decorative Elements ------------------- Decorative elements are used to generate page headers and footers. They are child elements of `\<decoration>`_ and contain `body elements`_. .. class:: field-indent-11em :Category members: `\<footer>`_, `\<header>`_ :Docutils class: ``nodes.Decorative`` Bibliographic Elements ---------------------- Bibliographic 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). .. class:: narrow run-in :Category members: .. class:: narrow run-in :simple: `\<address>`_, `\<author>`_, `\<contact>`_, `\<copyright>`_, `\<date>`_, `\<organization>`_, `\<revision>`_, `\<status>`_, `\<version>`_ :compound: `\<authors>`_, `\<field>`_ :Docutils class: ``nodes.Bibliographic`` :Parameter entity: `%bibliographic.elements`_ Body Elements ------------- 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. .. class:: narrow run-in :Category members: .. class:: narrow run-in :empty: `\<image>`_ , `\<pending>`_, `\<target>`_ :simple: `\<comment>`_, `\<doctest_block>`_, `\<literal_block>`_, `\<math_block>`_, `\<paragraph>`_, `\<raw>`_, `\<reference>`_, `\<rubric>`_, `\<substitution_definition>`_ :compound: `\<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>`_ :Docutils class: ``nodes.Body`` :Parameter Entities: `%body.elements`_ directly includes all body elements, `%structure.model`_ indirectly includes all body elements. Body Subelements ---------------- 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`_. .. class:: narrow run-in :Category members: .. class:: narrow run-in :empty: `\<colspec>`_ :simple: `\<attribution>`_, `\<caption>`_, `\<classifier>`_, `\<field_name>`_, `\<label>`_, `\<line>`_, `\<option_argument>`_, `\<option_string>`_, `\<term>`_, `\<title>`_ :compound: `\<definition>`_, `\<definition_list_item>`_, `\<description>`_, `\<entry>`_, `\<field>`_, `\<field_body>`_, `\<legend>`_, `\<list_item>`_, `\<option>`_, `\<option_group>`_, `\<option_list_item>`_, `\<row>`_, `\<tbody>`_, `\<tgroup>`_, `\<thead>`_ :Docutils class: ``nodes.Part`` Inline Elements --------------- 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. .. class:: narrow run-in :Category members: `\<abbreviation>`_, `\<acronym>`_, `\<citation_reference>`_, `\<emphasis>`_, `\<footnote_reference>`_, `\<generated>`_, `\<image>`_, `\<inline>`_, `\<literal>`_, `\<math>`_, `\<problematic>`_, `\<raw>`_, `\<reference>`_, `\<strong>`_, `\<subscript>`_, `\<substitution_reference>`_, `\<superscript>`_, `\<target>`_, `\<title_reference>`_ :Docutils class: ``nodes.Inline`` :Parameter Entities: `%inline.elements`_ directly includes all inline elements, `%text.model`_ indirectly includes all inline elements. ------------------- Element Reference ------------------- .. contents:: :local: :depth: 1 Introduction ============ 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): :Category: One or more references to the element categories in the `Element Hierarchy`_ above. Some elements belong to more than one category. :Analogues: Analogous elements in well-known document models such as `HTML` [html.spec]_ or `DocBook` [tdg5.1]_. Describes similarities and differences. :Processing: Formatting or rendering recommendations for the element. :Parents: Elements which may contain the element. :Children: Elements which may occur within the element. Optionally followed by the formal XML content model from the `Docutils Generic DTD`_. :Attributes: XML Attributes that are defined for this element. :Parameter Entities: `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. <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. :Category: `Inline Elements`_ :Analogues: <abbreviation> is analogous to the DocBook_ <abbrev> element. The HTML_ <abbr> element is used for both, abbreviations and acronyms. :Processing: May be used to semantically mark the presence of an abbreviation in the text for styling or scripting purposes. Writers_ may ignore the element and just render its contents. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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). :Category: `Inline Elements`_ :Analogues: <acronym> is analogous to the DocBook_ <acronym> element. The HTML_ <abbr> element is used for both, abbreviations and acronyms. :Processing: May be used to semantically mark the presence of an acronym in the text for styling or scripting purposes. Writers_ may ignore the element and just render its contents. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <address> is analogous to the DocBook_ <address> element. :Processing: As with the `\<literal_block>`_ element, newlines are significant and must be preserved. However, a monospaced typeface should not be used. :Parents: `\<docinfo>`_, `\<authors>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: 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. Examples -------- In 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. :Category: `Compound Body Elements`_ :Analogues: The generic <admonition> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. The specific admonitions `\<caution>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_ are analogous to the respective DocBook_ elements. :Processing: Rendered distinctly (inset and/or in a box, etc.). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: <admonition> elements begin with a `\<title>`_ and may contain one or more `body elements`_. :Attributes: only the `common attributes`_. See also the _`specific admonition elements` `\<attention>`_ `\<caution>`_, `\<danger>`_, `\<error>`_, `\<hint>`_, `\<important>`_, `\<note>`_, `\<tip>`_, and `\<warning>`_. Examples -------- The 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. :Category: `Compound Body Elements`_ :Analogues: <attention> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Attention!" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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>`_. :Category: `Body Subelements`_ (simple) :Analogues: <attribution> is analogous to the DocBook_ <attribution> element. :Processing: Placed below the block quote, usually be preceded by a dash, right aligned, or otherwise set apart from the quotation. :Parent: `\<block_quote>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. The Docutils HTML and LaTeX writers provide the `"attribution"`_ setting to configure the formatting of the `\<attribution>`_. Examples -------- See `\<block_quote>`_. <author> ======== The <author> element holds the name of the author (or one of the authors) of the document. :Category: `Bibliographic Elements`_ :Analogues: <author> is analogous to the DocBook_ <personname> element. :Processing: see `\<docinfo>`_ :Parents: `\<docinfo>`_, `\<authors>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <authors> is analogous to the DocBook_ <authorgroup> element. :Processing: See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: `\<author>`_, `\<organization>`_, `\<address>`_, `\<contact>`_:: ((author, organization?, address?, contact?)+) :Attributes: only the `common attributes`_. Examples -------- 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). :Category: `Compound Body Elements`_ :Analogues: <block_quote> is analogous to the <blockquote> element in both HTML_ and DocBook_. :Processing: <block_quote> elements serve to set their contents off from the main text, typically with indentation and/or other decoration. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: `body elements`_ followed by an optional `\<attribution>`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <bullet_list> is analogous to the HTML_ <ul> element [#]_ and to the DocBook_ <itemizedlist> element. :Processing: Each list item should begin a new vertical block, prefaced by a bullet/dingbat. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<list_item>`_ elements :Attributes: the `common attributes`_ and bullet_. .. [#] 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. Examples -------- 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>`_. [#]_ :Category: `Body Subelements`_ (simple) :Analogues: The <caption> element is analogous to the DocBook_ <title> element (but specific to a `\<figure>`_). The HTML_ <figcaption> element combines <caption> and `\<legend>`_. :Processing: Placed above, below, or besides the image it describes. Often preceded by a figure number. May be repeated in a generated "list of figures". :Parent: `\<figure>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- See `\<figure>`_. .. [#] The title/caption of a `\<table>`_ is represented by a `\<title>`_ element. <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`_. :Category: `Compound Body Elements`_ :Analogues: <caution> is analogous to the `DocBook \<caution>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Caution" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <citation> is analogous to the DocBook_ <bibliomixed> element. [#]_ 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". :Processing: Formatted as entry in a bibliography or similar to a `\<footnote>`_. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: <citation> elements begin with a `\<label>`_ and contain `body elements`_:: (label, (%body.elements;)+) :Attributes: the `common attributes`_ and backrefs_. .. [#] The DocBook_ <citation> element resembles a `\<citation_reference>`_. Example ------- See `\<citation_reference>`_. <citation_reference> ==================== The <citation_reference> element represents a cross reference to a `\<citation>`_. :Category: `Inline Elements`_ :Analogues: 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. :Processing: Typically enclosed in square brackets. :Parents: all elements employing `%text.model`_ in their content models :Children: only text data :Attributes: refid_, refname_, and the `common attributes`_. Example ------- 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. :Category: `Body Subelements`_ (simple) :Analogues: <classifier> has no direct analogues in common DTDs. It can be emulated with primitives or type effects. :Processing: see `\<definition_list_item>`_ :Parent: `\<definition_list_item>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (empty) :Analogues: <colspec> is analogous to the DocBook_ <colspec> element. The HTML_ <col> element is related but has different semantics. :Processing: See `colspec`__ in the `Exchange Table Model`. :Parent: `\<tgroup>`_ :Children: none (empty) :Attributes: The `Exchange Table Model` defines the attributes align_, char_, charoff_, colname_, colnum_, colsep_, colwidth_, and rowsep_. [#]_ Via the `%tbl.colspec.att`_ parameter entity, <colspec> also accepts the `common attributes`_ and `stub`_. .. [#] Docutils ignores all attributes except colwidth_. __ https://www.oasis-open.org/specs/tm9901.html#AEN446 Examples -------- See `\<table>`_. <comment> ========= The <comment> element is used for explanatory notes that should not be visible in the document rendering. :Category: `Simple Body Elements`_ :Analogues: While most markup languages provide a syntax for comments, the <comment> element has no direct analogues in HTML or DocBook. :Processing: Included as comment or skipped in translations to other markup languages. [#]_ Hidden from the document rendering. :Parents: all elements employing `%body.elements`_, `%structure.model`_, or `%text.model`_ in their content models :Children: only text data :Attributes: the `common attributes`_ and `xml:space`_. Examples -------- In reStructuredText, a comment_ block [#]_ is started by two full stops. No processing is done on the content but beware of a misinterpretation as `explicit markup construct`_:: .. This is a *comment*. .. [This] is a *citation*. .. [This] is another *comment*. Pseudo-XML_ fragment from simple parsing:: <comment xml:space="preserve"> This is a *comment*. <citation ids="this" names="this"> <label> This <paragraph> is a <emphasis> citation . <comment xml:space="preserve"> [This] is another *comment*. .. [#] In Docutils, the `"strip_comments"`_ configuration setting triggers the removal of comment elements from the document tree. .. [#] There is no syntax for inline comments in reStructuredText. <compound> ========== The <compound> element combines multiple `body elements`_ to a single logical paragraph. :Category: `Compound Body Elements`_ :Analogues: The <compound> element has no direct analogues in common DTDs. In HTML, it can be emulated with <div> and CSS styling. [#]_ :Processing: Typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity (cf. the `"compound" directive`_). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. .. [#] The Docutils counterpart to HTML’s <div> is the `\<container>`_ element. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <contact> is analogous to the DocBook_ <email> element. The HTML_ <address> element serves a similar purpose. :Processing: See `\<docinfo>`_. :Parents: `\<docinfo>`_, `\<authors>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: The <container> element is analogous to the HTML_ <div> element or the SVG <g> element. :Processing: Can be used for styling or scripting purposes. An example is a frame or background colour based on the value of the classes_ attribute. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <copyright> is analogous to the DocBook_ <copyright> element. :Processing: see `\<docinfo>`_ :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <danger> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "!DANGER!" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Bibliographic Elements`_ :Analogues: <date> is analogous to the DocBook_ <date> element. :Processing: Often used with the RCS/CVS keyword "Date". See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Structural Subelements`_ :Analogues: There are no direct analogies to <decoration> in HTML or DocBook. :Processing: See the individual `decorative elements`_. :Parent: `\<document>`_ :Children: The `decorative elements`_ `\<header>`_ and/or `\<footer>`_. Although the content model doesn't specifically require contents, no empty <decoration> elements are ever created. :Attributes: only the `common attributes`_. Examples -------- See `\<header>`_ and `\<footer>`_. <definition> ============ The <definition> element is a container for the body elements used to define a `\<term>`_ in a `\<definition_list>`_. :Category: `Body Subelements`_ (compound) :Analogues: <definition> is analogous to the HTML_ <dd> element and to the DocBook_ <listitem> element (inside a <variablelistentry> element). :Processing: see `\<definition_list_item>`_ :Parent: `\<definition_list_item>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <definition_list> is analogous to the HTML_ <dl> element and to the DocBook_ <variablelist> element. :Processing: see `\<definition_list_item>`_ :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<definition_list_item>`_ elements :Attributes: only the `common attributes`_. See also `\<field_list>`_. Examples -------- A 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>`_. :Category: `Body Subelements`_ (compound) :Analogues: <definition_list_item> is analogous to the DocBook_ <variablelistentry> element. :Processing: The optional `\<classifier>`_\ s can be rendered differently from the `\<term>`_. They should be separated visually, typically by spaces plus a colon or dash. :Parent: `\<definition_list>`_ :Children: <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. :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Body Subelements`_ (compound) :Analogues: <description> has no direct analogues in common DTDs. :Processing: see `\<option_list>`_ :Parent: `\<option_list_item>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Structural Subelements`_ :Analogues: There are no directly analogous HTML or DocBook elements. The DocBook_ <info> element is related but ususally suppressed in the output. :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`_. :Parent: `\<document>`_ :Children: `bibliographic elements`_ :Attributes: only the `common attributes`_. See also the `\<meta>`_ element (for hidden meta-data). Examples -------- `Bibliographic data`_ is represented in reStructuredText by a `field list <rST field list_>`__ as the first visible element of a `document <rST document_>`__ (after optional document title and subtitle). The field list is transformed into a <docinfo> element and its children by the `DocInfo transform`_. [#abstract-dedication]_ 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`_. .. [#abstract-dedication] Exceptions are the fields "abstract" and "dedication" that are transformed to `\<topic>`_ elements adjacent to the <docinfo>. <doctest_block> =============== The <doctest_block> element is a Python-specific variant of a `\<literal_block>`_. :Category: `Simple Body Elements`_ :Analogues: <doctest_block> is analogous to the HTML_ <pre> element and 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. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: the `common attributes`_ and `xml:space`_. Examples -------- 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. :Category: `Root Element`_ :Analogues: <document> is analogous to the HTML_ <html> element and to several DocBook_ elements such as <book>. :Parents: The <document> element has no parents. :Children: `structural elements`_, `structural subelements`_, and `body elements`_ .. parsed-literal:: ( (title, subtitle?)?, meta*, decoration?, (docinfo, transition?)?, `%structure.model`_; ) See the `%structure.model`_ parameter entity for details of the body of a <document>. :Attributes: the `common attributes`_ and title_. <document> is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document. Depending on the source of the data and the stage of processing, the <document> may not initially contain a `\<title>`_. A document title is not directly representable in reStructuredText_. Instead, the `DocTitle transform`_ may promote a lone top-level section title to become the document `\<title>`_, and similarly a lone second-level (sub)section's title to become the document `\<subtitle>`_. The contents of "`\<decoration>`_" may be specified in a document, constructed programmatically, or both. The "`\<docinfo>`_" may be transformed from an initial `\<field_list>`_. Examples -------- A 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*. :Category: `Inline Elements`_ :Analogues: <emphasis> is analogous to the HTML_ <em> element and the DocBook_ <emphasis> element. :Processing: Typically displayed in italic type. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (compound) :Analogues: <entry> is analogous to the DocBook_ <entry> element. HTML_ differentiates between header entries <th> and data entries <td>. :Processing: 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. :Parents: `\<thead>`_, `\<tbody>`_ :Children: `body elements`_ (via the `%tbl.entry.mdl`_ parameter entity) :Attributes: The <entry> element accepts the colname_, namest_, nameend_, morerows_, colsep_, rowsep_, align_, char_, charoff_, and valign_ attributes (ignored by Docutils) and (via the `%tbl.entry.att`_ parameter entity) the `common attributes`_ and morecols_. __ https://www.oasis-open.org/specs/tm9901.html#AEN827 Examples -------- See `\<table>`_. <enumerated_list> ================= The <enumerated_list> element contains `\<list_item>`_ elements which are uniformly marked with enumerator labels. :Category: `Compound Body Elements`_ :Analogues: <enumerated_list> is analogous to the HTML_ <ol> element and to the DocBook_ <orderedlist> element. :Processing: Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1."). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<list_item>`_ elements :Attributes: enumtype_, prefix_, suffix_, start_, and the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <error> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Error" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Body Subelements`_ (compound), `Bibliographic Elements`_ :Analogues: <field> has no direct analogues in common DTDs. HTML_ uses <div> elements inside <dl> lists for grouping <dt>/<dd> pairs. :Processing: See `\<field_list>`_. :Parents: `\<docinfo>`_, `\<field_list>`_ :Children: one `\<field_name>`_ and one `\<field_body>`_ element :Attributes: only the `common attributes`_. Examples -------- See the examples for the `\<field_list>`_ and `\<docinfo>`_ elements. <field_body> ============ The <field_body> element is analogous to a database field's data. :Category: `Body Subelements`_ (compound) :Analogues: <field_body> is analogous to the HTML_ <dd> element. :Processing: see `\<field_list>`_ :Parent: `\<field>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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). :Category: `Compound Body Elements`_ :Analogues: <field_list> is analogue to the HTML_ <dl> element. :Processing: A <field_list> is typically rendered as a two-column list, 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. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<field>`_ elements :Attributes: 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. Examples -------- A reStructuredText `field list <rST 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. :Category: `Body Subelements`_ (simple) :Analogues: <field_name> is analogous to the HTML_ <dt> element. :Processing: See `\<field_list>`_. :Parent: `\<field>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- See the examples for the `\<field_list>`_ and `\<docinfo>`_ elements. <figure> ======== The <figure> element groups an `\<image>`_ with a `\<caption>`_ and/or `\<legend>`_. :Category: `Compound Body Elements`_ :Analogues: 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). :Processing: On paged media, figures may float to a different position if this helps the page layout. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: `\<image>`_ or `\<reference>`_ (with nested <image>) followed by `\<caption>`_ or `\<legend>`_ or both. :Attributes: align_ (via `%align-h.att`_) , width_, and the `common attributes`_. Examples -------- 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. <footer> ======== The <footer> element is a container element whose contents are meant to appear at the bottom of a web page, or repeated at the bottom of every printed page. :Category: `Decorative Elements`_ :Analogues: <footer> is analogous to the HTML_ <footer> element. There are no direct analogies to <footer> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. :Parent: `\<decoration>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. The <footer> element may contain processing information (datestamp, a link to Docutils_, etc.) as well as custom content. Examples -------- A document may get a <footer> decoration even without use of the reStructuredText `"footer" directive`_:: A paragraph. Complete pseudo-XML_ result after parsing and applying transforms_, assuming that the ``--date`` command-line option or `"datestamp"`_ configuration setting has been supplied:: <document> <decoration> <footer> <paragraph> Generated on: 2002-08-20. <paragraph> A paragraph. <footnote> ========== The <footnote> element is used for labelled notes_ that provide additional context to a passage of text (*footnotes* or *endnotes*). The corresponding footnote mark in running text is set by the `\<footnote_reference>`_ element. .. _notes: https://en.wikipedia.org/wiki/Note_(typography) :Category: `Compound Body Elements`_ :Analogues: <footnote> has no direct analogues in DocBook or HTML. The `DocBook \<footnote>`_ element combines features of <footnote> and `\<footnote_reference>`_. The HTML standard lists suggestions to `emulate footnotes`_. The `DPub ARIA`_ role "doc-footnote" may be used to mark a `conforming HTML emulation`_ (for collections of notes that occur at the end of a section, "doc-endnotes" is more appropriate). The corresponding types in the `EPUB 3 Structural Semantics Vocabulary`_ are "footnote" and "endnote". :Processing: A <footnote> element should be set off from the rest of the document, e.g. with a border or using a smaller font size. Footnotes may "float" to the bottom or margin of a page or a dedicated section. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: <footnote> elements begin with an optional [#]_ `\<label>`_ and contain `body elements`_:: (label?, (%body.elements;)+) :Attributes: the `common attributes`_ plus auto_ and backrefs_. .. [#] The footnote label will become mandatory in Docutils 1.0. Examples -------- reStructuredText uses `explicit markup blocks`_ for `footnotes`_:: .. [1] This is a footnote. Pseudo-XML_ fragment from simple parsing:: <footnote ids="id1" names="1"> <label> 1 <paragraph> This is a footnote. <footnote_reference> ==================== The <footnote_reference> element is an inline element representing a cross reference to a `\<footnote>`_ (a footnote mark). :Category: `Inline Elements`_ :Analogues: The <footnote_reference> element resembles the `DocBook \<footnoteref>`_ element or the LaTeX ``\footnotemark`` command. There is no equivalent in HTML. The <a> element can be used to provide a link to the corresponding footnote. :Processing: A <footnote_reference> should generate a mark matching the `\<label>`_ of the referenced footnote. The mark is typically formatted as superscript or enclosed in square brackets. :Parents: all elements employing `%text.model`_ in their content models :Children: only text data :Attributes: auto_, refid_, refname_, and the `common attributes`_. Examples -------- A reStructuredText `footnote reference`_ and footnote_:: [#]_ is an auto-numbered footnote reference. .. [#] First auto-numbered footnote. Pseudo-XML_ fragment from simple parsing:: <paragraph> <footnote_reference auto="1" ids="id1"> is an auto-numbered footnote reference. <footnote auto="1" ids="id3"> <paragraph> First auto-numbered footnote. The ``references.Footnotes`` Docutils transform_ resolves this to:: <paragraph> <footnote_reference auto="1" ids="id1" refid="id2"> 1 is an auto-numbered footnote reference. <footnote auto="1" backrefs="id1" ids="id2" names="1"> <label> 1 <paragraph> First auto-numbered footnote. <generated> =========== The <generated> element represents text that is not present in the document source but inserted by the processing system. :Category: `Inline Elements`_ :Analogues: There are no analogies to <generated> in HTML_ or DocBook_. :Processing: No special handling required. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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 <header> ======== The <header> element is a container element whose contents are meant to appear at the top of a web page, or at the top of every printed page. :Category: `Decorative Elements`_ :Analogues: <header> is analogous to the HTML_ <header> element. There are no direct analogies to <header> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system. :Parent: `\<decoration>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- A reStructuredText `"header" directive`_:: .. header:: This space for rent. Pseudo-XML_ fragment from simple parsing:: <document> <decoration> <header> <paragraph> This space for rent. <hint> ====== The <hint> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <hint> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Hint" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Categories: `Body Elements`_, `Inline Elements`_ :Analogues: <image> is analogous to the `HTML \<img>`_, `DocBook \<imagedata>`_, and `SVG \<image>`_ elements. :Processing: The specified image is included into the output document. Depending on the output format, this is done by referring to the image URI or by embedding the image data. :Parents: all elements employing `%body.elements`_, `%text.model`_, or `%structure.model`_ in their content models :Children: none (empty) :Attributes: uri_, alt_, align_, height_, width_, scale_, loading_, and the `common attributes`_. It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX engine, HTML browser, ...). The `reStructuredText Directives` documentation contains a non exhaustive `table of compatible image formats`_. Examples -------- A 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"> .. _HTML <img>: https://html.spec.whatwg.org/multipage/embedded-content.html #the-img-element .. _SVG <image>: https://svgwg.org/svg2-draft/embedded.html#ImageElement <important> =========== The <important> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <important> is analogous to the `DocBook \<important>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Important" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Inline Elements`_ :Analogues: <inline> is analogous to the HTML_ <span> element and the DocBook_ <phrase> element. :Processing: 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. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- `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>`_. :Category: `Body Subelements`_ (simple) :Analogues: 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. :Processing: Rendered prominently, as first token of the footnote or citation. Often enclosed in square brackets. :Parents: `\<footnote>`_, `\<citation>`_ :Children: only text data :Attributes: only the `common attributes`_. Examples -------- 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>`_. :Category: `Body Subelements`_ (compound) :Analogues: The <legend> element is analogous to the DocBook_ <caption> element (but specific to a `\<figure>`_). The HTML_ <figcaption> element combines `\<caption>`_ and <legend>. :Processing: Formatted as a displayed block. :Parent: `\<figure>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- See `\<figure>`_. <line> ====== The <line> element contains a single line of text, part of a `\<line_block>`_. :Category: `Body Subelements`_ (simple) :Analogues: <line> has no direct analogues in common DTDs. It can be emulated with primitives or type effects. :Processing: See `\<line_block>`_. :Parent: `\<line_block>`_ :Children: text data plus `inline elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <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. :Processing: Each <line> should begin a new vertical block, without markers or additional spacing. Nested <line_blocks> should be indented. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: `\<line>`_, <line_block> :Attributes: only the `common attributes`_. See `\<literal_block>`_ for an alternative useful for program listings and interactive computer sessions. Examples -------- A 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. :Category: `Body Subelements`_ (compound) :Analogues: <list_item> is analogous to the HTML_ <li> element and to the DocBook_ <listitem> element. :Processing: See `\<bullet_list>`_ or `\<enumerated_list>`_. :Parents: `\<bullet_list>`_, `\<enumerated_list>`_ :Children: `body elements`_ :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Inline Elements`_ :Analogues: <literal> is analogous to the DocBook_ <literal> element. HTML_ uses the specific elements <code>, <kbd>, and <samp> for code, input, and output. :Processing: Typically rendered in a monospace font. Preservation of line breaks and sequences of whitespace characters is not guaranteed. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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 ------- :Category: `Simple Body Elements`_ :Analogues: <literal_block> is analogous to the HTML_ <pre> element and to the DocBook_ <programlisting> and <screen> elements. :Processing: <literal_block> elements are typically rendered in a monospaced typeface. It is crucial that all whitespace and line breaks are preserved in the rendered form. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: 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. Examples -------- A 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` [#latex-math]_ that is typeset as mathematical notation (inline formula). :Category: `Inline Elements`_ :Analogues: <math> is related to the <math> element in MathML and HTML. However, it contains text data only. :Processing: Rendered as mathematical notation. If the output format does not support math typesetting, the content may be inserted verbatim. :Parents: all elements employing `%text.model`_ in their content models :Children: only text data :Attributes: only the `common attributes`_. Example ------- 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 . .. [#latex-math] For details of the supported mathematical language, see the `"math" directive`_ <math_block> ============ The <math_block> element contains a block of text in `LaTeX math format` [#latex-math]_ that is typeset as mathematical notation (display formula). :Category: `Simple Body Elements`_ :Analogues: <math_block> is analogous to a HTML/MathML <math> element displayed as block-level element or a LaTeX ``equation*`` environment. :Processing: 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. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: only text data :Attributes: the `common attributes`_ and `xml:space`_. Example ------- 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). :Category: `Structural Subelements`_ :Analogues: <meta> is analogous to the `HTML <meta> element`_ or the file properties in ODT or PDF documents. :Processing: 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). :Parent: `\<document>`_ :Children: none (empty) :Attributes: the attributes *content*, *dir*, *http-equiv*, *lang*, *media*, name_, and *scheme* that correspond to the respective attributes of the `HTML <meta> element`_. See also the `\<docinfo>`_ element for displayed meta-data. The document's `title attribute`_ stores the metadata document title. Example ------- A 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"> .. _HTML <meta> element: https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element <note> ====== The <note> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <note> is analogous to the `DocBook \<note>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Note" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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. :Category: `Body Subelements`_ (compound) :Analogues: <option> has no direct analogues in common DTDs. :Processing: See `\<option_list>`_. :Parent: `\<option_group>`_ :Children: <option> elements start with an `\<option_string>`_ and may contain `\<option_argument>`_ elements:: (option_string, option_argument*) :Attributes: only the `common attributes`_. Note that reStructuredText_ currently supports only one argument per option. Examples -------- See the examples for the `\<option_list>`_ element. <option_argument> ================= The <option_argument> element contains placeholder text for option arguments. :Category: `Body Subelements`_ (simple) :Analogues: <option_argument> has no direct analogues in common DTDs. :Processing: 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. :Parent: `\<option>`_ :Children: only text data :Attributes: the `common attributes`_ and delimiter_. Examples -------- See the examples for the `\<option_list>`_ element. <option_group> ============== The <option_group> element groups together one or more `\<option>`_ elements, all synonyms. :Category: `Body Subelements`_ (compound) :Analogues: <option_group> has no direct analogues in common DTDs. :Processing: Typically `\<option>`_ elements within an <option_group> are joined together in a comma-separated list. :Parent: `\<option_list_item>`_ :Children: one or more `\<option>`_ elements :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <option_list> has no direct analogues in common DTDs. It can be emulated with primitives such as tables. :Processing: An <option_list> is typically rendered as a two-column list, where the first column contains option strings and arguments, and the second column contains descriptions. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `\<option_list_item>`_ elements :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Body Subelements`_ (compound) :Analogues: <option_list_item> has no direct analogues in common DTDs. :Processing: see `\<option_list>`_ :Parent: `\<option_list>`_ :Children: one `\<option_group>`_ and one `\<description>`_ :Attributes: only the `common attributes`_. Examples -------- See the examples for the `\<option_list>`_ element. <option_string> =============== The <option_string> element contains the text of a command-line option. :Category: `Body Subelements`_ (simple) :Analogues: <option_string> has no direct analogues in common DTDs. :Processing: The <option_string> text is typically rendered in a monospaced typeface. :Parent: `\<option>`_ :Children: only text data :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Bibliographic Elements`_ :Analogues: <organization> is analogous to the <orgname>, <corpname>, or <publishername> DocBook_ elements. :Processing: See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Simple Body Elements`_ :Analogues: <paragraph> is analogous to the HTML_ <p> element and to the DocBook_ <para> element. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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_. :Category: `Body Elements`_ (empty) :Analogues: <pending> has no direct analogues in common DTDs. :Processing: Usually replaced or removed by the associated transform_. Writers may ignore remaining <pending> elements. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: none (empty) :Attributes: only the `common attributes`_. Example ------- 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. :Category: `Inline Elements`_ :Analogues: <problematic> has no direct analogues in common DTDs. :Processing: Typically displayed in red colour. If the refid_ attribute is present, the element should point to the referenced element. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: the `common attributes`_ and refid_. Examples -------- 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. :Category: `Simple Body Elements`_, `Inline Elements`_ :Analogues: The <raw> element has no direct analogues in common DTDs. :Processing: Passed untouched to the Writer_. The interpretation is up to the Writer. A Writer may ignore <raw> elements not matching its format_. :Parents: all elements employing `%body.elements`_, `%structure.model`_, or `%text.model`_ in their content models :Children: only text data :Attributes: format_, `xml:space`_ and the `common attributes`_. Examples -------- The reStructuredText `"raw" directive`_ [#]_ 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> .. [#] For raw data pass-through in inline context, use `custom interpreted text roles`_ derived from the `"raw" role`_. <reference> =========== The <reference> element represents a cross reference to another element of the document or to an external ressource. :Category: `Simple Body Elements`_, `Inline Elements`_ :Analogues: The <reference> element is analogous to the DocBook_ <link> element and the HTML_ <a> (anchor) element. :Processing: 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 [#]_, or rendered in some other way. :Parents: all elements employing `%body.elements`_, `%text.model`_, or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: anonymous_, name_ (deprecated), refid_, refname_, refuri_, and the `common attributes`_. .. [#] See the `"target-notes" directive`_. Examples -------- 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 <rst/directives.html#target>`__ 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>`_. :Category: `Bibliographic Elements`_ :Analogues: <revision> is similar to (but simpler than) the DocBook_ <revision> element. It closely matches the DocBook_ <revnumber> element, but in a simpler context. :Processing: Often used with the RCS/CVS keyword "Revision". See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (compound) :Analogues: <row> is analogous to the HTML_ <tr> element and the DocBook_ <row> element. :Processing: Render content as a table row. See row__ in the `Exchange Table Model` for details. :Parents: `\<thead>`_, `\<tbody>`_ :Children: one or more `\<entry>`_ elements :Attributes: The <row> element may contain the rowsep_ and valign_ attributes (ignored by Docutils) and (via the `%tbl.row.att`_ parameter entity) the `common attributes`_. __ https://www.oasis-open.org/specs/tm9901.html#AEN741 Examples -------- See `\<table>`_. <rubric> ======== A <rubric> is an informal heading outside the document's section structure. :Category: `Simple Body Elements`_ :Analogues: <rubric> has no direct analogues in common DTDs. It shares some features with the <bridgehead> DocBook_ element. :Processing: Rendered similar to a section heading, traditionally highlighted in red (hence the name). Rubrics are not (auto)numbered and not included in the document's table of contents. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Example ------- The reStructuredText `"rubric" directive`_ can be used to get a heading at places where a section is not allowed:: .. sidebar:: Sidebar Title This is a sidebar. It is for text outside the flow of the main text. .. rubric:: A heading inside a sidebar Sections are not supported in a sidebar. A rubric can be used to structure the content instead. Pseudo-XML_ fragment from simple parsing:: <sidebar> <title> Sidebar Title <paragraph> This is a sidebar. It is for text outside the flow of the main text. <rubric> A heading inside a sidebar <paragraph> Sections are not supported in a sidebar. A rubric can be used to structure the content instead. <section> ========= The <section> element is the main unit of hierarchy for Docutils documents. .. class:: run-in :Category: `Structural Elements`_ :Analogues: <section> is analogous to the <section> elements in HTML_ and DocBook_. :Parents: `\<document>`_, `\<section>`_ :Children: <section> elements begin with a `\<title>`_, followed by an optional `\<subtitle>`_. They may contain `structural elements`_, `body elements`_, and `\<transition>`_ elements: .. parsed-literal:: (title, subtitle?, `%structure.model`_;) :Attributes: only the `common attributes`_ :Parameter Entities: `%section.elements`_ directly includes <section>, `%structure.model`_ indirectly includes <section>. The Docutils document model uses a simple, recursive model for section structure. A `\<document>`_ element may contain <section> elements. Sections in turn may contain other <section> elements, without limit. The level (depth) of a section element is determined from its physical nesting level. Paragraphs and other `body elements`_ may occur before a <section>, but not after it. Examples -------- reStructuredText 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. <sidebar> ========= Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. Their content is outside of the flow of the document's main text. .. class:: run-in :Category: `Structural Elements`_ :Analogues: <sidebar> is analogous to the DocBook_ <sidebar> element and the HTML_ <aside> element. :Processing: A <sidebar> element should be set off from the rest of the document somehow, typically with a border. Sidebars typically "float" to the side of the page and the document's main text flows around them. :Parents: `\<document>`_, `\<section>`_. :Children: <sidebar> elements begin with optional `\<title>`_ and `\<subtitle>`_ and contain `body elements`_ and `\<topic>`_ elements. There must not be a <subtitle> without title. :: ((title, subtitle?)?, (%body.elements; | topic)+) :Attributes: only the `common attributes`_ :Parameter Entities: `%structure.model`_ directly includes <sidebar>. The <sidebar> element is a non-recursive `\<section>`_-like construct. <sidebar> elements cannot nest inside body elements, so you can't have a <sidebar> inside a `\<table>`_ or a list, or inside another <sidebar> or `\<topic>`_. Examples -------- A reStructuredText `"sidebar" directive`_:: .. sidebar:: Optional Title :subtitle: If Desired Body. Pseudo-XML_ fragment from simple parsing:: <sidebar> <title> Optional Title <subtitle> If Desired <paragraph> Body. <status> ======== The <status> element contains a status statement for the document, such as "Draft", "Final", "Work In Progress", etc. :Category: `Bibliographic Elements`_ :Analogues: <status> is analogous to the DocBook_ <status> element. :Processing: See `\<docinfo>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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**. :Category: `Inline Elements`_ :Analogues: <strong> is analogous to the HTML_ <strong> element. :Processing: Typically displayed in boldface. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Inline Elements`_ :Analogues: <subscript> is analogous to the HTML_ <sub> element and the DocBook_ <subscript> element. :Processing: Typically rendered with a lowered baseline using smaller text. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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 content that shall replace matching `\<substitution_reference>`_ elements. :Category: `Simple Body Elements`_ :Analogues: Substitution definitions are analog to XML’s `internal entities`_ or programming language macros. :Processing: A <substitution_definition> is not directly rendered. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: ltrim_, rtrim_, and the `common attributes`_. The names_ attribute uses the "substitution" namespace_. Examples -------- A reStructuredText `substitution definition`_ allows to include complex inline structures within text while keeping the details out of the text flow:: The chemical formula for water is |H2O|. .. |H2O| replace:: H\ :sub:`2`\ O Pseudo-XML_ fragment from simple parsing:: <paragraph> The chemical formula for water is <substitution_reference refname="H2O"> H2O . <substitution_definition names="H2O"> H <subscript> 2 O The `references.Substitutions` transform_ replaces the `\<substitution_reference>`_ with the content of the <substitution_definition>:: <paragraph> The chemical formula for water is H <subscript> 2 O . <substitution_definition names="H2O"> H <subscript> 2 O A substitution definition can also supply an `\<image>`_ for inline use:: The |biohazard| symbol must be used on medical waste containers. .. |biohazard| image:: biohazard.png Pseudo-XML_ fragment from simple parsing:: <paragraph> The <substitution_reference refname="biohazard"> biohazard symbol must be used on medical waste containers. <substitution_definition names="biohazard"> <image alt="biohazard" uri="biohazard.png"> After running the `references.Substitutions` transform_, we get:: <paragraph> The <image alt="biohazard" uri="biohazard.png"> symbol must be used on medical waste containers. <substitution_definition names="biohazard"> <image alt="biohazard" uri="biohazard.png"> For more usage examples, see `Substitution Definitions`_ in the `reStructuredText Markup Specification`_. <substitution_reference> ======================== The <substitution_reference> element is a placeholder for the content of the matching <substitution_definition>. :Category: `Inline Elements`_ :Analogues: A <substitution_reference> is analogue to an XML `entity reference`_. :Processing: Replaced by the content of a matching `\<substitution_definition>`_. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: the `common attributes`_ plus refname_. The refname_ attribute uses the "substitution" namespace_. Examples -------- See `\<substitution_definition>`_. <subtitle> ========== The <subtitle> element stores the subtitle of a `\<document>`_, `\<section>`_, or `\<sidebar>`_. :Category: `Structural Subelements`_ :Analogues: <subtitle> is analogous to the DocBook_ <subtitle> element. In HTML, subtitles are represented by a <p> element inside a <hgroup_> element. :Processing: A document's subtitle is usually rendered smaller than its `\<title>`_. :Parents: `\<document>`_, `\<section>`_, and `\<sidebar>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. .. _hgroup: https://html.spec.whatwg.org/multipage/sections.html #the-hgroup-element <superscript> ============= The <superscript> element is an inline element representing text which should be displayed as superscript. :Category: `Inline Elements`_ :Analogues: <superscript> is analogous to the HTML_ <sup> element and the DocBook_ <superscript> element. :Processing: Typically rendered with a raised baseline using smaller text. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <system_message> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. :Processing: Rendered similar to an `\<admonition>`_, with the generated title "System Message", its type_/level_ and, if available, source_ and line_. :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: backrefs_, level_, line_, type_, and the `common attributes`_. In Docutils, system messages with a level lower than the `"report_level"`_ setting are removed by the `universal.FilterMessages` transform_. Examples -------- An 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`_. :Category: `Compound Body Elements`_ :Analogues: <table> is analogous to the <table> element in HTML_ and DocBook_. :Processing: Content is arranged in rows and columns forming a grid. See table__ in the `Exchange Table Model` for details. :Parents: `\<document>`_, `\<section>`_ and all `body elements`_ :Children: <table> elements begin with an optional `\<title>`_ (caption) and may contain one or more `\<tgroup>`_ elements:: (title?, tgroup+) :Attributes: 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_. __ https://www.oasis-open.org/specs/tm9901.html#AEN142 Examples -------- In reStructuredText, tables can be specified via the `"table" <"table" directive_>`__, `"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> ======== The <target> element provides an end-point for a hypertext `\<reference>`_. :Category: Empty `Body Elements`_, `Inline Elements`_ [#inline-targets]_ :Analogues: As body element, <target> is similar to the DocBook_ <anchor> element. An inline <target> can be represented by a DocBook <phrase> or HTML_ <span> element. :Processing: <target> elements with refid_, refname_, or refuri_ attribute (indirect targets) act as a relay for links to one of the target's ids_ or names_. A <target> without refid_, refname_, or refuri_ attributes provides ids_ or names_ for its content or, if empty, the next element. :Parents: all elements employing `%body.elements`_, `%structure.model`_, or `%text.model`_ in their content models :Children: only text data [#target-content]_ :Attributes: anonymous_, refid_, refname_, refuri_, and the `common attributes`_. .. [#inline-targets] Inline <target> elements will be deprecated in Docutils 1.0 and invalid in Docutils 2.0. The "rst" parser will use `\<inline>`_ elements for inline targets. .. [#target-content] <target> elements with content will be deprecated in Docutils 1.0 and invalid in Docutils 2.0. Examples -------- In reStructuredText, `hyperlink targets`_ are indicated by a leading underscore:: .. _inline: `inline target`_ .. _example: https//:example.org .. _alias: .. _explicit target: The hyperlink target above points to this paragraph with an _`inline target`. Pseudo-XML_ fragment from simple parsing:: <target ids="inline" names="inline" refname="inline target"> <target ids="example" names="example" refuri="https//:example.org"> <target ids="alias" names="alias"> <target ids="explicit-target" names="explicit\ target"> <paragraph> The hyperlink target above points to this paragraph with an <target ids="inline-target" names="inline\ target"> inline target . After applying transforms_, the paragraph has two reference names and two IDs, transferred from the preceding targets:: <target ids="inline" names="inline" refid="inline-target"> <target ids="example" names="example" refuri="https//:example.org"> <target refid="alias"> <target refid="explicit-target"> <paragraph ids="explicit-target alias" names="explicit\ target alias"> The hyperlink target above points to this paragraph with an <target ids="inline-target" names="inline\ target"> inline target . For more examples, see `\<reference>`_. <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`_. :Category: `Body Subelements`_ (compound) :Analogues: <tbody> is analogous to the <tbody> element in HTML_ and DocBook_. :Processing: Render content as table body. :Parent: `\<tgroup>`_ :Children: one or more `\<row>`_ elements :Attributes: valign_ (ignored by Docutils) and the `common attributes`_ (via the `%tbl.tbody.att`_ parameter entity). Examples -------- See `\<table>`_. <term> ====== The <term> element contains a word or phrase being defined in a `\<definition_list>`_. :Category: `Body Subelements`_ (simple) :Analogues: <term> is analogous to the HTML_ <dt> element and to the DocBook_ <term> element. :Processing: see `\<definition_list_item>`_ :Parent: `\<definition_list_item>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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`_. :Category: `Body Subelements`_ (compound) :Analogues: <tgroup> is analogous to the DocBook_ <tgroup> element. There is no corresponding HTML element (the <colgroup> element has a different purpose and semantics). :Processing: See tgroup__ in the `Exchange Table Model`. :Parent: `\<table>`_ :Children: One or more `\<colspec>`_ elements, followed by an optional `\<thead>`_ and a `\<tbody>`_ (cf. the `%tbl.tgroup.mdl`_ parameter entity). The number of <colspec>s, must not exceed the value of the cols_ attribute. Docutils expects one <colspec> per column. :Attributes: The <tgroup> element must contain a cols_ attribute and may contain colsep_, rowsep_, and align_ (ignored by Docutils). Via the `%tbl.tgroup.att`_ parameter entity, <tgroup> supports the `common attributes`_. __ https://www.oasis-open.org/specs/tm9901.html#AEN282 Tables usually consist of a single <tgroup>. Complex tables with widely varying column specifications may be easier to code using multiple <tgroup>s. However, this is not supported by `table markup in reStructuredText <rST tables_>`__ and Docutils table handling routines. Examples -------- See `\<table>`_. <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`_. :Category: `Body Subelements`_ (compound) :Analogues: <thead> is analogous to the <thead> element in HTML_ and DocBook_. :Processing: 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. :Parent: `\<tgroup>`_ :Children: one or more `\<row>`_ elements :Attributes: the valign_ attribute (ignored by Docutils) and (via the `%tbl.thead.att`_ parameter entity) the `common attributes`_. Examples -------- See `\<table>`_. <tip> ===== The <tip> element is a specific *admonition*, a distinctive and self-contained notice. :Category: `Compound Body Elements`_ :Analogues: <tip> is analogous to the `DocBook \<tip>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Tip" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A 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>`_. :Category: `Structural Subelements`_, `Body Subelements`_ (simple) :Analogues: <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). :Parents: `\<admonition>`_, `\<document>`_, `\<section>`_, `\<sidebar>`_, `\<table>`_, and `\<topic>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: 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`_. Examples -------- Section_ 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. :Category: `Inline Elements`_ :Analogues: <title_reference> is analogous to the HTML_ <cite> element and the DocBook_ <citetitle> element. :Processing: Typically displayed in italic type. :Parents: all elements employing `%text.model`_ in their content models :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. .. class:: run-in :Category: `Structural Elements`_ :Analogues: <topic> is analogous to the HTML_ <aside> element. The DocBook_ <simplesect> element is similar, but you cannot place `body elements`_ after a <simplesect>. :Processing: A <topic> element should be set off from the rest of the document somehow, such as with indentation or a border. In contrast to a `\<sidebar>`_, it should not float. :Parents: `\<document>`_, `\<section>`_, and `\<sidebar>`_ :Children: <topic> elements may begin with a `\<title>`_ and contain `body elements`_:: (title?, (%body.elements;)+) :Attributes: only the `common attributes`_ :Parameter Entities: `%structure.model`_ directly includes <topic>. Topics are terminal, "leaf" mini-sections, like block quotes with titles, or textual figures. A <topic> is just like a `\<section>`_, except that 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`_. Examples -------- A 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. .. class:: run-in :Category: `Structural Subelements`_ :Analogues: <transition> is analogous to the HTML_ <hr> element. :Processing: 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 or a vignette with vertical space above and below. :Parents: `\<document>`_, `\<section>`_ (cf. `%structure.model`_) :Children: none (empty) :Attributes: only the `common attributes`_ :Parameter Entities: The `%structure.model`_ directly includes <transition>. The document model sets additional restrictions on the placement of <transitions>: [#extra-rule]_ * A transition may not be immediately adjacent to another transition, i.e., <transition> elements must be separated by other elements. * A transition may not start the text of a document or section, i.e., a <transition> is invalid as first child or preceded by only `\<title>`_, `\<subtitle>`_, or invisible elements [#invisible-or-moving]_. * A transition may not occur at the end of a document or section. [#]_ In other words, a <transition> is invalid as last child element or followed by only invisible elements [#invisible-or-moving]_. See also `Doctree Representation of Transitions`__ in `A Record of reStructuredText Syntax Alternatives`__. .. [#invisible-or-moving] The elements `\<meta>`_, `\<pending>`_, `\<substitution_definition>`_, and `\<target>`_ are not visible in the output document. The `\<decoration>`_ element contains `\<header>`_ and `\<footer>`_ which move to the respective places. .. [#] In reStructuredText markup, a transition may appear to fall at the end of a section immediately before another section. The `misc.Transitions` transform_ recognizes this case and moves the transition so it separates the sections. __ ../dev/rst/alternatives.html#doctree-representation-of-transitions __ ../dev/rst/alternatives.html Examples -------- A 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>`_. :Category: `Bibliographic Elements`_ :Analogues: <version> may be considered analogous to the <revision>, <revnumber>, or <biblioid> DocBook_ elements. :Processing: Sometimes used with the RCS/CVS keyword "Revision". See `\<docinfo>`_ and `\<revision>`_. :Parent: `\<docinfo>`_ :Children: text data plus `inline elements`_ (`%text.model`_) :Attributes: only the `common attributes`_. Examples -------- 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. :Category: `Compound Body Elements`_ :Analogues: <warning> is analogous to the `DocBook \<warning>`_ element. :Processing: Rendered distinctly (inset and/or in a box, etc.), with the generated title "Warning" (or similar). :Parents: all elements employing `%body.elements`_ or `%structure.model`_ in their content models :Children: one or more `body elements`_ :Attributes: only the `common attributes`_. See also the generic `\<admonition>`_ and the other `specific admonition elements`_. Examples -------- A reStructuredText `"warning" directive`_:: .. WARNING:: Reader discretion is strongly advised. Pseudo-XML_ fragment from simple parsing:: <warning> <paragraph> Reader discretion is strongly advised. --------------- Attribute Types --------------- .. contents:: :local: Standard Attribute Types ======================== *Standard attribute types* are defined in the `attribute types <XML attribute types_>`__ section of the `XML 1.0 specification` [xml1.0]_. _`CDATA` Character data. CDATA attributes may contain arbitrary text. _`NMTOKEN` A "name token". One or more of letters, digits, ".", "-", and "_". _`NMTOKENS` One or more space-separated NMTOKEN_ values. _`EnumeratedType` The attribute value may be one of a specified list of values. Custom Attribute Types ====================== 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. _`%classnames.type` | Space-separated list of `class names`_. Resolves to NMTOKEN_. | Used in the `classes`_ attribute. Python data type: ``list[str]``. _`%idref.type` | A reference to another element by one of its identifiers_. Resolves to NMTOKEN_. [#id-vc]_ | Used in the `refid`_ attribute. Python data type: ``str``. .. _identifier: identifiers_ _`%idrefs.type` | Space separated list of references to other elements by their identifiers_. Resolves to NMTOKENS_. [#id-vc]_ | Used in the `backrefs`_ attribute. Python data type: ``list[str]``. _`%ids.type` | A space-separated list of unique `identifiers`_. Resolves to NMTOKENS_. [#id-vc]_ | Used in the `ids`_ attribute. Python data type: ``list[str]``. _`%measure` | 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 documentation`__ for details). Resolves to CDATA_. | Used in the `height`_ and `width`_ attributes. Python data type: ``str``. __ ../index.html#writer-specific _`%number` | The attribute value must be a positive interger. Resolves to NMTOKEN_. | Used in the level_, morecols_, morerows_, scale_, and start_ attributes. Python data type: ``int``. _`%refname.type` | A `reference name`_. Resolves to CDATA_. | Used in the `refname`_ attribute. Python data type: ``str``. _`%refnames.type` | Space-separated list of `reference names`_. (Backslash escaping is used for space characters inside a `reference name`.) Resolves to CDATA_. | Used in the `names`_ and `dupnames`_ attributes. Python data type: ``list[str]``. _`%yesorno` | Boolean: False if zero ("0"), true for any other value. Resolves to NMTOKEN_. | Used in the anonymous_, colsep_, ltrim_, rtrim_, rowsep_, and `stub`_ attributes. Python data type: ``bool``. Common Attributes ================= Through the `%basic.atts`_ parameter entity, all elements except `\<meta>`_ support the attributes ids_, names_ or dupnames_, source_, and classes_. --------------------- Attribute Reference --------------------- .. contents:: :local: :depth: 1 ``alt`` ======= Attribute type: `CDATA`_. Default value: none. The ``alt`` attribute is used to store a text description in the `\<image>`_ element. ``align`` ========= Attribute 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. ``anonymous`` ============= Attribute 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). ``auto`` ======== Attribute 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_). ``backrefs`` ============ Attribute 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). ``bullet`` ========== Attribute 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. ``classes`` =========== Attribute 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. ``char`` ======== Attribute 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. ``charoff`` =========== Attribute 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. ``colname`` =========== Attribute 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. ``colnum`` =========== Attribute 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. ``cols`` ========= Attribute 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`__). __ http://www.oasis-open.org/html/tm9901.html#AEN350 ``colsep`` ========== Attribute 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. ``colwidth`` ============ Attribute 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. __ https://www.oasis-open.org/specs/tm9901.html#AEN530 __ ../../RELEASE-NOTES.html#document-tree-docutils-dtd ``delimiter`` ============= Attribute 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 " "). ``dupnames`` ============ Attribute 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. ``enumtype`` ============ Attribute 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. Supported values: .. class:: field-indent-8em :arabic: 1, 2, 3, ... :loweralpha: a, b, c, ..., z :upperalpha: A, B, C, ..., Z :lowerroman: i, ii, iii, iv, ..., mmmmcmxcix [4999] :upperroman: I, II, III, IV, ..., MMMMCMXCIX [4999] ``format`` ========== 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. ``frame`` ========= | Attribute type: EnumeratedType_ (top|bottom|topbot|all|sides|none). | Default 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. ``height`` ========== Attribute type: `%measure`_. Default value: none. The ``height`` attribute is used in the `\<image>`_ element. ``ids`` ======= Attribute 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. An XPath_ expression to select the element with identifier `test` is :: //*[contains(concat(' ', @ids, ' '), ' test ')] (similar to `selecting an element by CSS class`__). .. TODO: * Use 'id' for primary identifier key? * Keep additional keys in `ids` or in the preceding target elements? __ https://stackoverflow.com/questions/1604471/how-can-i-find-an-element-by-css-class-with-xpath ``level`` ========= Attribute 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. ``line`` ========= Attribute 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. ``ltrim`` ========= Attribute type: `%yesorno`_. Default value: none (implies no). The ``ltrim`` attribute is used in the `\<substitution_definition>`_ element. ``loading`` =========== Attribute 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_. [#]_ The default depends on the writer and the `"image_loading"`_ configuration setting. New in Docutils 0.21 .. [#] Currently only recognized by the HTML5 writer. The ODF/ODT writer always embeds images in the output document, XML and LaTeX writers link to the image. The behaviour may change for the ODT and XML writers (images cannot be embedded in a LaTeX source). ``morecols`` ============ Attribute 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. ``morerows`` ============ Attribute 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`__). __ http://www.oasis-open.org/html/tm9901.html#AEN997 ``name`` ========= Attribute 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. ``names`` ========= Attribute 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. .. _reference name removal: Each reference name must be unique in its namespace_; if there are name conflicts (two or more elements want to use the same name), the affected name will be transferred to the `dupnames`_ attribute on the duplicate element(s). The element can no longer be used as hyperlink target. [#]_ An element may have both ``names`` and ``dupnames`` attributes, if the ``dupnames`` are from conflicting `implicit hyperlink targets`_ and the ``names`` from `explicit hyperlink targets`_ or a directive's `name option`_. .. [#] See `Implicit Hyperlink Targets`_ for details of conflict resolution. ``namest`` ========== Attribute 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. ``nameend`` =========== Attribute 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. ``pgwide`` ========== Attribute 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. ``prefix`` ========== Attribute 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. ``refid`` ========= Attribute type: `%idref.type`_. Default value: none. The ``refid`` attribute contains a reference to another element via one of its `identifiers`_. It is used by the `\<citation_reference>`_, `\<footnote_reference>`_, `\<problematic>`_, `\<reference>`_, `\<target>`_, and `\<title>`_ elements (via the `%refid.att`_ and `%reference.atts`_ parameter entities). ``refname`` =========== Attribute 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). ``refuri`` ========== Attribute 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). ``rowsep`` ========== Attribute 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. ``rtrim`` ========= Attribute type: `%yesorno`_. Default value: none (implies no). The ``rtrim`` attribute is used in the `\<substitution_definition>`_ element. ``scale`` ========== Attribute type: `%number`_. Default value: none. The ``scale`` attribute is used in the `\<image>`_ element to store a uniform scaling factor (integer percentage value). ``source`` ========== Attribute type: `CDATA`_. Default value: none. The ``source`` attribute stores the path, URI, or a description of the source that was used to produce the document tree. 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. ``start`` ========= Attribute 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. ``stub`` ========= Attribute 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. ``suffix`` ========== Attribute 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. .. _title attribute: ``title`` ========= Attribute type: `CDATA`_. Default value: none. The ``title`` attribute is used in the `\<document>`_ element to store the document's *metadata title*. The attribute is set by the `"title" directive`_ or the `DocTitle transform`_. It is typically not part of the rendered document but, for example, used as `HTML <title> element`_ and shown in a browser's title bar, a user's history or bookmarks, or search results. Its value may may differ from the *displayed title* which is stored in a `\<title>`_ element. .. _HTML <title> element: https://html.spec.whatwg.org/multipage/semantics.html#the-title-element ``type`` ========= Attribute 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). ``uri`` ======= Attribute 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`_ [#]_. [rfc3986]_ Docutils applies the `"root_prefix"`_ configuration setting when a URI Reference starting with "/" is converted to a local filesystem path. .. [#] Examples are a full URI, an *absolute-path reference* (begins with a single slash character) or a *relative-path reference* (does not begin with a slash character). .. _URI reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1 ``valign`` ========== | Attribute type: `EnumeratedType`_ (top|middle|bottom). | Default 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. ``width`` ========== Attribute type: `%measure`_. Default value: none. The ``width`` attribute is used in the `\<figure>`_, `\<image>`_, and `\<table>`_ elements. ``xml:space`` ============= | Attribute type: `EnumeratedType`_, one of "default" or "preserve". | Default 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 entities: ---------------------------- Parameter Entity Reference ---------------------------- `Parameter entities <https://www.w3.org/TR/REC-xml/#dt-PE>`__ 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. .. contents:: :local: In addition, the `Docutils Generic` DTD defines parameter entities for `custom attribute types`_. Attribute Entities ================== ``%align-h.att`` ---------------- The ``%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.att`` ----------------- The ``%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.att`` ------------------ The ``%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.att`` ------------- The ``%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.att`` ----------------- The ``%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.atts`` --------------- The ``%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: .. parsed-literal:: 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. ``%bodyatt`` ------------ The ``%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.att`` ------------------- The ``%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.atts`` ------------------- The ``%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: .. parsed-literal:: `%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.att`` -------------- The ``%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.att`` ---------------- The ``%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.att`` --------------- The ``%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.att`` -------------------- The ``%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.att`` ------------------ The ``%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.att`` ---------------- The ``%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.att`` ------------------ The ``%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.att`` ------------------ The ``%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.att`` ------------------- The ``%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.att`` ------------------ The ``%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.elements`` --------------------------- The ``%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.elements`` ------------------ The ``%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.elements`` -------------------- The ``%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.elements`` --------------------- The ``%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 ============== %calstblx --------- .. _Exchange Table Model: The `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: .. parsed-literal:: ( ( `%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, .. parsed-literal:: ( ( (`%body.elements`_; | topic | sidebar)+, transition? )*, ( (`%section.elements`_;), (transition?, (`%section.elements`_;) )* )? ) because there are additional restrictions on `\<transition>`_\ s. [#extra-rule]_ The ``%structure.model`` parameter entity is directly employed in the content models of the `\<document>`_ and `\<section>`_ elements. .. [#extra-rule] The restrictions cannot be fully expressed in the language of DTDs without making the definition overly complicated. Docutils checks them in the `misc.Transitions` transform_. ``%tbl.entry.mdl`` ------------------- The ``%tbl.entry.mdl`` parameter entity is defined in the `Exchange Table Model`_ to allow customization of the `\<entry>`_ element's content model. The `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: .. parsed-literal:: (#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>`_ .. _%additional.basic.atts: .. _%additional.bibliographic.elements: .. _%additional.body.elements: .. _%additional.inline.elements: .. _%additional.reference.atts: .. _%additional.section.elements: Placeholders ============ The following empty placeholders are employed to allow easy extension of the corresponding parameter entity by wrapper DTDs: | ``%additional.basic.atts`` in `%basic.atts`_, | ``%additional.bibliographic.elements`` in `%bibliographic.elements`_, | ``%additional.body.elements`` in `%body.elements`_, | ``%additional.inline.elements`` in `%inline.elements`_, | ``%additional.reference.atts`` in `%reference.atts`_, and | ``%additional.section.elements`` in `%section.elements`_. -------- Glossary -------- .. class:: description _`Class names` define 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`_. _`Identifiers` 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`_) [#id-vc]_. 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). .. [#id-vc] The `Docutils Generic DTD`_ cannot use the ID, IDREF, and IDREFS standard types because elements do not adhere to the `One ID per Element Type`_ validity constraint. __ https://www.w3.org/TR/html401/types.html#type-name __ https://html.spec.whatwg.org/multipage/dom.html #global-attributes:the-id-attribute-2 __ https://www.w3.org/TR/html-polyglot/#id-attribute __ https://tex.stackexchange.com/questions/18311/ what-are-the-valid-names-as-labels __ https://help.libreoffice.org/6.3/en-US/text/swriter/01/04040000.html ?DbPAR=WRITER#bm_id4974211 __ `XML attribute types`_ _`Phrasing content` is text data that may be intermixed with `inline elements`_ (cf. the `%text.model`_ parameter entity). _`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 A paragraph.