1 ============================
2 The Docutils Document Tree
3 ============================
5 A Guide to the Docutils DTD
6 ***************************
9 :Contact: docutils-develop@lists.sourceforge.net
12 :Copyright: This document has been placed in the public domain.
15 .. contents:: :depth: 1
18 This document describes the XML data structure of Docutils_ documents:
19 the relationships and semantics of elements and attributes. The
20 Docutils document structure is formally defined by the `Docutils
21 Generic DTD`_ XML document type definition, docutils.dtd_, which is
22 the definitive source for details of element structural relationships.
24 This document does not discuss implementation details. Those can be
25 found in internal documentation (docstrings) for the
26 ``docutils.nodes`` module, where the document tree data structure is
27 implemented in a class library.
29 The reader is assumed to have some familiarity with XML or SGML, and
30 an understanding of the data structure meaning of "tree". For a list
31 of introductory articles, see `Introducing the Extensible Markup
34 The reStructuredText_ markup is used for illustrative examples
35 throughout this document. For a gentle introduction, see `A
36 ReStructuredText Primer`_. For complete technical details, see the
37 `reStructuredText Markup Specification`_.
40 .. _Docutils: http://docutils.sourceforge.net/
41 .. _Docutils Generic DTD:
43 .. _docutils.dtd: docutils.dtd
44 .. _Introducing the Extensible Markup Language (XML):
45 http://xml.coverpages.org/xmlIntro.html
46 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
47 .. _A ReStructuredText Primer: ../user/rst/quickstart.html
48 .. _reStructuredText Markup Specification: rst/restructuredtext.html
57 Below is a simplified diagram of the hierarchy of elements in the
58 Docutils document tree structure. An element may contain any other
59 elements immediately below it in the diagram. Notes are written in
60 square brackets. Element types in parentheses indicate recursive or
61 one-to-many relationships; sections may contain (sub)sections, tables
62 contain further body elements, etc. ::
64 +--------------------------------------------------------------------+
65 | document [may begin with a title, subtitle, decoration, docinfo] |
66 | +--------------------------------------+
67 | | sections [each begins with a title] |
68 +-----------------------------+-------------------------+------------+
69 | [body elements:] | (sections) |
70 | | - literal | - lists | | - hyperlink +------------+
71 | | blocks | - tables | | targets |
72 | para- | - doctest | - block | foot- | - sub. defs |
73 | graphs | blocks | quotes | notes | - comments |
74 +---------+-----------+----------+-------+--------------+
75 | [text]+ | [text] | (body elements) | [text] |
76 | (inline +-----------+------------------+--------------+
80 The Docutils document model uses a simple, recursive model for section
81 structure. A document_ node may contain body elements and section_
82 elements. Sections in turn may contain body elements and sections.
83 The level (depth) of a section element is determined from its physical
84 nesting level; unlike other document models (``<h1>`` in HTML_,
85 ``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not
86 incorporated into the element name.
88 The Docutils document model uses strict element content models. Every
89 element has a unique structure and semantics, but elements may be
90 classified into general categories (below). Only elements which are
91 meant to directly contain text data have a mixed content model, where
92 text data and inline elements may be intermixed. This is unlike the
93 much looser HTML_ document model, where paragraphs and text data may
94 occur at the same level.
100 Structural elements may only contain child elements; they do not
101 directly contain text data. Structural elements may contain body
102 elements or further structural elements. Structural elements can only
103 be child elements of other structural elements.
105 Category members: document_, section_, topic_, sidebar_
108 Structural Subelements
109 ----------------------
111 Structural subelements are child elements of structural elements.
112 Simple structuctural subelements (title_, subtitle_) contain text
113 data; the others are compound and do not directly contain text data.
115 Category members: title_, subtitle_, decoration_, docinfo_,
119 Bibliographic Elements
120 ``````````````````````
122 The docinfo_ element is an optional child of document_. It groups
123 bibliographic elements together. All bibliographic elements except
124 authors_ and field_ contain text data. authors_ contains further
125 bibliographic elements (most notably author_). field_ contains
126 field_name_ and field_body_ body subelements.
128 Category members: address_, author_, authors_, contact_, copyright_,
129 date_, field_, organization_, revision_, status_, version_
135 The decoration_ element is also an optional child of document_. It
136 groups together elements used to generate page headers and footers.
138 Category members: footer_, header_
144 Body elements are contained within structural elements and compound
145 body elements. There are two subcategories of body elements: simple
148 Category members: admonition_, attention_, block_quote_, bullet_list_,
149 caution_, citation_, comment_, compound_, container_, danger_,
150 definition_list_, doctest_block_, enumerated_list_, error_,
151 field_list_, figure_, footnote_, hint_, image_, important_,
152 line_block_, literal_block_, note_, option_list_, paragraph_,
153 pending_, raw_, rubric_, substitution_definition_, system_message_,
154 table_, target_, tip_, warning_
160 Simple body elements are empty or directly contain text data. Those
161 that contain text data may also contain inline elements. Such
162 elements therefore have a "mixed content model".
164 Category members: comment_, doctest_block_, image_, literal_block_,
165 math_block_, paragraph_, pending_, raw_, rubric_, substitution_definition_,
169 Compound Body Elements
170 ----------------------
172 Compound body elements contain local substructure (body subelements)
173 and further body elements. They do not directly contain text data.
175 Category members: admonition_, attention_, block_quote_, bullet_list_,
176 caution_, citation_, compound_, container_, danger_, definition_list_,
177 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
178 important_, line_block, note_, option_list_, system_message_, table_,
185 Compound body elements contain specific subelements (e.g. bullet_list_
186 contains list_item_). Subelements may themselves be compound elements
187 (containing further child elements, like field_) or simple data
188 elements (containing text data, like field_name_). These subelements
189 always occur within specific parent elements, never at the body
190 element level (beside paragraphs, etc.).
192 Category members (simple): attribution_, caption_, classifier_,
193 colspec_, field_name_, label_, line_, option_argument_,
194 option_string_, term_
196 Category members (compound): definition_, definition_list_item_,
197 description_, entry_, field_, field_body_, legend_, list_item_,
198 option_, option_group_, option_list_item_, row_, tbody_, tgroup_,
205 Inline elements directly contain text data, and may also contain
206 further inline elements. Inline elements are contained within simple
207 body elements. Most inline elements have a "mixed content model".
209 Category members: abbreviation_, acronym_, citation_reference_,
210 emphasis_, footnote_reference_, generated_, image_, inline_, literal_,
211 math_, problematic_, reference_, strong_, subscript_,
212 substitution_reference_, superscript_, target_, title_reference_, raw_
215 .. _HTML: http://www.w3.org/MarkUp/
216 .. _DocBook: http://docbook.org/tdg/en/html/docbook.html
217 .. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm
224 .. contents:: :local:
227 Each element in the DTD (document type definition) is described in its
228 own section below. Each section contains an introduction plus the
229 following subsections:
231 * Details (of element relationships and semantics):
233 - Category: One or more references to the element categories in
234 `Element Hierarchy`_ above. Some elements belong to more than one
237 - Parents: A list of elements which may contain the element.
239 - Children: A list of elements which may occur within the element.
241 - Analogues: Describes analogous elements in well-known document
242 models such as HTML_ or DocBook_. Lists similarities and
245 - Processing: Lists formatting or rendering recommendations for the
250 The formal XML content model from the `Docutils DTD`_, followed by:
252 - Attributes: Describes (or refers to descriptions of) the possible
253 values and semantics of each attribute.
255 - Parameter Entities: Lists the parameter entities which directly or
256 indirectly include the element.
258 * Examples: reStructuredText_ examples are shown along with
259 fragments of the document trees resulting from parsing.
260 _`Pseudo-XML` is used for the results of parsing and processing.
261 Pseudo-XML is a representation of XML where nesting is indicated by
262 indentation and end-tags are not shown. Some of the precision of
263 real XML is given up in exchange for easier readability. For
264 example, the following are equivalent:
269 <section ids="a-title" names="a title">
270 <title>A Title</title>
271 <paragraph>A paragraph.</paragraph>
278 <section ids="a-title" names="a title">
286 Many of the element reference sections below are marked "_`to be
287 completed`". Please help complete this document by contributing to
294 The ``abbreviation`` element is an inline element used to represent an
295 abbreviation being used in the document. An example of an abbreviation is 'St'
296 being used instead of 'Street'.
305 All elements employing the %inline.elements; parameter entities in their
306 content models may contain ``abbreviation``.
309 ``abbreviation`` elements may contain text data plus `inline elements`_.
312 ``abbreviation`` is analogous to the HTML "abbr" element.
322 The ``abbreviation`` element contains only the `common attributes`_:
323 ids_, names_, dupnames_, source_, and classes_.
328 The ``abbreviation`` element is not exposed in default restructured text. It
329 can only be accessed through custom roles.
331 Pseudo-XML_ example from a custom `:abbr:` role::
334 <abbreviation explanation="Street">
336 is a common abbreviation for "street".
348 The ``address`` element holds the surface mailing address information
349 for the author (individual or group) of the document, or a third-party
350 contact address. Its structure is identical to that of the
351 literal_block_ element: whitespace is significant, especially
359 `Bibliographic Elements`_
362 The following elements may contain ``address``: docinfo_, authors_
365 ``address`` elements contain text data plus `inline elements`_.
368 ``address`` is analogous to the DocBook "address" element.
371 As with the literal_block_ element, newlines and other whitespace
372 is significant and must be preserved. However, a monospaced
373 typeface need not be used.
386 The ``address`` element contains the `common attributes`_ (ids_,
387 names_, dupnames_, source_, and classes_), plus `xml:space`_.
390 The `%bibliographic.elements;`_ parameter entity directly includes
397 reStructuredText_ source::
402 :Address: 123 Example Ave.
405 Complete pseudo-XML_ result after parsing and applying transforms::
407 <document ids="document-title" names="document title">
415 See docinfo_ for a more complete example, including processing
422 This element is a generic, titled admonition. Also see the specific
423 admonition elements Docutils offers (in alphabetical order): caution_,
424 danger_, error_, hint_, important_, note_, tip_, warning_.
431 `Compound Body Elements`_
434 All elements employing the `%body.elements;`_ or
435 `%structure.model;`_ parameter entities in their content models
436 may contain ``admonition``.
439 ``admonition`` elements begin with a title_ and may contain one or
440 more `body elements`_.
443 ``admonition`` has no direct analogues in common DTDs. It can be
444 emulated with primitives and type effects.
447 Rendered distinctly (inset and/or in a box, etc.).
455 (title_, (`%body.elements;`_)+)
458 The ``admonition`` element contains only the `common attributes`_:
459 ids_, names_, dupnames_, source_, and classes_.
462 The `%body.elements;`_ parameter entity directly includes
463 ``admonition``. The `%structure.model;`_ parameter entity
464 indirectly includes ``admonition``.
470 reStructuredText source::
472 .. admonition:: And, by the way...
474 You can make up your own admonition too.
476 Pseudo-XML_ fragment from simple parsing::
478 <admonition class="admonition-and-by-the-way">
482 You can make up your own admonition too.
488 The ``attention`` element is an admonition, a distinctive and
489 self-contained notice. Also see the other admonition elements
490 Docutils offers (in alphabetical order): caution_, danger_, error_,
491 hint_, important_, note_, tip_, warning_, and the generic admonition_.
498 `Compound Body Elements`_
501 All elements employing the `%body.elements;`_ or
502 `%structure.model;`_ parameter entities in their content models
503 may contain ``attention``.
506 ``attention`` elements contain one or more `body elements`_.
509 ``attention`` has no direct analogues in common DTDs. It can be
510 emulated with primitives and type effects.
513 Rendered distinctly (inset and/or in a box, etc.), with the
514 generated title "Attention!" (or similar).
522 (`%body.elements;`_)+
525 The ``attention`` element contains only the `common attributes`_:
526 ids_, names_, dupnames_, source_, and classes_.
529 The `%body.elements;`_ parameter entity directly includes
530 ``attention``. The `%structure.model;`_ parameter entity
531 indirectly includes ``attention``.
537 reStructuredText source::
539 .. Attention:: All your base are belong to us.
541 Pseudo-XML_ fragment from simple parsing::
545 All your base are belong to us.
557 The ``author`` element holds the name of the author of the document.
564 `Bibliographic Elements`_
567 The following elements may contain ``author``: docinfo_, authors_
570 ``author`` elements may contain text data plus `inline elements`_.
573 ``author`` is analogous to the DocBook "author" element.
587 The ``author`` element contains only the `common attributes`_:
588 ids_, names_, dupnames_, source_, and classes_.
591 The `%bibliographic.elements;`_ parameter entity directly includes
598 reStructuredText_ source::
603 :Author: J. Random Hacker
605 Complete pseudo-XML_ result after parsing and applying transforms::
607 <document ids="document-title" names="document title">
614 See docinfo_ for a more complete example, including processing
621 The ``authors`` element is a container for author information for
622 documents with multiple authors.
629 `Bibliographic Elements`_
632 Only the docinfo_ element contains ``authors``.
635 ``authors`` elements may contain the following elements: author_,
636 organization_, address_, contact_
639 ``authors`` is analogous to the DocBook "authors" element.
650 ((author_, organization_?, address_?, contact_?)+)
653 The ``authors`` element contains only the `common attributes`_:
654 ids_, names_, dupnames_, source_, and classes_.
657 The `%bibliographic.elements;`_ parameter entity directly includes
664 reStructuredText_ source::
669 :Authors: J. Random Hacker; Jane Doe
671 Complete pseudo-XML_ result after parsing and applying transforms::
673 <document ids="document-title" names="document title">
683 In reStructuredText, multiple author's names are separated with
684 semicolons (";") or commas (","); semicolons take precedence. There
685 is currently no way to represent the author's organization, address,
686 or contact in a reStructuredText "Authors" field.
688 See docinfo_ for a more complete example, including processing
695 The ``block_quote`` element is used for quotations set off from the
696 main text (standalone).
703 `Compound Body Elements`_
706 All elements employing the `%body.elements;`_ or
707 `%structure.model;`_ parameter entities in their content models
708 may contain ``block_quote``.
711 ``block_quote`` elements contain `body elements`_ followed by an
712 optional attribution_ element.
715 ``block_quote`` is analogous to the "blockquote" element in both
719 ``block_quote`` elements serve to set their contents off from the
720 main text, typically with indentation and/or other decoration.
728 ((`%body.elements;`_)+, attribution_?)
731 The ``block_quote`` element contains only the `common
732 attributes`_: ids_, names_, dupnames_, source_, and classes_.
735 The `%body.elements;`_ parameter entity directly includes
736 ``block_quote``. The `%structure.model;`_ parameter entity
737 indirectly includes ``block_quote``.
743 reStructuredText source::
745 As a great paleontologist once said,
747 This theory, that is mine, is mine.
751 Pseudo-XML_ fragment from simple parsing::
754 As a great paleontologist once said,
757 This theory, that is mine, is mine.
765 The ``bullet_list`` element contains list_item_ elements which are
766 uniformly marked with bullets. Bullets are typically simple dingbats
767 (symbols) such as circles and squares.
774 `Compound Body Elements`_
777 All elements employing the `%body.elements;`_ or
778 `%structure.model;`_ parameter entities in their content models
779 may contain ``bullet_list``.
782 ``bullet_list`` elements contain one or more list_item_ elements.
785 ``bullet_list`` is analogous to the HTML "ul" element and to the
786 DocBook "itemizedlist" element. HTML's "ul" is short for
787 "unordered list", which we consider to be a misnomer. "Unordered"
788 implies that the list items may be randomly rearranged without
789 affecting the meaning of the list. Bullet lists *are* often
790 ordered; the ordering is simply left implicit.
793 Each list item should begin a new vertical block, prefaced by a
805 The ``bullet_list`` element contains the `common attributes`_
806 (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
808 ``bullet`` is used to record the style of bullet from the input
809 data. In documents processed from reStructuredText_, it contains
810 one of "-", "+", or "*". It may be ignored in processing.
813 The `%body.elements;`_ parameter entity directly includes
814 ``bullet_list``. The `%structure.model;`_ parameter entity
815 indirectly includes ``bullet_list``.
821 reStructuredText_ source::
823 - Item 1, paragraph 1.
829 Pseudo-XML_ fragment from simple parsing::
831 <bullet_list bullet="-">
841 See list_item_ for another example.
853 The ``caution`` element is an admonition, a distinctive and
854 self-contained notice. Also see the other admonition elements
855 Docutils offers (in alphabetical order): attention_, danger_, error_,
856 hint_, important_, note_, tip_, warning_, and the generic admonition_.
863 `Compound Body Elements`_
866 All elements employing the `%body.elements;`_ or
867 `%structure.model;`_ parameter entities in their content models
868 may contain ``caution``.
871 ``caution`` elements contain one or more `body elements`_.
874 ``caution`` is analogous to the DocBook "caution" element.
877 Rendered distinctly (inset and/or in a box, etc.), with the
878 generated title "Caution" (or similar).
886 (`%body.elements;`_)+
889 The ``caution`` element contains only the `common attributes`_:
890 ids_, names_, dupnames_, source_, and classes_.
893 The `%body.elements;`_ parameter entity directly includes
894 ``caution``. The `%structure.model;`_ parameter entity
895 indirectly includes ``caution``.
901 reStructuredText source::
903 .. Caution:: Don't take any wooden nickels.
905 Pseudo-XML_ fragment from simple parsing::
909 Don't take any wooden nickels.
918 ``citation_reference``
919 ======================
927 The ``classifier`` element contains the classification or type of the
928 term_ being defined in a definition_list_. For example, it can be
929 used to indicate the type of a variable.
936 `Body Subelements`_ (simple)
939 Only the definition_list_item_ element contains ``classifier``.
942 ``classifier`` elements may contain text data plus `inline elements`_.
945 ``classifier`` has no direct analogues in common DTDs. It can be
946 emulated with primitives or type effects.
949 See definition_list_item_.
960 The ``classifier`` element contains only the `common attributes`_:
961 ids_, names_, dupnames_, source_, and classes_.
967 Here is a hypothetical data dictionary. reStructuredText_ source::
972 Temporary index variable.
974 Pseudo-XML_ fragment from simple parsing::
977 <definition_list_item>
985 <definition_list_item>
992 Temporary index variable.
1016 The ``contact`` element holds contact information for the author
1017 (individual or group) of the document, or a third-party contact. It
1018 is typically used for an email or web address.
1025 `Bibliographic Elements`_
1028 The following elements may contain ``contact``: docinfo_, authors_
1031 ``contact`` elements may contain text data plus `inline
1035 ``contact`` is analogous to the DocBook "email" element. The HTML
1036 "address" element serves a similar purpose.
1050 The ``contact`` element contains only the `common attributes`_:
1051 ids_, names_, dupnames_, source_, and classes_.
1053 :Parameter Entities:
1054 The `%bibliographic.elements;`_ parameter entity directly includes
1061 reStructuredText_ source::
1066 :Contact: jrh@example.com
1068 Complete pseudo-XML_ result after parsing and applying transforms::
1070 <document ids="document-title" names="document title">
1075 <reference refuri="mailto:jrh@example.com">
1078 See docinfo_ for a more complete example, including processing
1091 The ``copyright`` element contains the document's copyright statement.
1098 `Bibliographic Elements`_
1101 Only the docinfo_ element contains ``copyright``.
1104 ``copyright`` elements may contain text data plus `inline
1108 ``copyright`` is analogous to the DocBook "copyright" element.
1122 The ``copyright`` element contains only the `common attributes`_:
1123 ids_, names_, dupnames_, source_, and classes_.
1125 :Parameter Entities:
1126 The `%bibliographic.elements;`_ parameter entity directly includes
1133 reStructuredText_ source::
1138 :Copyright: This document has been placed in the public domain.
1140 Complete pseudo-XML_ result after parsing and applying transforms::
1142 <document ids="document-title" names="document title">
1147 This document has been placed in the public domain.
1149 See docinfo_ for a more complete example, including processing
1156 The ``danger`` element is an admonition, a distinctive and
1157 self-contained notice. Also see the other admonition elements
1158 Docutils offers (in alphabetical order): attention_, caution_, error_,
1159 hint_, important_, note_, tip_, warning_, and the generic admonition_.
1166 `Compound Body Elements`_
1169 All elements employing the `%body.elements;`_ or
1170 `%structure.model;`_ parameter entities in their content models
1171 may contain ``danger``.
1174 ``danger`` elements contain one or more `body elements`_.
1177 ``danger`` has no direct analogues in common DTDs. It can be
1178 emulated with primitives and type effects.
1181 Rendered distinctly (inset and/or in a box, etc.), with the
1182 generated title "!DANGER!" (or similar).
1190 (`%body.elements;`_)+
1193 The ``danger`` element contains only the `common attributes`_:
1194 ids_, names_, dupnames_, source_, and classes_.
1196 :Parameter Entities:
1197 The `%body.elements;`_ parameter entity directly includes
1198 ``danger``. The `%structure.model;`_ parameter entity
1199 indirectly includes ``danger``.
1205 reStructuredText source::
1207 .. DANGER:: Mad scientist at work!
1209 Pseudo-XML_ fragment from simple parsing::
1213 Mad scientist at work!
1219 The ``date`` element contains the date of publication, release, or
1220 last modification of the document.
1227 `Bibliographic Elements`_
1230 Only the docinfo_ element contains ``date``.
1233 ``date`` elements may contain text data plus `inline elements`_.
1236 ``date`` is analogous to the DocBook "date" element.
1239 Often used with the RCS/CVS keyword "Date". See docinfo_.
1250 The ``date`` element contains only the `common attributes`_:
1251 ids_, names_, dupnames_, source_, and classes_.
1253 :Parameter Entities:
1254 The `%bibliographic.elements;`_ parameter entity directly includes
1261 reStructuredText_ source::
1268 Complete pseudo-XML_ result after parsing and applying transforms::
1270 <document ids="document-title" names="document title">
1277 See docinfo_ for a more complete example, including processing
1284 The ``decoration`` element is a container for header_ and footer_
1285 elements and potential future extensions. These elements are used for
1286 notes, time/datestamp, processing information, etc.
1293 `Structural Subelements`_
1296 Only the document_ element contains ``decoration``.
1299 ``decoration`` elements may contain `decorative elements`_.
1302 There are no direct analogies to ``decoration`` in HTML or in
1303 DocBook. Equivalents are typically constructed from primitives
1304 and/or generated by the processing system.
1307 See the individual `decorative elements`_.
1315 (header_?, footer_?)
1317 Although the content model doesn't specifically require contents, no
1318 empty ``decoration`` elements are ever created.
1321 The ``decoration`` element contains only the `common attributes`_:
1322 ids_, names_, dupnames_, source_, and classes_.
1328 reStructuredText_ source::
1332 Complete pseudo-XML_ result after parsing and applying transforms,
1333 assuming that the datestamp command-line option or configuration
1334 setting has been supplied::
1340 Generated on: 2002-08-20.
1348 The ``definition`` element is a container for the body elements used
1349 to define a term_ in a definition_list_.
1356 `Body Subelements`_ (compound)
1359 Only definition_list_item_ elements contain ``definition``.
1362 ``definition`` elements may contain `body elements`_.
1365 ``definition`` is analogous to the HTML "dd" element and to the
1366 DocBook "listitem" element (inside a "variablelistentry" element).
1369 See definition_list_item_.
1377 (`%body.elements;`_)+
1380 The ``definition`` element contains only the `common attributes`_:
1381 ids_, names_, dupnames_, source_, and classes_.
1387 See the examples for the definition_list_, definition_list_item_, and
1388 classifier_ elements.
1394 The ``definition_list`` element contains a list of terms and their
1395 definitions. It can be used for glossaries or dictionaries, to
1396 describe or classify things, for dialogues, or to itemize subtopics
1397 (such as in this reference).
1404 `Compound Body Elements`_
1407 All elements employing the `%body.elements;`_ or
1408 `%structure.model;`_ parameter entities in their content models
1409 may contain ``definition_list``.
1412 ``definition_list`` elements contain one or more
1413 definition_list_item_ elements.
1416 ``definition_list`` is analogous to the HTML "dl" element and to
1417 the DocBook "variablelist" element.
1420 See definition_list_item_.
1428 (definition_list_item_ +)
1431 The ``definition_list`` element contains only the `common
1432 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1434 :Parameter Entities:
1435 The `%body.elements;`_ parameter entity directly includes
1436 ``definition_list``. The `%structure.model;`_ parameter entity
1437 indirectly includes ``definition_list``.
1443 reStructuredText_ source::
1449 The ' : ' indicates a classifier in
1450 definition list item terms only.
1452 Pseudo-XML_ fragment from simple parsing::
1455 <definition_list_item>
1461 <definition_list_item>
1468 The ' : ' indicates a classifier in
1469 definition list item terms only.
1471 See definition_list_item_ and classifier_ for further examples.
1474 ``definition_list_item``
1475 ========================
1477 The ``definition_list_item`` element contains a single
1478 term_/definition_ pair (with optional classifier_).
1485 `Body Subelements`_ (compound)
1488 Only the definition_list_ element contains
1489 ``definition_list_item``.
1492 ``definition_list_item`` elements each contain a single term_,
1493 an optional classifier_, and a definition_.
1496 ``definition_list_item`` is analogous to the DocBook
1497 "variablelistentry" element.
1500 The optional classifier_ can be rendered differently from the
1501 term_. They should be separated visually, typically by spaces
1502 plus a colon or dash.
1510 (term_, classifier_?, definition_)
1513 The ``definition_list_item`` element contains only the `common
1514 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1520 reStructuredText_ source::
1522 Tyrannosaurus Rex : carnivore
1523 Big and scary; the "Tyrant King".
1525 Brontosaurus : herbivore
1526 All brontosauruses are thin at one end,
1527 much much thicker in the middle
1528 and then thin again at the far end.
1532 Pseudo-XML_ fragment from simple parsing::
1535 <definition_list_item>
1542 Big and scary; the "Tyrant King".
1543 <definition_list_item>
1550 All brontosauruses are thin at one end,
1551 much much thicker in the middle
1552 and then thin again at the far end.
1556 See definition_list_ and classifier_ for further examples.
1562 The ``description`` element contains body elements, describing the
1563 purpose or effect of a command-line option or group of options.
1573 Only the option_list_item_ element contains ``description``.
1576 ``description`` elements may contain `body elements`_.
1579 ``description`` has no direct analogues in common DTDs.
1590 (`%body.elements;`_)+
1593 The ``description`` element contains only the `common attributes`_:
1594 ids_, names_, dupnames_, source_, and classes_.
1600 See the examples for the option_list_ element.
1606 The ``docinfo`` element is a container for document bibliographic
1607 data, or meta-data (data about the document). It corresponds to the
1608 front matter of a book, such as the title page and copyright page.
1615 `Structural Subelements`_
1618 Only the document_ element contains ``docinfo``.
1621 ``docinfo`` elements contain `bibliographic elements`_.
1624 ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1625 etc.). There are no directly analogous HTML elements; the "meta"
1626 element carries some of the same information, albeit invisibly.
1629 The ``docinfo`` element may be rendered as a two-column table or
1630 in other styles. It may even be invisible or omitted from the
1631 processed output. Meta-data may be extracted from ``docinfo``
1632 children; for example, HTML ``<meta>`` tags may be constructed.
1634 When Docutils_ transforms a reStructuredText_ field_list_ into a
1635 ``docinfo`` element (see the examples below), RCS/CVS keywords are
1636 normally stripped from simple (one paragraph) field bodies. For
1637 complete details, please see `RCS Keywords`_ in the
1638 `reStructuredText Markup Specification`_.
1640 .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
1648 (`%bibliographic.elements;`_)+
1651 The ``docinfo`` element contains only the `common attributes`_:
1652 ids_, names_, dupnames_, source_, and classes_.
1658 Docinfo is represented in reStructuredText_ by a field_list_ in a
1659 bibliographic context: the first non-comment element of a document_,
1660 after any document title_/subtitle_. The field list is transformed
1661 into a ``docinfo`` element and its children by a transform. Source::
1666 :Author: J. Random Hacker
1667 :Contact: jrh@example.com
1669 :Status: Work In Progress
1671 :Filename: $RCSfile$
1672 :Copyright: This document has been placed in the public domain.
1674 Complete pseudo-XML_ result after parsing and applying transforms::
1676 <document ids="docinfo-example" names="docinfo example">
1683 <reference refuri="mailto:jrh@example.com">
1698 This document has been placed in the public domain.
1700 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1701 generic ``field`` element. Also note that the "RCSfile" keyword
1702 syntax has been stripped from the "Filename" data.
1704 See field_list_ for an example in a non-bibliographic context. Also
1705 see the individual examples for the various `bibliographic elements`_.
1711 The ``doctest_block`` element is a Python-specific variant of
1712 literal_block_. It is a block of text where line breaks and
1713 whitespace are significant and must be preserved. ``doctest_block``
1714 elements are used for interactive Python interpreter sessions, which
1715 are distinguished by their input prompt: ``>>>``. They are meant to
1716 illustrate usage by example, and provide an elegant and powerful
1717 testing environment via the `doctest module`_ in the Python standard
1721 http://www.python.org/doc/current/lib/module-doctest.html
1728 `Simple Body Elements`_
1731 All elements employing the `%body.elements;`_ or
1732 `%structure.model;`_ parameter entities in their content models
1733 may contain ``doctest_block``.
1736 ``doctest_block`` elements may contain text data plus `inline
1740 ``doctest_block`` is analogous to the HTML "pre" element and to
1741 the DocBook "programlisting" and "screen" elements.
1744 As with literal_block_, ``doctest_block`` elements are typically
1745 rendered in a monospaced typeface. It is crucial that all
1746 whitespace and line breaks are preserved in the rendered form.
1757 The ``doctest_block`` element contains the `common attributes`_
1758 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
1760 :Parameter Entities:
1761 The `%body.elements;`_ parameter entity directly includes
1762 ``doctest_block``. The `%structure.model;`_ parameter entity
1763 indirectly includes ``doctest_block``.
1769 reStructuredText source::
1771 This is an ordinary paragraph.
1773 >>> print 'this is a Doctest block'
1774 this is a Doctest block
1776 Pseudo-XML_ fragment from simple parsing::
1779 This is an ordinary paragraph.
1780 <doctest_block xml:space="preserve">
1781 >>> print 'this is a Doctest block'
1782 this is a Doctest block
1788 The ``document`` element is the root (topmost) element of the Docutils
1789 document tree. ``document`` is the direct or indirect ancestor of
1790 every other element in the tree. It encloses the entire document
1791 tree. It is the starting point for a document.
1798 `Structural Elements`_
1801 The ``document`` element has no parents.
1804 ``document`` elements may contain `structural subelements`_,
1805 `structural elements`_, and `body elements`_.
1808 ``document`` is analogous to the HTML "html" element and to
1809 several DocBook elements such as "book".
1817 ( (title_, subtitle_?)?,
1819 (docinfo_, transition_?)?,
1820 `%structure.model;`_ )
1822 Depending on the source of the data and the stage of processing, the
1823 "document" may not initially contain a "title". A document title is
1824 not directly representable in reStructuredText_. Instead, a lone
1825 top-level section may have its title promoted to become the document
1826 title_, and similarly for a lone second-level (sub)section's title to
1827 become the document subtitle_.
1829 The contents of "decoration_" may be specified in a document,
1830 constructed programmatically, or both. The "docinfo_" may be
1831 transformed from an initial field_list_.
1833 See the `%structure.model;`_ parameter entity for details of the body
1837 The ``document`` element contains the `common attributes`_ (ids_,
1838 names_, dupnames_, source_, and classes_), plus an optional title__
1839 attribute which stores the document title metadata.
1841 __ `title (attribute)`_
1847 reStructuredText_ source::
1854 Complete pseudo-XML_ result from simple parsing::
1857 <section ids="a-title" names="a title">
1863 After applying transforms, the section title is promoted to become the
1866 <document ids="a-title" names="a title">
1888 The ``enumerated_list`` element contains list_item_ elements which are
1889 uniformly marked with enumerator labels.
1896 `Compound Body Elements`_
1899 All elements employing the `%body.elements;`_ or
1900 `%structure.model;`_ parameter entities in their content models
1901 may contain ``enumerated_list``.
1904 ``enumerated_list`` elements contain one or more list_item_
1908 ``enumerated_list`` is analogous to the HTML "ol" element and to
1909 the DocBook "orderedlist" element.
1912 Each list item should begin a new vertical block, prefaced by a
1913 enumeration marker (such as "1.").
1924 The ``enumerated_list`` element contains the `common attributes`_
1925 (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
1926 prefix_, suffix_, and start_.
1928 ``enumtype`` is used to record the intended enumeration sequence,
1929 one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1930 "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1931 mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1934 ``prefix`` stores the formatting characters used before the
1935 enumerator. In documents originating from reStructuredText_ data,
1936 it will contain either "" (empty string) or "(" (left
1937 parenthesis). It may or may not affect processing.
1939 ``suffix`` stores the formatting characters used after the
1940 enumerator. In documents originating from reStructuredText_ data,
1941 it will contain either "." (period) or ")" (right parenthesis).
1942 Depending on the capabilities of the output format, this attribute
1943 may or may not affect processing.
1945 ``start`` contains the ordinal value of the first item in the
1946 list, in decimal. For lists beginning at value 1 ("1", "a", "A",
1947 "i", or "I"), this attribute may be omitted.
1949 :Parameter Entities:
1950 The `%body.elements;`_ parameter entity directly includes
1951 ``enumerated_list``. The `%structure.model;`_ parameter entity
1952 indirectly includes ``enumerated_list``.
1958 reStructuredText_ source::
1968 Pseudo-XML_ fragment from simple parsing::
1970 <enumerated_list enumtype="arabic" prefix="" suffix=".">
1974 <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1988 See list_item_ for another example.
1994 The ``error`` element is an admonition, a distinctive and
1995 self-contained notice. Also see the other admonition elements
1996 Docutils offers (in alphabetical order): attention_, caution_,
1997 danger_, hint_, important_, note_, tip_, warning_, and the generic
2005 `Compound Body Elements`_
2008 All elements employing the `%body.elements;`_ or
2009 `%structure.model;`_ parameter entities in their content models
2010 may contain ``error``.
2013 ``error`` elements contain one or more `body elements`_.
2016 ``error`` has no direct analogues in common DTDs. It can be
2017 emulated with primitives and type effects.
2020 Rendered distinctly (inset and/or in a box, etc.), with the
2021 generated title "Error" (or similar).
2029 (`%body.elements;`_)+
2032 The ``error`` element contains only the `common attributes`_: ids_,
2033 names_, dupnames_, source_, and classes_.
2035 :Parameter Entities:
2036 The `%body.elements;`_ parameter entity directly includes
2037 ``error``. The `%structure.model;`_ parameter entity indirectly
2044 reStructuredText source::
2046 .. Error:: Does not compute.
2048 Pseudo-XML_ fragment from simple parsing::
2058 The ``field`` element contains a pair of field_name_ and field_body_
2069 The following elements may contain ``field``: docinfo_,
2073 Each ``field`` element contains one field_name_ and one
2074 field_body_ element.
2077 ``field`` has no direct analogues in common DTDs.
2088 (field_name_, field_body_)
2091 The ``field`` element contains only the `common attributes`_:
2092 ids_, names_, dupnames_, source_, and classes_.
2094 :Parameter Entities:
2095 The `%bibliographic.elements;`_ parameter entity directly includes
2102 See the examples for the field_list_ and docinfo_ elements.
2108 The ``field_body`` element contains body elements. It is analogous to
2109 a database field's data.
2119 Only the field_ element contains ``field_body``.
2122 ``field_body`` elements may contain `body elements`_.
2125 ``field_body`` has no direct analogues in common DTDs.
2136 (`%body.elements;`_)*
2139 The ``field_body`` element contains only the `common attributes`_:
2140 ids_, names_, dupnames_, source_, and classes_.
2146 See the examples for the field_list_ and docinfo_ elements.
2152 The ``field_list`` element contains two-column table-like structures
2153 resembling database records (label & data pairs). Field lists are
2154 often meant for further processing. In reStructuredText_, field lists
2155 are used to represent bibliographic fields (contents of the docinfo_
2156 element) and directive options.
2163 `Compound Body Elements`_
2166 All elements employing the `%body.elements;`_ or
2167 `%structure.model;`_ parameter entities in their content models
2168 may contain ``field_list``.
2171 ``field_list`` elements contain one or more field_ elements.
2174 ``field_list`` has no direct analogues in common DTDs. It can be
2175 emulated with primitives such as tables.
2178 A ``field_list`` is typically rendered as a two-column list, where
2179 the first column contains "labels" (usually with a colon suffix).
2180 However, field lists are often used for extension syntax or
2181 special processing. Such structures do not survive as field lists
2193 The ``field_list`` element contains only the `common attributes`_:
2194 ids_, names_, dupnames_, source_, and classes_.
2196 :Parameter Entities:
2197 The `%body.elements;`_ parameter entity directly includes
2198 ``field_list``. The `%structure.model;`_ parameter entity
2199 indirectly includes ``field_list``.
2205 reStructuredText_ source::
2210 :Parameter i: integer
2212 Pseudo-XML_ fragment from simple parsing::
2244 The ``field_name`` element contains text; it is analogous to a
2245 database field's name.
2252 `Body Subelements`_ (simple)
2255 Only the field_ element contains ``field_name``.
2258 ``field_name`` elements may contain text data plus `inline elements`_.
2261 ``field_name`` has no direct analogues in common DTDs.
2275 The ``field_name`` element contains only the `common attributes`_:
2276 ids_, names_, dupnames_, source_, and classes_.
2282 See the examples for the field_list_ and docinfo_ elements.
2294 The ``footer`` element is a container element whose contents are meant
2295 to appear at the bottom of a web page, or repeated at the bottom of
2296 every printed page. The ``footer`` element may contain processing
2297 information (datestamp, a link to Docutils_, etc.) as well as custom
2305 `Decorative Elements`_
2308 Only the decoration_ element contains ``footer``.
2311 ``footer`` elements may contain `body elements`_.
2314 There are no direct analogies to ``footer`` in HTML or DocBook.
2315 Equivalents are typically constructed from primitives and/or
2316 generated by the processing system.
2324 (`%body.elements;`_)+
2327 The ``footer`` element contains only the `common attributes`_:
2328 ids_, names_, dupnames_, source_, and classes_.
2334 reStructuredText_ source::
2338 Complete pseudo-XML_ result after parsing and applying transforms,
2339 assuming that the datestamp command-line option or configuration
2340 setting has been supplied::
2346 Generated on: 2002-08-20.
2357 ``footnote_reference``
2358 ======================
2366 Docutils wraps ``generated`` elements around text that is inserted
2367 (generated) by Docutils; i.e., text that was not in the document, like
2368 section numbers inserted by the "sectnum" directive.
2376 The ``header`` element is a container element whose contents are meant
2377 to appear at the top of a web page, or at the top of every printed
2385 `Decorative Elements`_
2388 Only the decoration_ element contains ``header``.
2391 ``header`` elements may contain `body elements`_.
2394 There are no direct analogies to ``header`` in HTML or DocBook.
2395 Equivalents are typically constructed from primitives and/or
2396 generated by the processing system.
2404 (`%body.elements;`_)+
2407 The ``header`` element contains only the `common attributes`_:
2408 ids_, names_, dupnames_, source_, and classes_.
2414 reStructuredText source fragment::
2416 .. header:: This space for rent.
2418 Pseudo-XML_ fragment from simple parsing::
2424 This space for rent.
2430 The ``hint`` element is an admonition, a distinctive and
2431 self-contained notice. Also see the other admonition elements
2432 Docutils offers (in alphabetical order): attention_, caution_,
2433 danger_, error_, important_, note_, tip_, warning_, and the generic
2441 `Compound Body Elements`_
2444 All elements employing the `%body.elements;`_ or
2445 `%structure.model;`_ parameter entities in their content models
2446 may contain ``hint``.
2449 ``hint`` elements contain one or more `body elements`_.
2452 ``hint`` has no direct analogues in common DTDs. It can be
2453 emulated with primitives and type effects.
2456 Rendered distinctly (inset and/or in a box, etc.), with the
2457 generated title "Hint" (or similar).
2465 (`%body.elements;`_)+
2468 The ``hint`` element contains only the `common attributes`_: ids_,
2469 names_, dupnames_, source_, and classes_.
2471 :Parameter Entities:
2472 The `%body.elements;`_ parameter entity directly includes
2473 ``hint``. The `%structure.model;`_ parameter entity indirectly
2480 reStructuredText source::
2482 .. Hint:: It's bigger than a bread box.
2484 Pseudo-XML_ fragment from simple parsing::
2488 It's bigger than a bread box.
2500 The ``important`` element is an admonition, a distinctive and
2501 self-contained notice. Also see the other admonition elements
2502 Docutils offers (in alphabetical order): attention_, caution_,
2503 danger_, error_, hint_, note_, tip_, warning_, and the generic
2511 `Compound Body Elements`_
2514 All elements employing the `%body.elements;`_ or
2515 `%structure.model;`_ parameter entities in their content models
2516 may contain ``important``.
2519 ``important`` elements contain one or more `body elements`_.
2522 ``important`` is analogous to the DocBook "important" element.
2525 Rendered distinctly (inset and/or in a box, etc.), with the
2526 generated title "Important" (or similar).
2534 (`%body.elements;`_)+
2537 The ``important`` element contains only the `common attributes`_:
2538 ids_, names_, dupnames_, source_, and classes_.
2540 :Parameter Entities:
2541 The `%body.elements;`_ parameter entity directly includes
2542 ``important``. The `%structure.model;`_ parameter entity
2543 indirectly includes ``important``.
2549 reStructuredText source::
2553 * Wash behind your ears.
2554 * Clean up your room.
2555 * Back up your data.
2558 Pseudo-XML_ fragment from simple parsing::
2564 Wash behind your ears.
2597 The ``line`` element contains a single line of text, part of a
2605 `Body Subelements`_ (simple)
2608 Only the `line_block`_ element contains ``line``.
2611 ``line`` elements may contain text data plus `inline elements`_.
2614 ``line`` has no direct analogues in common DTDs. It can be
2615 emulated with primitives or type effects.
2629 The ``line`` element contains the `common attributes`_ (ids_,
2630 names_, dupnames_, source_, and classes_), plus `xml:space`_.
2642 The ``line_block`` element contains a sequence of lines and nested
2643 line blocks. Line breaks (implied between elements) and leading
2644 whitespace (indicated by nesting) is significant and must be
2645 preserved. ``line_block`` elements are commonly used for verse and
2646 addresses. See `literal_block`_ for an alternative useful for program
2647 listings and interactive computer sessions.
2654 `Compound Body Elements`_
2657 All elements employing the `%body.elements;`_ or
2658 `%structure.model;`_ parameter entities in their content models
2659 may contain ``line_block``.
2662 ``line_block`` elements may contain line_ elements and nested
2663 ``line_block`` elements.
2666 ``line_block`` is analogous to the DocBook "literallayout" element
2667 and to the HTML "pre" element (with modifications to typeface
2671 Unlike ``literal_block``, ``line_block`` elements are typically
2672 rendered in an ordinary text typeface. It is crucial that leading
2673 whitespace and line breaks are preserved in the rendered form.
2681 (line_ | line_block_)+
2684 The ``line_block`` element contains the `common attributes`_ (ids_,
2685 names_, dupnames_, source_, and classes_), plus `xml:space`_.
2687 :Parameter Entities:
2688 The `%body.elements;`_ parameter entity directly includes
2689 ``line_block``. The `%structure.model;`_ parameter entity
2690 indirectly includes ``line_block``.
2696 reStructuredText uses a directive to indicate a ``line_block``.
2699 Take it away, Eric the Orchestra Leader!
2701 | A one, two, a one two three four
2703 | Half a bee, philosophically,
2704 | must, *ipso facto*, half not be.
2705 | But half the bee has got to be,
2706 | *vis a vis* its entity. D'you see?
2708 | But can a bee be said to be
2709 | or not to be an entire bee,
2710 | when half the bee is not a bee,
2711 | due to some ancient injury?
2715 Pseudo-XML_ fragment from simple parsing::
2718 Take it away, Eric the Orchestra Leader!
2721 A one, two, a one two three four
2724 Half a bee, philosophically,
2732 But half the bee has got to be,
2737 its entity. D'you see?
2740 But can a bee be said to be
2743 or not to be an entire bee,
2746 when half the bee is not a bee,
2749 due to some ancient injury?
2758 The ``list_item`` element is a container for the elements of a list
2766 `Body Subelements`_ (compound)
2769 The bullet_list_ and enumerated_list_ elements contain
2773 ``list_item`` elements may contain `body elements`_.
2776 ``list_item`` is analogous to the HTML "li" element and to the
2777 DocBook "listitem" element.
2780 See bullet_list_ or enumerated_list_.
2788 (`%body.elements;`_)*
2791 The ``list_item`` element contains only the `common attributes`_:
2792 ids_, names_, dupnames_, source_, and classes_.
2798 reStructuredText_ source::
2800 1. Outer list, item 1.
2802 * Inner list, item 1.
2803 * Inner list, item 2.
2805 2. Outer list, item 2.
2807 Pseudo-XML_ fragment from simple parsing::
2809 <enumerated_list enumtype="arabic" prefix="" suffix=".">
2813 <bullet_list bullet="*">
2824 See bullet_list_ or enumerated_list_ for further examples.
2836 The ``literal_block`` element contains a block of text where line
2837 breaks and whitespace are significant and must be preserved.
2838 ``literal_block`` elements are commonly used for program listings and
2839 interactive computer sessions. See `line_block`_ for an alternative
2840 useful for verse and addresses.
2847 `Simple Body Elements`_
2850 All elements employing the `%body.elements;`_ or
2851 `%structure.model;`_ parameter entities in their content models
2852 may contain ``literal_block``.
2855 ``literal_block`` elements may contain text data plus `inline
2859 ``literal_block`` is analogous to the HTML "pre" element and to
2860 the DocBook "programlisting" and "screen" elements.
2863 ``literal_block`` elements are typically rendered in a monospaced
2864 typeface. It is crucial that all whitespace and line breaks are
2865 preserved in the rendered form.
2876 The ``literal_block`` element contains the `common attributes`_
2877 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
2879 :Parameter Entities:
2880 The `%body.elements;`_ parameter entity directly includes
2881 ``literal_block``. The `%structure.model;`_ parameter entity
2882 indirectly includes ``literal_block``.
2888 reStructuredText source::
2890 Here is a literal block::
2893 text = 'is left as-is'
2894 spaces_and_linebreaks = 'are preserved'
2895 markup_processing = None
2897 Pseudo-XML_ fragment from simple parsing::
2900 Here is a literal block:
2901 <literal_block xml:space="preserve">
2903 text = 'is left as-is'
2904 spaces_and_linebreaks = 'are preserved'
2905 markup_processing = None
2910 The ``math`` element contains text in `LaTeX math format` [#latex-math]_
2911 that is typeset as mathematical notation (inline formula).
2913 If the output format does not support math typesetting, the content is
2923 All elements employing the `%inline.elements;`_ parameter entities in
2924 their content models may contain ``math``.
2927 ``math`` elements may contain text data.
2930 ``math`` is analogous to a MathML "math" element or
2931 the LaTeX (``$ math $``) mode.
2934 Rendered as mathematical notation.
2944 The ``math`` element contains the `common attributes`_
2945 (ids_, names_, dupnames_, source_, and classes_).
2947 .. [#latex-math] For details of the supported mathematical language, see
2948 the `"math" directive`_
2950 .. _"math" directive: rst/directives.html#math
2956 The ``math_block`` element contains a block of text in `LaTeX math
2957 format` [#latex-math]_ that is typeset as mathematical notation
2958 (display formula). The ``math_block`` element is generated during
2959 the initial parse from a "math" directive.
2961 If the output format does not support math typesetting, the content is
2968 `Simple Body Elements`_
2971 All elements employing the `%body.elements;`_ or
2972 `%structure.model;`_ parameter entities in their content models
2973 may contain ``math_block``.
2976 ``math_block`` elements may contain text data.
2979 ``math_block`` is analogous to a LaTeX "equation*" environment or
2980 a MathML "math" element displayed as block-level element.
2983 Rendered in a block as mathematical notation, typically centered or with
2994 The ``math`` element contains the `common attributes`_
2995 (ids_, names_, dupnames_, source_, and classes_).
3001 The ``note`` element is an admonition, a distinctive and
3002 self-contained notice. Also see the other admonition elements
3003 Docutils offers (in alphabetical order): attention_, caution_,
3004 danger_, error_, hint_, important_, tip_, warning_, and the generic
3012 `Compound Body Elements`_
3015 All elements employing the `%body.elements;`_ or
3016 `%structure.model;`_ parameter entities in their content models
3017 may contain ``note``.
3020 ``note`` elements contain one or more `body elements`_.
3023 ``note`` is analogous to the DocBook "note" element.
3026 Rendered distinctly (inset and/or in a box, etc.), with the
3027 generated title "Note" (or similar).
3035 (`%body.elements;`_)+
3038 The ``note`` element contains only the `common attributes`_: ids_,
3039 names_, dupnames_, source_, and classes_.
3041 :Parameter Entities:
3042 The `%body.elements;`_ parameter entity directly includes
3043 ``note``. The `%structure.model;`_ parameter entity indirectly
3050 reStructuredText source::
3052 .. Note:: Admonitions can be handy to break up a
3053 long boring technical document.
3055 Pseudo-XML_ fragment from simple parsing::
3059 Admonitions can be handy to break up a
3060 long boring technical document.
3065 The ``option`` element groups an option string together with zero or
3066 more option argument placeholders. Note that reStructuredText_
3067 currently supports only one argument per option.
3077 Only the option_group_ element contains ``option``.
3080 Each ``option`` element contains one option_string_ and zero or
3081 more option_argument_ elements.
3084 ``option`` has no direct analogues in common DTDs.
3095 (option_string_, option_argument_ \*)
3098 The ``option`` element contains only the `common attributes`_:
3099 ids_, names_, dupnames_, source_, and classes_.
3105 See the examples for the option_list_ element.
3111 The ``option_argument`` element contains placeholder text for option
3122 Only the option_ element contains ``option_argument``.
3125 ``option_argument`` elements contain text data only.
3128 ``option_argument`` has no direct analogues in common DTDs.
3131 The value of the "delimiter" attribute is prefixed to the
3132 ``option_argument``, separating it from its option_string_ or a
3133 preceding ``option_argument``. The ``option_argument`` text is
3134 typically rendered in a monospaced typeface, possibly italicized
3135 or otherwise altered to indicate its placeholder nature.
3146 The ``option_argument`` element contains the `common attributes`_ (ids_,
3147 names_, dupnames_, source_, and classes_), plus delimiter_.
3149 ``delimiter`` contains the text preceding the ``option_argument``:
3150 either the text separating it from the option_string_ (typically
3151 either "=" or " ") or the text between option arguments (typically
3158 See the examples for the option_list_ element.
3164 The ``option_group`` element groups together one or more option_
3165 elements, all synonyms.
3175 Only the option_list_item_ element contains ``option_group``.
3178 ``option_group`` elements contain one or more option_ elements.
3180 ``option_group`` is an empty element and has no children.
3182 Each ``option_group`` element contains one _ and
3186 ``option_group`` has no direct analogues in common DTDs.
3189 Typically option_ elements within an ``option_group`` are joined
3190 together in a comma-separated list.
3198 (option_group_, description_)
3201 The ``option_group`` element contains only the `common attributes`_:
3202 ids_, names_, dupnames_, source_, and classes_.
3208 See the examples for the option_list_ element.
3214 Each ``option_list`` element contains a two-column list of
3215 command-line options and descriptions, documenting a program's
3223 `Compound Body Elements`_
3226 All elements employing the `%body.elements;`_ or
3227 `%structure.model;`_ parameter entities in their content models
3228 may contain ``option_list``.
3231 ``option_list`` elements contain one or more option_list_item_
3235 ``option_list`` has no direct analogues in common DTDs. It can be
3236 emulated with primitives such as tables.
3239 An ``option_list`` is typically rendered as a two-column list,
3240 where the first column contains option strings and arguments, and
3241 the second column contains descriptions.
3249 (option_list_item_ +)
3252 The ``option_list`` element contains only the `common attributes`_:
3253 ids_, names_, dupnames_, source_, and classes_.
3255 :Parameter Entities:
3256 The `%body.elements;`_ parameter entity directly includes
3257 ``option_list``. The `%structure.model;`_ parameter entity
3258 indirectly includes ``option_list``.
3264 reStructuredText_ source::
3266 -a command-line option "a"
3267 -1 file, --one=file, --two file
3268 Multiple options with arguments.
3270 Pseudo-XML_ fragment from simple parsing::
3280 command-line option "a"
3286 <option_argument delimiter=" ">
3291 <option_argument delimiter="=">
3296 <option_argument delimiter=" ">
3300 Multiple options with arguments.
3303 ``option_list_item``
3304 ====================
3306 The ``option_list_item`` element is a container for a pair of
3307 option_group_ and description_ elements.
3317 Only the option_list_ element contains ``option_list_item``.
3320 Each ``option_list_item`` element contains one option_group_ and
3321 one description_ element.
3324 ``option_list_item`` has no direct analogues in common DTDs.
3335 (option_group_, description_)
3338 The ``option_list_item`` element contains only the `common attributes`_:
3339 ids_, names_, dupnames_, source_, and classes_.
3345 See the examples for the option_list_ element.
3351 The ``option_string`` element contains the text of a command-line
3362 Only the option_ element contains ``option_string``.
3365 ``option_string`` elements contain text data only.
3368 ``option_string`` has no direct analogues in common DTDs.
3371 The ``option_string`` text is typically rendered in a monospaced
3383 The ``option_string`` element contains only the `common attributes`_:
3384 ids_, names_, dupnames_, source_, and classes_.
3390 See the examples for the option_list_ element.
3396 The ``organization`` element contains the name of document author's
3397 organization, or the organization responsible for the document.
3404 `Bibliographic Elements`_
3407 Only the docinfo_ element contains ``organization``.
3410 ``organization`` elements may contain text data plus `inline
3414 ``organization`` is analogous to the DocBook "orgname",
3415 "corpname", or "publishername" elements.
3429 The ``organization`` element contains only the `common attributes`_:
3430 ids_, names_, dupnames_, source_, and classes_.
3432 :Parameter Entities:
3433 The `%bibliographic.elements;`_ parameter entity directly includes
3440 reStructuredText_ source::
3445 :Organization: Humankind
3447 Complete pseudo-XML_ result after parsing and applying transforms::
3449 <document ids="document-title" names="document title">
3456 See docinfo_ for a more complete example, including processing
3463 The ``paragraph`` element contains the text and inline elements of a
3464 single paragraph, a fundamental building block of documents.
3471 `Simple Body Elements`_
3474 All elements employing the `%body.elements;`_ or
3475 `%structure.model;`_ parameter entities in their content models
3476 may contain ``paragraph``.
3479 ``paragraph`` elements may contain text data plus `inline
3483 ``paragraph`` is analogous to the HTML "p" element and to the
3484 DocBook "para" elements.
3495 The ``paragraph`` element contains only the `common attributes`_:
3496 ids_, names_, dupnames_, source_, and classes_.
3498 :Parameter Entities:
3499 The `%body.elements;`_ parameter entity directly includes
3500 ``paragraph``. The `%structure.model;`_ parameter entity
3501 indirectly includes ``paragraph``.
3507 reStructuredText_ source::
3511 Pseudo-XML_ fragment from simple parsing::
3544 The ``revision`` element contains the revision number of the document.
3545 It can be used alone or in conjunction with version_.
3552 `Bibliographic Elements`_
3555 Only the docinfo_ element contains ``revision``.
3558 ``revision`` elements may contain text data plus `inline
3562 ``revision`` is analogous to but simpler than the DocBook
3563 "revision" element. It closely matches the DocBook "revnumber"
3564 element, but in a simpler context.
3567 Often used with the RCS/CVS keyword "Revision". See docinfo_.
3578 The ``revision`` element contains only the `common attributes`_:
3579 ids_, names_, dupnames_, source_, and classes_.
3581 :Parameter Entities:
3582 The `%bibliographic.elements;`_ parameter entity directly includes
3589 reStructuredText_ source::
3597 Complete pseudo-XML_ result after parsing and applying transforms::
3599 <document ids="document-title" names="document title">
3608 See docinfo_ for a more complete example, including processing
3621 rubric n. 1. a title, heading, or the like, in a manuscript,
3622 book, statute, etc., written or printed in red or otherwise
3623 distinguished from the rest of the text. ...
3625 -- Random House Webster's College Dictionary, 1991
3627 A rubric is like an informal heading that doesn't correspond to the
3628 document's structure.
3636 The ``section`` element is the main unit of hierarchy for Docutils
3637 documents. Docutils ``section`` elements are a recursive structure; a
3638 ``section`` may contain other ``section`` elements, without limit.
3639 Paragraphs and other body elements may occur before a ``section``, but
3647 `Structural Elements`_
3650 The following elements may contain ``section``: document_,
3654 ``section`` elements begin with a title_, and may contain `body
3655 elements`_ as well as transition_, topic_, and sidebar_ elements.
3658 ``section`` is analogous to DocBook recursive "section" elements,
3659 and to HTML "div" elements combined with "h1" etc. title elements.
3668 `%structure.model;`_)
3670 See the `%structure.model;`_ parameter entity for details of the body
3674 The ``section`` element contains only the `common attributes`_:
3675 ids_, names_, dupnames_, source_, and classes_.
3677 :Parameter Entities:
3678 The `%section.elements;`_ parameter entity directly includes
3679 ``section``. The `%structure.model;`_ parameter entity indirectly
3680 includes ``section``.
3686 reStructuredText_ source::
3704 Complete pseudo-XML_ result after parsing::
3707 <section ids="title-1" names="title 1">
3712 <section ids="title-2" names="title 2">
3717 <section ids="title-3" names="title 3">
3722 <section ids="title-4" names="title 4">
3732 Sidebars are like miniature, parallel documents that occur inside
3733 other documents, providing related or reference material. A
3734 ``sidebar`` is typically offset by a border and "floats" to the side
3735 of the page; the document's main text may flow around it. Sidebars
3736 can also be likened to super-footnotes; their content is outside of
3737 the flow of the document's main text.
3739 The ``sidebar`` element is a nonrecursive section_-like construct
3740 which may occur at the top level of a section_ wherever a body element
3741 (list, table, etc.) is allowed. In other words, ``sidebar`` elements
3742 cannot nest inside body elements, so you can't have a ``sidebar``
3743 inside a ``table`` or a ``list``, or inside another ``sidebar`` (or
3751 `Structural Elements`_
3754 The following elements may contain ``sidebar``: document_,
3758 ``sidebar`` elements begin with a title_ and an optional subtitle_
3759 and contain `body elements`_ and topic_ elements.
3762 ``sidebar`` is analogous to the DocBook "sidebar" element.
3765 A ``sidebar`` element should be set off from the rest of the
3766 document somehow, typically with a border. Sidebars typically
3767 "float" to the side of the page and the document's main text flows
3776 (title_, subtitle_?,
3777 (`%body.elements;`_ | topic_)+)
3780 The ``sidebar`` element contains only the `common attributes`_:
3781 ids_, names_, dupnames_, source_, and classes_.
3783 :Parameter Entities:
3784 The `%structure.model;`_ parameter entity directly includes
3791 The `"sidebar" directive`_ is used to create a ``sidebar`` element.
3792 reStructuredText_ source::
3795 :subtitle: If Desired
3799 Pseudo-XML_ fragment from simple parsing::
3809 .. _"sidebar" directive: rst/directives.html#sidebar
3815 The ``status`` element contains a status statement for the document,
3816 such as "Draft", "Final", "Work In Progress", etc.
3823 `Bibliographic Elements`_
3826 Only the docinfo_ element contains ``status``.
3829 ``status`` elements may contain text data plus `inline elements`_.
3832 ``status`` is analogous to the DocBook "status" element.
3846 The ``status`` element contains only the `common attributes`_:
3847 ids_, names_, dupnames_, source_, and classes_.
3849 :Parameter Entities:
3850 The `%bibliographic.elements;`_ parameter entity directly includes
3857 reStructuredText_ source::
3862 :Status: Work In Progress
3864 Complete pseudo-XML_ result after parsing and applying transforms::
3866 <document ids="document-title" names="document title">
3873 See docinfo_ for a more complete example, including processing
3889 ``substitution_definition``
3890 ===========================
3895 ``substitution_reference``
3896 ==========================
3904 The ``subtitle`` element stores the subtitle of a document_.
3911 `Structural Subelements`_
3914 The document_ and sidebar_ elements may contain ``subtitle``.
3917 ``subtitle`` elements may contain text data plus `inline
3921 ``subtitle`` is analogous to HTML header elements ("h2" etc.) and
3922 to the DocBook "subtitle" element.
3925 A document's subtitle is usually rendered smaller than its title_.
3936 The ``subtitle`` element contains only the `common attributes`_:
3937 ids_, names_, dupnames_, source_, and classes_.
3943 reStructuredText_ source::
3954 Complete pseudo-XML_ result after parsing and applying transforms::
3956 <document ids="title" names="title">
3959 <subtitle ids="subtitle" names="subtitle">
3964 Note how two section levels have collapsed, promoting their titles to
3965 become the document's title and subtitle. Since there is only one
3966 structural element (document), the subsection's ``ids`` and ``names``
3967 attributes are stored in the ``subtitle`` element.
3985 Docutils tables are based on the Exchange subset of the CALS-table model
3986 (OASIS Technical Memorandum 9901:1999 "XML Exchange Table Model DTD",
3987 http://www.oasis-open.org/html/tm9901.htm).
4007 The ``term`` element contains a word or phrase being defined in a
4015 `Body Subelements`_ (simple)
4018 Only the definition_list_item_ element contains ``term``.
4021 ``term`` elements may contain text data plus `inline elements`_.
4024 ``term`` is analogous to the HTML "dt" element and to the DocBook
4028 See definition_list_item_.
4039 The ``term`` element contains only the `common attributes`_:
4040 ids_, names_, dupnames_, source_, and classes_.
4046 See the examples for the definition_list_, definition_list_item_, and
4047 classifier_ elements.
4065 The ``tip`` element is an admonition, a distinctive and self-contained
4066 notice. Also see the other admonition elements Docutils offers (in
4067 alphabetical order): attention_, caution_, danger_, error_, hint_,
4068 important_, note_, warning_, and the generic admonition_.
4075 `Compound Body Elements`_
4078 All elements employing the `%body.elements;`_ or
4079 `%structure.model;`_ parameter entities in their content models
4080 may contain ``tip``.
4083 ``tip`` elements contain one or more `body elements`_.
4086 ``tip`` is analogous to the DocBook "tip" element.
4089 Rendered distinctly (inset and/or in a box, etc.), with the
4090 generated title "Tip" (or similar).
4098 (`%body.elements;`_)+
4101 The ``tip`` element contains only the `common attributes`_: ids_,
4102 names_, dupnames_, source_, and classes_.
4104 :Parameter Entities:
4105 The `%body.elements;`_ parameter entity directly includes ``tip``.
4106 The `%structure.model;`_ parameter entity indirectly includes
4113 reStructuredText source::
4115 .. Tip:: 15% if the service is good.
4117 Pseudo-XML_ fragment from simple parsing::
4121 15% if the service is good.
4129 The ``title`` element stores the title of a document_, section_,
4130 topic_, sidebar_, or generic admonition_.
4137 `Structural Subelements`_
4140 The following elements may contain ``title``: document_, section_,
4141 topic_, sidebar_, admonition_
4144 ``title`` elements may contain text data plus `inline elements`_.
4147 ``title`` is analogous to HTML "title" and header ("h1" etc.)
4148 elements, and to the DocBook "title" element.
4159 The ``title`` element contains the `common attributes`_ (ids_,
4160 names_, dupnames_, source_, and classes_), plus refid_ and auto_.
4162 ``refid`` is used as a backlink to a table of contents entry.
4164 ``auto`` is used to indicate (with value "1") that the ``title``
4165 has been numbered automatically.
4171 reStructuredText_ source::
4178 Pseudo-XML_ fragment from simple parsing::
4180 <section ids="a-title" names="a title">
4196 The ``topic`` element is a nonrecursive section_-like construct which
4197 may occur at the top level of a section_ wherever a body element
4198 (list, table, etc.) is allowed. In other words, ``topic`` elements
4199 cannot nest inside body elements, so you can't have a ``topic`` inside
4200 a ``table`` or a ``list``, or inside another ``topic``.
4207 `Structural Elements`_
4210 The following elements may contain ``topic``: document_, section_,
4214 ``topic`` elements begin with a title_ and may contain `body
4218 ``topic`` is analogous to the DocBook "simplesect" element.
4221 A ``topic`` element should be set off from the rest of the
4222 document somehow, such as with indentation or a border.
4231 (`%body.elements;`_)+)
4234 The ``topic`` element contains only the `common attributes`_:
4235 ids_, names_, dupnames_, source_, and classes_.
4237 :Parameter Entities:
4238 The `%structure.model;`_ parameter entity directly includes
4245 The `"topic" directive`_ is used to create a ``topic`` element.
4246 reStructuredText_ source::
4252 Pseudo-XML_ fragment from simple parsing::
4260 .. _"topic" directive: rst/directives.html#topic
4266 The ``transition`` element is commonly seen in novels and short
4267 fiction, as a gap spanning one or more lines, with or without a type
4268 ornament such as a row of asterisks. Transitions separate body
4269 elements and sections, dividing a section into untitled divisions. A
4270 transition may not begin or end a section [#]_ or document, nor may
4271 two transitions be immediately adjacent.
4273 See `Doctree Representation of Transitions`__ in `A Record of
4274 reStructuredText Syntax Alternatives`__.
4276 .. [#] In reStructuredText markup, a transition may appear to fall at
4277 the end of a section immediately before another section. A
4278 transform recognizes this case and moves the transition so it
4279 separates the sections.
4281 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
4282 __ ../dev/rst/alternatives.html
4289 `Structural Subelements`_
4292 The following elements may contain ``transition``: document_,
4296 ``transition`` is an empty element and has no children.
4299 ``transition`` is analogous to the HTML "hr" element.
4302 The ``transition`` element is typically rendered as vertical
4303 whitespace (more than that separating paragraphs), with or without
4304 a horizontal line or row of asterisks. In novels, transitions are
4305 often represented as a row of three well-spaced asterisks with
4306 vertical space above and below.
4316 The ``transition`` element has no content; it is a "point element".
4319 The ``transition`` element contains only the `common attributes`_:
4320 ids_, names_, dupnames_, source_, and classes_.
4322 :Parameter Entities:
4323 The `%structure.model;`_ parameter entity directly includes
4330 reStructuredText_ source::
4338 Complete pseudo-XML_ result after parsing::
4351 The ``version`` element contains the version number of the document.
4352 It can be used alone or in conjunction with revision_.
4359 `Bibliographic Elements`_
4362 Only the docinfo_ element contains ``version``.
4365 ``version`` elements may contain text data plus `inline
4369 ``version`` may be considered analogous to the DocBook "revision",
4370 "revnumber", or "biblioid" elements.
4373 Sometimes used with the RCS/CVS keyword "Revision". See docinfo_
4385 The ``version`` element contains only the `common attributes`_:
4386 ids_, names_, dupnames_, source_, and classes_.
4388 :Parameter Entities:
4389 The `%bibliographic.elements;`_ parameter entity directly includes
4396 reStructuredText_ source::
4403 Complete pseudo-XML_ result after parsing and applying transforms::
4405 <document ids="document-title" names="document title">
4412 See docinfo_ for a more complete example, including processing
4419 The ``warning`` element is an admonition, a distinctive and
4420 self-contained notice. Also see the other admonition elements
4421 Docutils offers (in alphabetical order): attention_, caution_,
4422 danger_, error_, hint_, important_, note_, tip_.
4429 `Compound Body Elements`_
4432 All elements employing the `%body.elements;`_ or
4433 `%structure.model;`_ parameter entities in their content models
4434 may contain ``warning``.
4437 ``warning`` elements contain one or more `body elements`_.
4440 ``warning`` is analogous to the DocBook "warning" element.
4443 Rendered distinctly (inset and/or in a box, etc.), with the
4444 generated title "Warning" (or similar).
4452 (`%body.elements;`_)+
4455 The ``warning`` element contains only the `common attributes`_:
4456 ids_, names_, dupnames_, source_, and classes_.
4458 :Parameter Entities:
4459 The `%body.elements;`_ parameter entity directly includes
4460 ``warning``. The `%structure.model;`_ parameter entity indirectly
4461 includes ``warning``.
4467 reStructuredText source::
4469 .. WARNING:: Reader discretion is strongly advised.
4471 Pseudo-XML_ fragment from simple parsing::
4475 Reader discretion is strongly advised.
4478 ---------------------
4480 ---------------------
4482 .. contents:: :local:
4485 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
4486 all elements contain the following attributes: ids_, names_, dupnames_,
4487 source_, and classes_.
4494 Character data. ``CDATA`` attributes may contain arbitrary text.
4497 Like a ``NMTOKEN``, but it must begin with a letter (a "name
4498 production"). Identical ``ID`` values must not appear more than
4499 once in a document; i.e., ID values must uniquely identify their
4503 A reference to an ``ID`` value (a name production) of another
4507 One or more space-separated ``ID`` references (name productions).
4510 A "name token". One or more of letters, digits, ".", "-", and
4514 One or more space-separated ``NMTOKEN`` names.
4517 No if zero ("0"), yes if any other value. This is a parameter
4518 entity which resolves to a ``NMTOKEN`` attribute type.
4521 This emphasizes that the attribute value must be a number. This
4522 is a parameter entity which resolves to a ``NMTOKEN`` attribute
4526 The attribute value may be one of a specified list of values.
4532 `Attribute type`_: ``%yesorno;``. Default value: none (implies no).
4534 The ``anonymous`` attribute is used for unnamed hyperlinks in the
4535 target_ and reference_ elements (via the `%anonymous.att;`_ parameter
4542 `Attribute type`_: ``CDATA``. Default value: none.
4544 The ``auto`` attribute is used to indicate automatically-numbered
4545 footnote_, footnote_reference_ and title_ elements (via the
4546 `%auto.att;`_ parameter entity).
4552 `Attribute type`_: ``IDREFS``. Default value: none.
4554 The ``backrefs`` attribute contains a space-separated list of ids_
4555 references, used for backlinks from footnote_, citation_, and
4556 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
4562 `Attribute type`_: ``CDATA``. Default value: none.
4564 The ``bullet`` attribute is used in the bullet_list_ element.
4570 `Attribute type`_: ``NMTOKENS``. Default value: none.
4572 The ``classes`` attribute is a list containing zero or more names used
4573 to classify an element. The names are converted to conform to the
4574 regular expression ``[a-z](-?[a-z0-9]+)*`` (see the `"class"
4575 directive`_ description for details and rationale_).
4577 The purpose of the attribute is to indicate
4578 an "is-a" variant relationship, to allow an extensible way of defining
4579 sub-classes of existing elements. It can be used to carry context
4580 forward between a Docutils Reader and Writer, when a custom structure
4581 is reduced to a standardized document tree. One common use is in
4582 conjunction with stylesheets, to add selection criteria. It should
4583 not be used to carry formatting instructions or arbitrary content.
4585 The ``classes`` attribute's contents should be ignorable. Writers that
4586 are not familiar with the variant expressed should be able to ignore
4589 ``classes`` is one of the `common attributes`_, shared by all Docutils
4592 .. _"class" directive: rst/directives.html#class
4593 .. _rationale: rst/directives.html#rationale
4598 `Attribute type`_: ``CDATA``. Default value: none.
4600 The ``delimiter`` attribute is used in the option_argument_ element.
4606 `Attribute type`_: ``CDATA``. Default value: none.
4608 The ``dupnames`` attribute is a list containing the names of an
4609 element when there has been a naming conflict. The contents of the
4610 ``dupnames`` attribute would have been transferred from the `names`_
4611 attribute. An element may have at most one of the ``names`` or
4612 ``dupnames`` attributes, but not both. ``dupnames`` is one of the
4613 `common attributes`_, shared by all Docutils elements.
4619 `Attribute type`_: enumeration, one of "arabic", "loweralpha",
4620 "upperalpha", "lowerroman", or "upperroman". Default value: none.
4622 The ``enumtype`` attribute is used in the enumerated_list_ element.
4628 `Attribute type`_: ``NMTOKENS``. Default value: none.
4630 The ``ids`` attribute is a list containing one or more unique
4631 identifier keys. ``ids`` is one of the `common attributes`_, shared
4632 by all Docutils elements.
4638 `Attribute type`_: ``CDATA``. Default value: none.
4640 The ``names`` attribute is a list containing the names of an element,
4641 typically originating from the element's title or content. Each name
4642 in ``names`` must be unique; if there are name conflicts (two or more
4643 elements want to the same name), the contents will be transferred to
4644 the `dupnames`_ attribute on the duplicate elements. An element may
4645 have at most one of the ``names`` or ``dupnames`` attributes, but not
4646 both. ``names`` is one of the `common attributes`_, shared by all
4653 `Attribute type`_: ``CDATA``. Default value: none.
4655 The ``prefix`` attribute is used in the enumerated_list_ element.
4661 `Attribute type`_: ``IDREF``. Default value: none.
4663 The ``refid`` attribute contains references to `ids`_ attributes in
4664 other elements. It is used by the target_, reference_,
4665 footnote_reference_, citation_reference_, title_ and problematic_
4666 elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter
4673 `Attribute type`_: ``NMTOKENS``. Default value: none.
4675 The ``refname`` attribute contains an internal reference to the
4676 `names`_ attribute of another element. On a `target`_ element,
4677 ``refname`` indicates an indirect target which may resolve to either
4678 an internal or external reference. ``refname`` is used by the
4679 target_, reference_, footnote_reference_, citation_reference_, and
4680 substitution_reference_ elements (via the `%refname.att;`_ and
4681 `%reference.atts;`_ parameter entities).
4687 `Attribute type`_: ``CDATA``. Default value: none.
4689 The ``refuri`` attribute contains an external reference to a URI/URL.
4690 It is used by the target_, reference_, footnote_reference_, and
4691 citation_reference_ elements (via the `%reference.atts;`_ parameter
4698 `Attribute type`_: ``CDATA``. Default value: none.
4700 The ``source`` attribute is used to store the path or URL to the
4701 source text that was used to produce the document tree. It is one of
4702 the `common attributes`_, shared by all Docutils elements.
4708 `Attribute type`_: ``%number;``. Default value: none.
4710 The ``start`` attribute is used in the enumerated_list_ element.
4716 `Attribute type`_: ``CDATA``. Default value: none.
4718 The ``suffix`` attribute is used in the enumerated_list_ element.
4724 `Attribute type`_: one of "default" or "preserve". Default value:
4727 The ``xml:space`` attribute is a standard XML attribute for
4728 whitespace-preserving elements. It is used by the literal_block_,
4729 line_block_, doctest_block_, comment_, and raw_ elements (via the
4730 `%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant
4731 to communicate to an XML parser that the element contains significant
4732 whitespace. The attribute value should not be set in a document
4736 .. _title (attribute):
4741 `Attribute type`_: ``CDATA``. Default value: none.
4743 The ``title`` attribute stores the title metadata of a document. This
4744 title is typically not part of the rendered document. It may for
4745 example be used in HTML's ``title`` element.
4748 ----------------------------
4749 Parameter Entity Reference
4750 ----------------------------
4752 .. contents:: :local:
4755 Parameter entities are used to simplify the DTD (to share definitions
4756 and reduce duplication) and to allow the DTD to be customized by
4757 wrapper DTDs (external client DTDs that use or import the Docutils
4758 DTD). Parameter entities may be overridden by wrapper DTDs, replacing
4759 the definitions below with custom definitions. Parameter entities
4760 whose names begin with "additional" are meant to allow easy extension
4767 The ``%anonymous.att;`` parameter entity contains the anonymous_
4768 attribute, used for unnamed hyperlinks.
4774 anonymous_ %yesorno; #IMPLIED
4776 The reference_ and target_ elements directly employ the
4777 ``%anonymous.att;`` parameter entity in their attribute lists.
4783 The ``%auto.att;`` parameter entity contains the auto_ attribute, used
4784 to indicate an automatically-numbered footnote or title.
4790 auto_ CDATA #IMPLIED
4792 The footnote_, footnote_reference_, and title_ elements directly
4793 employ the ``%auto.att;`` parameter entity in their attribute lists.
4799 The ``%backrefs.att;`` parameter entity contains the backrefs_
4800 attribute, a space-separated list of id references, for backlinks.
4806 backrefs_ IDREFS #IMPLIED
4808 The citation_, footnote_, and system_message_ elements directly employ
4809 the ``%backrefs.att;`` parameter entity in their attribute lists.
4815 The ``%basic.atts;`` parameter entity lists attributes common to all
4816 Docutils elements. See `Common Attributes`_.
4822 ids_ NMTOKENS #IMPLIED
4823 names_ CDATA #IMPLIED
4824 dupnames_ CDATA #IMPLIED
4825 source_ CDATA #IMPLIED
4826 classes_ NMTOKENS #IMPLIED
4827 %additional.basic.atts;
4829 The ``%additional.basic.atts;`` parameter entity can be used by
4830 wrapper DTDs to extend ``%basic.atts;``.
4833 ``%bibliographic.elements;``
4834 ============================
4836 The ``%bibliographic.elements;`` parameter entity contains an OR-list of all
4837 `bibliographic elements`_.
4843 author_ | authors_ | organization_ | contact_ | address_
4844 | version_ | revision_ | status_ | date_ | copyright_
4846 %additional.bibliographic.elements;
4848 The ``%additional.bibliographic.elements;`` parameter entity can be used by
4849 wrapper DTDs to extend ``%bibliographic.elements;``.
4851 Only the docinfo_ element directly employs the
4852 ``%bibliographic.elements;`` parameter entity in its content model.
4858 The ``%body.elements;`` parameter entity contains an OR-list of all
4859 `body elements`_. ``%body.elements;`` is itself contained within the
4860 `%structure.model;`_ parameter entity.
4866 admonition_ | attention_ | block_quote_ | bullet_list_ | caution_
4867 | citation_ | compound_ | comment_ | container_ | danger_ |
4868 definition_list_ | doctest_block_ | enumerated_list_ | error_ |
4869 field_list_ | figure_ | footnote_ | hint_ | image_ | important_
4870 | line_block_ | literal_block_ | note_ | option_list_ |
4871 paragraph_ | pending_ | raw_ reference_ | rubric_ |
4872 substitution_definition_ | system_message_ | table_ | target_ |
4873 tip_ | warning_ %additional.body.elements;
4875 The ``%additional.body.elements;`` parameter entity can be used by
4876 wrapper DTDs to extend ``%body.elements;``.
4878 The ``%body.elements;`` parameter entity is directly employed in the
4879 content models of the following elements: admonition_, attention_,
4880 block_quote_, caution_, citation_, compound_, danger_, definition_,
4881 description_, entry_, error_, field_body_, footer_, footnote_,
4882 header_, hint_, important_, legend_, list_item_, note_, sidebar_,
4883 system_message_, tip_, topic_, warning_
4885 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
4886 indirectly employed in the content models of the document_ and
4890 ``%fixedspace.att;``
4891 ====================
4893 The ``%fixedspace.att;`` parameter entity contains the `xml:space`_
4894 attribute, a standard XML attribute for whitespace-preserving
4901 `xml:space`_ (default | preserve) #FIXED 'preserve'
4903 The ``%fixedspace.att;`` parameter entity is directly employed in the
4904 attribute lists of the following elements: address_, comment_,
4905 doctest_block_, line_block_, literal_block_, raw_
4908 ``%inline.elements;``
4909 =====================
4911 The ``%inline.elements;`` parameter entity contains an OR-list of all
4918 abbreviation_ | acronym_ | citation_reference_ | emphasis_ |
4919 footnote_reference_ | generated_ | image_ | inline_ | literal_ |
4920 problematic_ | raw_ | reference_ | strong_ | substitution_reference_ |
4921 subscript_ | superscript_ | target_ | title_reference_
4922 %additional.inline.elements;
4924 The ``%additional.inline.elements;`` parameter entity can be used by
4925 wrapper DTDs to extend ``%inline.elements;``.
4927 Via `%text.model;`_, the ``%inline.elements;`` parameter entity is
4928 indirectly employed in the content models of the following elements:
4929 abbreviation_, acronym_, address_, attribution_, author_, caption_,
4930 classifier_, contact_, copyright_, date_, doctest_block_, emphasis_,
4931 generated_, inline_, line_block_, literal_block_, math_, math_block_,
4933 paragraph_, problematic_, raw_, reference_, revision_, rubric_,
4934 status_, strong_, subscript_, substitution_definition_,
4935 substitution_reference_, subtitle_, superscript_, target_, term_,
4936 title_, title_reference_, version_
4939 ``%reference.atts;``
4940 ====================
4942 The ``%reference.atts;`` parameter entity groups together the refuri_,
4943 refid_, and refname_ attributes.
4952 %additional.reference.atts;
4954 The ``%additional.reference.atts;`` parameter entity can be used by
4955 wrapper DTDs to extend ``%additional.reference.atts;``.
4957 The citation_reference_, footnote_reference_, reference_, and target_
4958 elements directly employ the ``%reference.att;`` parameter entity in
4959 their attribute lists.
4965 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
4966 internal reference to the `ids`_ attribute of another element.
4972 refid_ CDATA #IMPLIED
4974 The title_ and problematic_ elements directly employ the
4975 ``%refid.att;`` parameter entity in their attribute lists.
4977 Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is
4978 indirectly employed in the attribute lists of the citation_reference_,
4979 footnote_reference_, reference_, and target_ elements.
4985 The ``%refname.att;`` parameter entity contains the refname_
4986 attribute, an internal reference to the `names`_ attribute of another
4987 element. On a `target`_ element, ``refname`` indicates an indirect
4988 target which may resolve to either an internal or external
4995 refname_ NMTOKENS #IMPLIED
4997 The substitution_reference_ element directly employs the
4998 ``%refname.att;`` parameter entity in its attribute list.
5000 Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is
5001 indirectly employed in the attribute lists of the citation_reference_,
5002 footnote_reference_, reference_, and target_ elements.
5008 The ``%refuri.att;`` parameter entity contains the refuri_ attribute,
5009 an external reference to a URI/URL.
5015 refuri_ CDATA #IMPLIED
5017 Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is
5018 indirectly employed in the attribute lists of the citation_reference_,
5019 footnote_reference_, reference_, and target_ elements.
5022 ``%section.elements;``
5023 ======================
5025 The ``%section.elements;`` parameter entity contains an OR-list of all
5026 section_-equivalent elements. ``%section.elements;`` is itself
5027 contained within the `%structure.model;`_ parameter entity.
5034 %additional.section.elements;
5036 The ``%additional.section.elements;`` parameter entity can be used
5037 by wrapper DTDs to extend ``%section.elements;``.
5039 Via `%structure.model;`_, the ``%section.elements;`` parameter entity
5040 is indirectly employed in the content models of the document_ and
5044 ``%structure.model;``
5045 =====================
5047 The ``%structure.model;`` parameter entity encapsulates the
5048 hierarchical structure of a document and of its constituent parts.
5049 See the discussion of the `element hierarchy`_ above.
5055 ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*,
5056 ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
5058 Each document_ or section_ contains zero or more body elements,
5059 topics, and/or sidebars, optionally interspersed with single
5060 transitions, followed by zero or more sections (whose contents are
5061 recursively the same as this model) optionally interspersed with
5064 The following restrictions are imposed by this model:
5066 * Transitions must be separated by other elements (body elements,
5067 sections, etc.). In other words, a transition may not be
5068 immediately adjacent to another transition.
5070 * A transition may not occur at the beginning of a document or
5073 An additional restriction, which cannot be expressed in the language
5074 of DTDs, is imposed by software:
5076 * A transition may not occur at the end of a document or section.
5078 The `%structure.model;`_ parameter entity is directly employed in the
5079 content models of the document_ and section_ elements.
5085 The ``%text.model;`` parameter entity is used by many elements to
5086 represent text data mixed with `inline elements`_.
5092 (#PCDATA | `%inline.elements;`_)*
5094 The ``%text.model;`` parameter entity is directly employed in the
5095 content models of the following elements: abbreviation_, acronym_,
5096 address_, author_, caption_, classifier_, contact_, copyright_, date_,
5097 doctest_block_, emphasis_, field_name_, generated_, line_block_,
5098 literal_block_, organization_, paragraph_, problematic_, raw_,
5099 reference_, revision_, status_, strong_, substitution_definition_,
5100 substitution_reference_, subtitle_, target_, term_, title_, version_
5107 indent-tabs-mode: nil
5108 sentence-end-double-space: t