docs/ref/doctree.txt

   1 ============================
   2  The Docutils Document Tree
   3 ============================
   4
   5 A Guide to the Docutils DTD
   6 ***************************
   7
   8 :Author: David Goodger
   9 :Contact: docutils-develop@lists.sourceforge.net
  10 :Revision: $Revision$
  11 :Date: $Date$
  12 :Copyright: This document has been placed in the public domain.
  13
  14
  15 .. contents:: :depth: 1
  16
  17
  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.
  23
  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.
  28
  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
  32 Language (XML)`_.
  33
  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`_.
  38
  39
  40 .. _Docutils: http://docutils.sourceforge.net/
  41 .. _Docutils Generic DTD:
  42 .. _Docutils 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
  49
  50
  51 -------------------
  52  Element Hierarchy
  53 -------------------
  54
  55 .. contents:: :local:
  56
  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. ::
  63
  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 +-----------+------------------+--------------+
  77   | markup) |
  78   +---------+
  79
  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.
  87
  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.
  95
  96
  97 Structural Elements
  98 ===================
  99
 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.
 104
 105 Category members: document_, section_, topic_, sidebar_
 106
 107
 108 Structural Subelements
 109 ----------------------
 110
 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.
 114
 115 Category members: title_, subtitle_, decoration_, docinfo_,
 116 transition_
 117
 118
 119 Bibliographic Elements
 120 ``````````````````````
 121
 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.
 127
 128 Category members: address_, author_, authors_, contact_, copyright_,
 129 date_, field_, organization_, revision_, status_, version_
 130
 131
 132 Decorative Elements
 133 ```````````````````
 134
 135 The decoration_ element is also an optional child of document_.  It
 136 groups together elements used to generate page headers and footers.
 137
 138 Category members: footer_, header_
 139
 140
 141 Body Elements
 142 =============
 143
 144 Body elements are contained within structural elements and compound
 145 body elements.  There are two subcategories of body elements: simple
 146 and compound.
 147
 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_
 155
 156
 157 Simple Body Elements
 158 --------------------
 159
 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".
 163
 164 Category members: comment_, doctest_block_, image_, literal_block_,
 165 math_block_, paragraph_, pending_, raw_, rubric_, substitution_definition_,
 166 target_
 167
 168
 169 Compound Body Elements
 170 ----------------------
 171
 172 Compound body elements contain local substructure (body subelements)
 173 and further body elements.  They do not directly contain text data.
 174
 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_,
 179 tip_, warning_
 180
 181
 182 Body Subelements
 183 ````````````````
 184
 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.).
 191
 192 Category members (simple): attribution_, caption_, classifier_,
 193 colspec_, field_name_, label_, line_, option_argument_,
 194 option_string_, term_
 195
 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_,
 199 thead_
 200
 201
 202 Inline Elements
 203 ===============
 204
 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".
 208
 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_
 213
 214
 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
 218
 219
 220 -------------------
 221  Element Reference
 222 -------------------
 223
 224 .. contents:: :local:
 225               :depth: 1
 226
 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:
 230
 231 * Details (of element relationships and semantics):
 232
 233   - Category: One or more references to the element categories in
 234     `Element Hierarchy`_ above.  Some elements belong to more than one
 235     category.
 236
 237   - Parents: A list of elements which may contain the element.
 238
 239   - Children: A list of elements which may occur within the element.
 240
 241   - Analogues: Describes analogous elements in well-known document
 242     models such as HTML_ or DocBook_.  Lists similarities and
 243     differences.
 244
 245   - Processing: Lists formatting or rendering recommendations for the
 246     element.
 247
 248 * Content Model:
 249
 250   The formal XML content model from the `Docutils DTD`_, followed by:
 251
 252   - Attributes: Describes (or refers to descriptions of) the possible
 253     values and semantics of each attribute.
 254
 255   - Parameter Entities: Lists the parameter entities which directly or
 256     indirectly include the element.
 257
 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:
 265
 266   - Real XML::
 267
 268         <document>
 269         <section ids="a-title" names="a title">
 270         <title>A Title</title>
 271         <paragraph>A paragraph.</paragraph>
 272         </section>
 273         </document>
 274
 275   - Pseudo-XML::
 276
 277         <document>
 278             <section ids="a-title" names="a title">
 279                 <title>
 280                     A Title
 281                 <paragraph>
 282                     A paragraph.
 283
 284 --------------------
 285
 286 Many of the element reference sections below are marked "_`to be
 287 completed`".  Please help complete this document by contributing to
 288 its writing.
 289
 290
 291 ``abbreviation``
 292 ================
 293
 294 `To be completed`_.
 295
 296
 297 ``acronym``
 298 ===========
 299
 300 `To be completed`_.
 301
 302
 303 ``address``
 304 ===========
 305
 306 The ``address`` element holds the surface mailing address information
 307 for the author (individual or group) of the document, or a third-party
 308 contact address.  Its structure is identical to that of the
 309 literal_block_ element: whitespace is significant, especially
 310 newlines.
 311
 312
 313 Details
 314 -------
 315
 316 :Category:
 317     `Bibliographic Elements`_
 318
 319 :Parents:
 320     The following elements may contain ``address``: docinfo_, authors_
 321
 322 :Children:
 323     ``address`` elements contain text data plus `inline elements`_.
 324
 325 :Analogues:
 326     ``address`` is analogous to the DocBook "address" element.
 327
 328 :Processing:
 329     As with the literal_block_ element, newlines and other whitespace
 330     is significant and must be preserved.  However, a monospaced
 331     typeface need not be used.
 332
 333     See also docinfo_.
 334
 335
 336 Content Model
 337 -------------
 338
 339 .. parsed-literal::
 340
 341     `%text.model;`_
 342
 343 :Attributes:
 344     The ``address`` element contains the `common attributes`_ (ids_,
 345     names_, dupnames_, source_, and classes_), plus `xml:space`_.
 346
 347 :Parameter Entities:
 348     The `%bibliographic.elements;`_ parameter entity directly includes
 349     ``address``.
 350
 351
 352 Examples
 353 --------
 354
 355 reStructuredText_ source::
 356
 357     Document Title
 358     ==============
 359
 360     :Address: 123 Example Ave.
 361               Example, EX
 362
 363 Complete pseudo-XML_ result after parsing and applying transforms::
 364
 365     <document ids="document-title" names="document title">
 366         <title>
 367             Document Title
 368         <docinfo>
 369             <address>
 370                 123 Example Ave.
 371                 Example, EX
 372
 373 See docinfo_ for a more complete example, including processing
 374 context.
 375
 376
 377 ``admonition``
 378 ==============
 379
 380 This element is a generic, titled admonition.  Also see the specific
 381 admonition elements Docutils offers (in alphabetical order): caution_,
 382 danger_, error_, hint_, important_, note_, tip_, warning_.
 383
 384
 385 Details
 386 -------
 387
 388 :Category:
 389     `Compound Body Elements`_
 390
 391 :Parents:
 392     All elements employing the `%body.elements;`_ or
 393     `%structure.model;`_ parameter entities in their content models
 394     may contain ``admonition``.
 395
 396 :Children:
 397     ``admonition`` elements begin with a title_ and may contain one or
 398     more `body elements`_.
 399
 400 :Analogues:
 401     ``admonition`` has no direct analogues in common DTDs.  It can be
 402     emulated with primitives and type effects.
 403
 404 :Processing:
 405     Rendered distinctly (inset and/or in a box, etc.).
 406
 407
 408 Content Model
 409 -------------
 410
 411 .. parsed-literal::
 412
 413    (title_, (`%body.elements;`_)+)
 414
 415 :Attributes:
 416     The ``admonition`` element contains only the `common attributes`_:
 417     ids_, names_, dupnames_, source_, and classes_.
 418
 419 :Parameter Entities:
 420     The `%body.elements;`_ parameter entity directly includes
 421     ``admonition``.  The `%structure.model;`_ parameter entity
 422     indirectly includes ``admonition``.
 423
 424
 425 Examples
 426 --------
 427
 428 reStructuredText source::
 429
 430     .. admonition:: And, by the way...
 431
 432        You can make up your own admonition too.
 433
 434 Pseudo-XML_ fragment from simple parsing::
 435
 436     <admonition class="admonition-and-by-the-way">
 437         <title>
 438             And, by the way...
 439         <paragraph>
 440             You can make up your own admonition too.
 441
 442
 443 ``attention``
 444 =============
 445
 446 The ``attention`` element is an admonition, a distinctive and
 447 self-contained notice.  Also see the other admonition elements
 448 Docutils offers (in alphabetical order): caution_, danger_, error_,
 449 hint_, important_, note_, tip_, warning_, and the generic admonition_.
 450
 451
 452 Details
 453 -------
 454
 455 :Category:
 456     `Compound Body Elements`_
 457
 458 :Parents:
 459     All elements employing the `%body.elements;`_ or
 460     `%structure.model;`_ parameter entities in their content models
 461     may contain ``attention``.
 462
 463 :Children:
 464     ``attention`` elements contain one or more `body elements`_.
 465
 466 :Analogues:
 467     ``attention`` has no direct analogues in common DTDs.  It can be
 468     emulated with primitives and type effects.
 469
 470 :Processing:
 471     Rendered distinctly (inset and/or in a box, etc.), with the
 472     generated title "Attention!" (or similar).
 473
 474
 475 Content Model
 476 -------------
 477
 478 .. parsed-literal::
 479
 480    (`%body.elements;`_)+
 481
 482 :Attributes:
 483     The ``attention`` element contains only the `common attributes`_:
 484     ids_, names_, dupnames_, source_, and classes_.
 485
 486 :Parameter Entities:
 487     The `%body.elements;`_ parameter entity directly includes
 488     ``attention``.  The `%structure.model;`_ parameter entity
 489     indirectly includes ``attention``.
 490
 491
 492 Examples
 493 --------
 494
 495 reStructuredText source::
 496
 497     .. Attention:: All your base are belong to us.
 498
 499 Pseudo-XML_ fragment from simple parsing::
 500
 501     <attention>
 502         <paragraph>
 503             All your base are belong to us.
 504
 505
 506 ``attribution``
 507 ===============
 508
 509 `To be completed`_.
 510
 511
 512 ``author``
 513 ==========
 514
 515 The ``author`` element holds the name of the author of the document.
 516
 517
 518 Details
 519 -------
 520
 521 :Category:
 522     `Bibliographic Elements`_
 523
 524 :Parents:
 525     The following elements may contain ``author``: docinfo_, authors_
 526
 527 :Children:
 528     ``author`` elements may contain text data plus `inline elements`_.
 529
 530 :Analogues:
 531     ``author`` is analogous to the DocBook "author" element.
 532
 533 :Processing:
 534     See docinfo_.
 535
 536
 537 Content Model
 538 -------------
 539
 540 .. parsed-literal::
 541
 542     `%text.model;`_
 543
 544 :Attributes:
 545     The ``author`` element contains only the `common attributes`_:
 546     ids_, names_, dupnames_, source_, and classes_.
 547
 548 :Parameter Entities:
 549     The `%bibliographic.elements;`_ parameter entity directly includes
 550     ``author``.
 551
 552
 553 Examples
 554 --------
 555
 556 reStructuredText_ source::
 557
 558     Document Title
 559     ==============
 560
 561     :Author: J. Random Hacker
 562
 563 Complete pseudo-XML_ result after parsing and applying transforms::
 564
 565     <document ids="document-title" names="document title">
 566         <title>
 567             Document Title
 568         <docinfo>
 569             <author>
 570                 J. Random Hacker
 571
 572 See docinfo_ for a more complete example, including processing
 573 context.
 574
 575
 576 ``authors``
 577 ===========
 578
 579 The ``authors`` element is a container for author information for
 580 documents with multiple authors.
 581
 582
 583 Details
 584 -------
 585
 586 :Category:
 587     `Bibliographic Elements`_
 588
 589 :Parents:
 590     Only the docinfo_ element contains ``authors``.
 591
 592 :Children:
 593     ``authors`` elements may contain the following elements: author_,
 594     organization_, address_, contact_
 595
 596 :Analogues:
 597     ``authors`` is analogous to the DocBook "authors" element.
 598
 599 :Processing:
 600     See docinfo_.
 601
 602
 603 Content Model
 604 -------------
 605
 606 .. parsed-literal::
 607
 608     ((author_, organization_?, address_?, contact_?)+)
 609
 610 :Attributes:
 611     The ``authors`` element contains only the `common attributes`_:
 612     ids_, names_, dupnames_, source_, and classes_.
 613
 614 :Parameter Entities:
 615     The `%bibliographic.elements;`_ parameter entity directly includes
 616     ``authors``.
 617
 618
 619 Examples
 620 --------
 621
 622 reStructuredText_ source::
 623
 624     Document Title
 625     ==============
 626
 627     :Authors: J. Random Hacker; Jane Doe
 628
 629 Complete pseudo-XML_ result after parsing and applying transforms::
 630
 631     <document ids="document-title" names="document title">
 632         <title>
 633             Document Title
 634         <docinfo>
 635             <authors>
 636                 <author>
 637                     J. Random Hacker
 638                 <author>
 639                     Jane Doe
 640
 641 In reStructuredText, multiple author's names are separated with
 642 semicolons (";") or commas (","); semicolons take precedence.  There
 643 is currently no way to represent the author's organization, address,
 644 or contact in a reStructuredText "Authors" field.
 645
 646 See docinfo_ for a more complete example, including processing
 647 context.
 648
 649
 650 ``block_quote``
 651 ===============
 652
 653 The ``block_quote`` element is used for quotations set off from the
 654 main text (standalone).
 655
 656
 657 Details
 658 -------
 659
 660 :Category:
 661     `Compound Body Elements`_
 662
 663 :Parents:
 664     All elements employing the `%body.elements;`_ or
 665     `%structure.model;`_ parameter entities in their content models
 666     may contain ``block_quote``.
 667
 668 :Children:
 669     ``block_quote`` elements contain `body elements`_ followed by an
 670     optional attribution_ element.
 671
 672 :Analogues:
 673     ``block_quote`` is analogous to the "blockquote" element in both
 674     HTML and DocBook.
 675
 676 :Processing:
 677     ``block_quote`` elements serve to set their contents off from the
 678     main text, typically with indentation and/or other decoration.
 679
 680
 681 Content Model
 682 -------------
 683
 684 .. parsed-literal::
 685
 686    ((`%body.elements;`_)+, attribution_?)
 687
 688 :Attributes:
 689     The ``block_quote`` element contains only the `common
 690     attributes`_: ids_, names_, dupnames_, source_, and classes_.
 691
 692 :Parameter Entities:
 693     The `%body.elements;`_ parameter entity directly includes
 694     ``block_quote``.  The `%structure.model;`_ parameter entity
 695     indirectly includes ``block_quote``.
 696
 697
 698 Examples
 699 --------
 700
 701 reStructuredText source::
 702
 703     As a great paleontologist once said,
 704
 705         This theory, that is mine, is mine.
 706
 707         -- Anne Elk (Miss)
 708
 709 Pseudo-XML_ fragment from simple parsing::
 710
 711     <paragraph>
 712         As a great paleontologist once said,
 713     <block_quote>
 714         <paragraph>
 715             This theory, that is mine, is mine.
 716         <attribution>
 717             Anne Elk (Miss)
 718
 719
 720 ``bullet_list``
 721 ===============
 722
 723 The ``bullet_list`` element contains list_item_ elements which are
 724 uniformly marked with bullets.  Bullets are typically simple dingbats
 725 (symbols) such as circles and squares.
 726
 727
 728 Details
 729 -------
 730
 731 :Category:
 732     `Compound Body Elements`_
 733
 734 :Parents:
 735     All elements employing the `%body.elements;`_ or
 736     `%structure.model;`_ parameter entities in their content models
 737     may contain ``bullet_list``.
 738
 739 :Children:
 740     ``bullet_list`` elements contain one or more list_item_ elements.
 741
 742 :Analogues:
 743     ``bullet_list`` is analogous to the HTML "ul" element and to the
 744     DocBook "itemizedlist" element.  HTML's "ul" is short for
 745     "unordered list", which we consider to be a misnomer.  "Unordered"
 746     implies that the list items may be randomly rearranged without
 747     affecting the meaning of the list.  Bullet lists *are* often
 748     ordered; the ordering is simply left implicit.
 749
 750 :Processing:
 751     Each list item should begin a new vertical block, prefaced by a
 752     bullet/dingbat.
 753
 754
 755 Content Model
 756 -------------
 757
 758 .. parsed-literal::
 759
 760     (list_item_ +)
 761
 762 :Attributes:
 763     The ``bullet_list`` element contains the `common attributes`_
 764     (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
 765
 766     ``bullet`` is used to record the style of bullet from the input
 767     data.  In documents processed from reStructuredText_, it contains
 768     one of "-", "+", or "*".  It may be ignored in processing.
 769
 770 :Parameter Entities:
 771     The `%body.elements;`_ parameter entity directly includes
 772     ``bullet_list``.  The `%structure.model;`_ parameter entity
 773     indirectly includes ``bullet_list``.
 774
 775
 776 Examples
 777 --------
 778
 779 reStructuredText_ source::
 780
 781     - Item 1, paragraph 1.
 782
 783       Item 1, paragraph 2.
 784
 785     - Item 2.
 786
 787 Pseudo-XML_ fragment from simple parsing::
 788
 789     <bullet_list bullet="-">
 790         <list_item>
 791             <paragraph>
 792                 Item 1, paragraph 1.
 793             <paragraph>
 794                 Item 1, paragraph 2.
 795         <list_item>
 796             <paragraph>
 797                 Item 2.
 798
 799 See list_item_ for another example.
 800
 801
 802 ``caption``
 803 ===========
 804
 805 `To be completed`_.
 806
 807
 808 ``caution``
 809 ===========
 810
 811 The ``caution`` element is an admonition, a distinctive and
 812 self-contained notice.  Also see the other admonition elements
 813 Docutils offers (in alphabetical order): attention_, danger_, error_,
 814 hint_, important_, note_, tip_, warning_, and the generic admonition_.
 815
 816
 817 Details
 818 -------
 819
 820 :Category:
 821     `Compound Body Elements`_
 822
 823 :Parents:
 824     All elements employing the `%body.elements;`_ or
 825     `%structure.model;`_ parameter entities in their content models
 826     may contain ``caution``.
 827
 828 :Children:
 829     ``caution`` elements contain one or more `body elements`_.
 830
 831 :Analogues:
 832     ``caution`` is analogous to the DocBook "caution" element.
 833
 834 :Processing:
 835     Rendered distinctly (inset and/or in a box, etc.), with the
 836     generated title "Caution" (or similar).
 837
 838
 839 Content Model
 840 -------------
 841
 842 .. parsed-literal::
 843
 844    (`%body.elements;`_)+
 845
 846 :Attributes:
 847     The ``caution`` element contains only the `common attributes`_:
 848     ids_, names_, dupnames_, source_, and classes_.
 849
 850 :Parameter Entities:
 851     The `%body.elements;`_ parameter entity directly includes
 852     ``caution``.  The `%structure.model;`_ parameter entity
 853     indirectly includes ``caution``.
 854
 855
 856 Examples
 857 --------
 858
 859 reStructuredText source::
 860
 861     .. Caution:: Don't take any wooden nickels.
 862
 863 Pseudo-XML_ fragment from simple parsing::
 864
 865     <caution>
 866         <paragraph>
 867             Don't take any wooden nickels.
 868
 869
 870 ``citation``
 871 ============
 872
 873 `To be completed`_.
 874
 875
 876 ``citation_reference``
 877 ======================
 878
 879 `To be completed`_.
 880
 881
 882 ``classifier``
 883 ==============
 884
 885 The ``classifier`` element contains the classification or type of the
 886 term_ being defined in a definition_list_.  For example, it can be
 887 used to indicate the type of a variable.
 888
 889
 890 Details
 891 -------
 892
 893 :Category:
 894     `Body Subelements`_ (simple)
 895
 896 :Parents:
 897     Only the definition_list_item_ element contains ``classifier``.
 898
 899 :Children:
 900     ``classifier`` elements may contain text data plus `inline elements`_.
 901
 902 :Analogues:
 903     ``classifier`` has no direct analogues in common DTDs.  It can be
 904     emulated with primitives or type effects.
 905
 906 :Processing:
 907     See definition_list_item_.
 908
 909
 910 Content Model
 911 -------------
 912
 913 .. parsed-literal::
 914
 915     `%text.model;`_
 916
 917 :Attributes:
 918     The ``classifier`` element contains only the `common attributes`_:
 919     ids_, names_, dupnames_, source_, and classes_.
 920
 921
 922 Examples
 923 --------
 924
 925 Here is a hypothetical data dictionary.  reStructuredText_ source::
 926
 927     name : string
 928         Customer name.
 929     i : int
 930         Temporary index variable.
 931
 932 Pseudo-XML_ fragment from simple parsing::
 933
 934     <definition_list>
 935         <definition_list_item>
 936             <term>
 937                 name
 938             <classifier>
 939                 string
 940             <definition>
 941                 <paragraph>
 942                     Customer name.
 943         <definition_list_item>
 944             <term>
 945                 i
 946             <classifier>
 947                 int
 948             <definition>
 949                 <paragraph>
 950                     Temporary index variable.
 951
 952
 953 ``colspec``
 954 ===========
 955
 956 `To be completed`_.
 957
 958
 959 ``comment``
 960 ===========
 961
 962 `To be completed`_.
 963
 964
 965 ``compound``
 966 ============
 967
 968 `To be completed`_.
 969
 970
 971 ``contact``
 972 ===========
 973
 974 The ``contact`` element holds contact information for the author
 975 (individual or group) of the document, or a third-party contact.  It
 976 is typically used for an email or web address.
 977
 978
 979 Details
 980 -------
 981
 982 :Category:
 983     `Bibliographic Elements`_
 984
 985 :Parents:
 986     The following elements may contain ``contact``: docinfo_, authors_
 987
 988 :Children:
 989     ``contact`` elements may contain text data plus `inline
 990     elements`_.
 991
 992 :Analogues:
 993     ``contact`` is analogous to the DocBook "email" element.  The HTML
 994     "address" element serves a similar purpose.
 995
 996 :Processing:
 997     See docinfo_.
 998
 999
1000 Content Model
1001 -------------
1002
1003 .. parsed-literal::
1004
1005     `%text.model;`_
1006
1007 :Attributes:
1008     The ``contact`` element contains only the `common attributes`_:
1009     ids_, names_, dupnames_, source_, and classes_.
1010
1011 :Parameter Entities:
1012     The `%bibliographic.elements;`_ parameter entity directly includes
1013     ``contact``.
1014
1015
1016 Examples
1017 --------
1018
1019 reStructuredText_ source::
1020
1021     Document Title
1022     ==============
1023
1024     :Contact: jrh@example.com
1025
1026 Complete pseudo-XML_ result after parsing and applying transforms::
1027
1028     <document ids="document-title" names="document title">
1029         <title>
1030             Document Title
1031         <docinfo>
1032             <contact>
1033                 <reference refuri="mailto:jrh@example.com">
1034                     jrh@example.com
1035
1036 See docinfo_ for a more complete example, including processing
1037 context.
1038
1039
1040 ``container``
1041 =============
1042
1043 `To be completed`_.
1044
1045
1046 ``copyright``
1047 =============
1048
1049 The ``copyright`` element contains the document's copyright statement.
1050
1051
1052 Details
1053 -------
1054
1055 :Category:
1056     `Bibliographic Elements`_
1057
1058 :Parents:
1059     Only the docinfo_ element contains ``copyright``.
1060
1061 :Children:
1062     ``copyright`` elements may contain text data plus `inline
1063     elements`_.
1064
1065 :Analogues:
1066     ``copyright`` is analogous to the DocBook "copyright" element.
1067
1068 :Processing:
1069     See docinfo_.
1070
1071
1072 Content Model
1073 -------------
1074
1075 .. parsed-literal::
1076
1077     `%text.model;`_
1078
1079 :Attributes:
1080     The ``copyright`` element contains only the `common attributes`_:
1081     ids_, names_, dupnames_, source_, and classes_.
1082
1083 :Parameter Entities:
1084     The `%bibliographic.elements;`_ parameter entity directly includes
1085     ``copyright``.
1086
1087
1088 Examples
1089 --------
1090
1091 reStructuredText_ source::
1092
1093     Document Title
1094     ==============
1095
1096     :Copyright: This document has been placed in the public domain.
1097
1098 Complete pseudo-XML_ result after parsing and applying transforms::
1099
1100     <document ids="document-title" names="document title">
1101         <title>
1102             Document Title
1103         <docinfo>
1104             <copyright>
1105                 This document has been placed in the public domain.
1106
1107 See docinfo_ for a more complete example, including processing
1108 context.
1109
1110
1111 ``danger``
1112 ==========
1113
1114 The ``danger`` element is an admonition, a distinctive and
1115 self-contained notice.  Also see the other admonition elements
1116 Docutils offers (in alphabetical order): attention_, caution_, error_,
1117 hint_, important_, note_, tip_, warning_, and the generic admonition_.
1118
1119
1120 Details
1121 -------
1122
1123 :Category:
1124     `Compound Body Elements`_
1125
1126 :Parents:
1127     All elements employing the `%body.elements;`_ or
1128     `%structure.model;`_ parameter entities in their content models
1129     may contain ``danger``.
1130
1131 :Children:
1132     ``danger`` elements contain one or more `body elements`_.
1133
1134 :Analogues:
1135     ``danger`` has no direct analogues in common DTDs.  It can be
1136     emulated with primitives and type effects.
1137
1138 :Processing:
1139     Rendered distinctly (inset and/or in a box, etc.), with the
1140     generated title "!DANGER!" (or similar).
1141
1142
1143 Content Model
1144 -------------
1145
1146 .. parsed-literal::
1147
1148    (`%body.elements;`_)+
1149
1150 :Attributes:
1151     The ``danger`` element contains only the `common attributes`_:
1152     ids_, names_, dupnames_, source_, and classes_.
1153
1154 :Parameter Entities:
1155     The `%body.elements;`_ parameter entity directly includes
1156     ``danger``.  The `%structure.model;`_ parameter entity
1157     indirectly includes ``danger``.
1158
1159
1160 Examples
1161 --------
1162
1163 reStructuredText source::
1164
1165     .. DANGER:: Mad scientist at work!
1166
1167 Pseudo-XML_ fragment from simple parsing::
1168
1169     <danger>
1170         <paragraph>
1171             Mad scientist at work!
1172
1173
1174 ``date``
1175 ========
1176
1177 The ``date`` element contains the date of publication, release, or
1178 last modification of the document.
1179
1180
1181 Details
1182 -------
1183
1184 :Category:
1185     `Bibliographic Elements`_
1186
1187 :Parents:
1188     Only the docinfo_ element contains ``date``.
1189
1190 :Children:
1191     ``date`` elements may contain text data plus `inline elements`_.
1192
1193 :Analogues:
1194     ``date`` is analogous to the DocBook "date" element.
1195
1196 :Processing:
1197     Often used with the RCS/CVS keyword "Date".  See docinfo_.
1198
1199
1200 Content Model
1201 -------------
1202
1203 .. parsed-literal::
1204
1205     `%text.model;`_
1206
1207 :Attributes:
1208     The ``date`` element contains only the `common attributes`_:
1209     ids_, names_, dupnames_, source_, and classes_.
1210
1211 :Parameter Entities:
1212     The `%bibliographic.elements;`_ parameter entity directly includes
1213     ``date``.
1214
1215
1216 Examples
1217 --------
1218
1219 reStructuredText_ source::
1220
1221     Document Title
1222     ==============
1223
1224     :Date: 2002-08-20
1225
1226 Complete pseudo-XML_ result after parsing and applying transforms::
1227
1228     <document ids="document-title" names="document title">
1229         <title>
1230             Document Title
1231         <docinfo>
1232             <date>
1233                 2002-08-20
1234
1235 See docinfo_ for a more complete example, including processing
1236 context.
1237
1238
1239 ``decoration``
1240 ==============
1241
1242 The ``decoration`` element is a container for header_ and footer_
1243 elements and potential future extensions.  These elements are used for
1244 notes, time/datestamp, processing information, etc.
1245
1246
1247 Details
1248 -------
1249
1250 :Category:
1251     `Structural Subelements`_
1252
1253 :Parents:
1254     Only the document_ element contains ``decoration``.
1255
1256 :Children:
1257     ``decoration`` elements may contain `decorative elements`_.
1258
1259 :Analogues:
1260     There are no direct analogies to ``decoration`` in HTML or in
1261     DocBook.  Equivalents are typically constructed from primitives
1262     and/or generated by the processing system.
1263
1264 :Processing:
1265     See the individual `decorative elements`_.
1266
1267
1268 Content Model
1269 -------------
1270
1271 .. parsed-literal::
1272
1273     (header_?, footer_?)
1274
1275 Although the content model doesn't specifically require contents, no
1276 empty ``decoration`` elements are ever created.
1277
1278 :Attributes:
1279     The ``decoration`` element contains only the `common attributes`_:
1280     ids_, names_, dupnames_, source_, and classes_.
1281
1282
1283 Examples
1284 --------
1285
1286 reStructuredText_ source::
1287
1288     A paragraph.
1289
1290 Complete pseudo-XML_ result after parsing and applying transforms,
1291 assuming that the datestamp command-line option or configuration
1292 setting has been supplied::
1293
1294     <document>
1295         <decoration>
1296             <footer>
1297                 <paragraph>
1298                     Generated on: 2002-08-20.
1299         <paragraph>
1300             A paragraph.
1301
1302
1303 ``definition``
1304 ==============
1305
1306 The ``definition`` element is a container for the body elements used
1307 to define a term_ in a definition_list_.
1308
1309
1310 Details
1311 -------
1312
1313 :Category:
1314     `Body Subelements`_ (compound)
1315
1316 :Parents:
1317     Only definition_list_item_ elements contain ``definition``.
1318
1319 :Children:
1320     ``definition`` elements may contain `body elements`_.
1321
1322 :Analogues:
1323     ``definition`` is analogous to the HTML "dd" element and to the
1324     DocBook "listitem" element (inside a "variablelistentry" element).
1325
1326 :Processing:
1327     See definition_list_item_.
1328
1329
1330 Content Model
1331 -------------
1332
1333 .. parsed-literal::
1334
1335     (`%body.elements;`_)+
1336
1337 :Attributes:
1338     The ``definition`` element contains only the `common attributes`_:
1339     ids_, names_, dupnames_, source_, and classes_.
1340
1341
1342 Examples
1343 --------
1344
1345 See the examples for the definition_list_, definition_list_item_, and
1346 classifier_ elements.
1347
1348
1349 ``definition_list``
1350 ===================
1351
1352 The ``definition_list`` element contains a list of terms and their
1353 definitions.  It can be used for glossaries or dictionaries, to
1354 describe or classify things, for dialogues, or to itemize subtopics
1355 (such as in this reference).
1356
1357
1358 Details
1359 -------
1360
1361 :Category:
1362     `Compound Body Elements`_
1363
1364 :Parents:
1365     All elements employing the `%body.elements;`_ or
1366     `%structure.model;`_ parameter entities in their content models
1367     may contain ``definition_list``.
1368
1369 :Children:
1370     ``definition_list`` elements contain one or more
1371     definition_list_item_ elements.
1372
1373 :Analogues:
1374     ``definition_list`` is analogous to the HTML "dl" element and to
1375     the DocBook "variablelist" element.
1376
1377 :Processing:
1378     See definition_list_item_.
1379
1380
1381 Content Model
1382 -------------
1383
1384 .. parsed-literal::
1385
1386     (definition_list_item_ +)
1387
1388 :Attributes:
1389     The ``definition_list`` element contains only the `common
1390     attributes`_: ids_, names_, dupnames_, source_, and classes_.
1391
1392 :Parameter Entities:
1393     The `%body.elements;`_ parameter entity directly includes
1394     ``definition_list``.  The `%structure.model;`_ parameter entity
1395     indirectly includes ``definition_list``.
1396
1397
1398 Examples
1399 --------
1400
1401 reStructuredText_ source::
1402
1403     Term
1404       Definition.
1405
1406     Term : classifier
1407         The ' : ' indicates a classifier in
1408         definition list item terms only.
1409
1410 Pseudo-XML_ fragment from simple parsing::
1411
1412     <definition_list>
1413         <definition_list_item>
1414             <term>
1415                 Term
1416             <definition>
1417                 <paragraph>
1418                     Definition.
1419         <definition_list_item>
1420             <term>
1421                 Term
1422             <classifier>
1423                 classifier
1424             <definition>
1425                 <paragraph>
1426                     The ' : ' indicates a classifier in
1427                     definition list item terms only.
1428
1429 See definition_list_item_ and classifier_ for further examples.
1430
1431
1432 ``definition_list_item``
1433 ========================
1434
1435 The ``definition_list_item`` element contains a single
1436 term_/definition_ pair (with optional classifier_).
1437
1438
1439 Details
1440 -------
1441
1442 :Category:
1443     `Body Subelements`_ (compound)
1444
1445 :Parents:
1446     Only the definition_list_ element contains
1447     ``definition_list_item``.
1448
1449 :Children:
1450     ``definition_list_item`` elements each contain a single term_,
1451     an optional classifier_, and a definition_.
1452
1453 :Analogues:
1454     ``definition_list_item`` is analogous to the DocBook
1455     "variablelistentry" element.
1456
1457 :Processing:
1458     The optional classifier_ can be rendered differently from the
1459     term_.  They should be separated visually, typically by spaces
1460     plus a colon or dash.
1461
1462
1463 Content Model
1464 -------------
1465
1466 .. parsed-literal::
1467
1468     (term_, classifier_?, definition_)
1469
1470 :Attributes:
1471     The ``definition_list_item`` element contains only the `common
1472     attributes`_: ids_, names_, dupnames_, source_, and classes_.
1473
1474
1475 Examples
1476 --------
1477
1478 reStructuredText_ source::
1479
1480     Tyrannosaurus Rex : carnivore
1481         Big and scary; the "Tyrant King".
1482
1483     Brontosaurus : herbivore
1484         All brontosauruses are thin at one end,
1485         much much thicker in the middle
1486         and then thin again at the far end.
1487
1488         -- Anne Elk (Miss)
1489
1490 Pseudo-XML_ fragment from simple parsing::
1491
1492     <definition_list>
1493         <definition_list_item>
1494             <term>
1495                 Tyrannosaurus Rex
1496             <classifier>
1497                 carnivore
1498             <definition>
1499                 <paragraph>
1500                     Big and scary; the "Tyrant King".
1501         <definition_list_item>
1502             <term>
1503                 Brontosaurus
1504             <classifier>
1505                 herbivore
1506             <definition>
1507                 <paragraph>
1508                     All brontosauruses are thin at one end,
1509                     much much thicker in the middle
1510                     and then thin again at the far end.
1511                 <paragraph>
1512                     -- Anne Elk (Miss)
1513
1514 See definition_list_ and classifier_ for further examples.
1515
1516
1517 ``description``
1518 ===============
1519
1520 The ``description`` element contains body elements, describing the
1521 purpose or effect of a command-line option or group of options.
1522
1523
1524 Details
1525 -------
1526
1527 :Category:
1528     `Body Subelements`_
1529
1530 :Parents:
1531     Only the option_list_item_ element contains ``description``.
1532
1533 :Children:
1534     ``description`` elements may contain `body elements`_.
1535
1536 :Analogues:
1537     ``description`` has no direct analogues in common DTDs.
1538
1539 :Processing:
1540     See option_list_.
1541
1542
1543 Content Model
1544 -------------
1545
1546 .. parsed-literal::
1547
1548    (`%body.elements;`_)+
1549
1550 :Attributes:
1551     The ``description`` element contains only the `common attributes`_:
1552     ids_, names_, dupnames_, source_, and classes_.
1553
1554
1555 Examples
1556 --------
1557
1558 See the examples for the option_list_ element.
1559
1560
1561 ``docinfo``
1562 ===========
1563
1564 The ``docinfo`` element is a container for document bibliographic
1565 data, or meta-data (data about the document).  It corresponds to the
1566 front matter of a book, such as the title page and copyright page.
1567
1568
1569 Details
1570 -------
1571
1572 :Category:
1573     `Structural Subelements`_
1574
1575 :Parents:
1576     Only the document_ element contains ``docinfo``.
1577
1578 :Children:
1579     ``docinfo`` elements contain `bibliographic elements`_.
1580
1581 :Analogues:
1582     ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1583     etc.).  There are no directly analogous HTML elements; the "meta"
1584     element carries some of the same information, albeit invisibly.
1585
1586 :Processing:
1587     The ``docinfo`` element may be rendered as a two-column table or
1588     in other styles.  It may even be invisible or omitted from the
1589     processed output.  Meta-data may be extracted from ``docinfo``
1590     children; for example, HTML ``<meta>`` tags may be constructed.
1591
1592     When Docutils_ transforms a reStructuredText_ field_list_ into a
1593     ``docinfo`` element (see the examples below), RCS/CVS keywords are
1594     normally stripped from simple (one paragraph) field bodies.  For
1595     complete details, please see `RCS Keywords`_ in the
1596     `reStructuredText Markup Specification`_.
1597
1598     .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
1599
1600
1601 Content Model
1602 -------------
1603
1604 .. parsed-literal::
1605
1606     (`%bibliographic.elements;`_)+
1607
1608 :Attributes:
1609     The ``docinfo`` element contains only the `common attributes`_:
1610     ids_, names_, dupnames_, source_, and classes_.
1611
1612
1613 Examples
1614 --------
1615
1616 Docinfo is represented in reStructuredText_ by a field_list_ in a
1617 bibliographic context: the first non-comment element of a document_,
1618 after any document title_/subtitle_.  The field list is transformed
1619 into a ``docinfo`` element and its children by a transform.  Source::
1620
1621     Docinfo Example
1622     ===============
1623
1624     :Author: J. Random Hacker
1625     :Contact: jrh@example.com
1626     :Date: 2002-08-18
1627     :Status: Work In Progress
1628     :Version: 1
1629     :Filename: $RCSfile$
1630     :Copyright: This document has been placed in the public domain.
1631
1632 Complete pseudo-XML_ result after parsing and applying transforms::
1633
1634     <document ids="docinfo-example" names="docinfo example">
1635         <title>
1636             Docinfo Example
1637         <docinfo>
1638             <author>
1639                 J. Random Hacker
1640             <contact>
1641                 <reference refuri="mailto:jrh@example.com">
1642                     jrh@example.com
1643             <date>
1644                 2002-08-18
1645             <status>
1646                 Work In Progress
1647             <version>
1648                 1
1649             <field>
1650                 <field_name>
1651                     Filename
1652                 <field_body>
1653                     <paragraph>
1654                         doctree.txt
1655             <copyright>
1656                 This document has been placed in the public domain.
1657
1658 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1659 generic ``field`` element.  Also note that the "RCSfile" keyword
1660 syntax has been stripped from the "Filename" data.
1661
1662 See field_list_ for an example in a non-bibliographic context.  Also
1663 see the individual examples for the various `bibliographic elements`_.
1664
1665
1666 ``doctest_block``
1667 =================
1668
1669 The ``doctest_block`` element is a Python-specific variant of
1670 literal_block_.  It is a block of text where line breaks and
1671 whitespace are significant and must be preserved.  ``doctest_block``
1672 elements are used for interactive Python interpreter sessions, which
1673 are distinguished by their input prompt: ``>>>``.  They are meant to
1674 illustrate usage by example, and provide an elegant and powerful
1675 testing environment via the `doctest module`_ in the Python standard
1676 library.
1677
1678 .. _doctest module:
1679    http://www.python.org/doc/current/lib/module-doctest.html
1680
1681
1682 Details
1683 -------
1684
1685 :Category:
1686     `Simple Body Elements`_
1687
1688 :Parents:
1689     All elements employing the `%body.elements;`_ or
1690     `%structure.model;`_ parameter entities in their content models
1691     may contain ``doctest_block``.
1692
1693 :Children:
1694     ``doctest_block`` elements may contain text data plus `inline
1695     elements`_.
1696
1697 :Analogues:
1698     ``doctest_block`` is analogous to the HTML "pre" element and to
1699     the DocBook "programlisting" and "screen" elements.
1700
1701 :Processing:
1702     As with literal_block_, ``doctest_block`` elements are typically
1703     rendered in a monospaced typeface.  It is crucial that all
1704     whitespace and line breaks are preserved in the rendered form.
1705
1706
1707 Content Model
1708 -------------
1709
1710 .. parsed-literal::
1711
1712    `%text.model;`_
1713
1714 :Attributes:
1715     The ``doctest_block`` element contains the `common attributes`_
1716     (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
1717
1718 :Parameter Entities:
1719     The `%body.elements;`_ parameter entity directly includes
1720     ``doctest_block``.  The `%structure.model;`_ parameter entity
1721     indirectly includes ``doctest_block``.
1722
1723
1724 Examples
1725 --------
1726
1727 reStructuredText source::
1728
1729     This is an ordinary paragraph.
1730
1731     >>> print 'this is a Doctest block'
1732     this is a Doctest block
1733
1734 Pseudo-XML_ fragment from simple parsing::
1735
1736     <paragraph>
1737         This is an ordinary paragraph.
1738     <doctest_block xml:space="preserve">
1739         >>> print 'this is a Doctest block'
1740         this is a Doctest block
1741
1742
1743 ``document``
1744 ============
1745
1746 The ``document`` element is the root (topmost) element of the Docutils
1747 document tree.  ``document`` is the direct or indirect ancestor of
1748 every other element in the tree.  It encloses the entire document
1749 tree.  It is the starting point for a document.
1750
1751
1752 Details
1753 -------
1754
1755 :Category:
1756     `Structural Elements`_
1757
1758 :Parents:
1759     The ``document`` element has no parents.
1760
1761 :Children:
1762     ``document`` elements may contain `structural subelements`_,
1763     `structural elements`_, and `body elements`_.
1764
1765 :Analogues:
1766     ``document`` is analogous to the HTML "html" element and to
1767     several DocBook elements such as "book".
1768
1769
1770 Content Model
1771 -------------
1772
1773 .. parsed-literal::
1774
1775     ( (title_, subtitle_?)?,
1776       decoration_?,
1777       (docinfo_, transition_?)?,
1778       `%structure.model;`_ )
1779
1780 Depending on the source of the data and the stage of processing, the
1781 "document" may not initially contain a "title".  A document title is
1782 not directly representable in reStructuredText_.  Instead, a lone
1783 top-level section may have its title promoted to become the document
1784 title_, and similarly for a lone second-level (sub)section's title to
1785 become the document subtitle_.
1786
1787 The contents of "decoration_" may be specified in a document,
1788 constructed programmatically, or both.  The "docinfo_" may be
1789 transformed from an initial field_list_.
1790
1791 See the `%structure.model;`_ parameter entity for details of the body
1792 of a ``document``.
1793
1794 :Attributes:
1795     The ``document`` element contains the `common attributes`_ (ids_,
1796     names_, dupnames_, source_, and classes_), plus an optional title__
1797     attribute which stores the document title metadata.
1798
1799     __ `title (attribute)`_
1800
1801
1802 Examples
1803 --------
1804
1805 reStructuredText_ source::
1806
1807     A Title
1808     =======
1809
1810     A paragraph.
1811
1812 Complete pseudo-XML_ result from simple parsing::
1813
1814     <document>
1815         <section ids="a-title" names="a title">
1816             <title>
1817                 A Title
1818             <paragraph>
1819                 A paragraph.
1820
1821 After applying transforms, the section title is promoted to become the
1822 document title::
1823
1824     <document ids="a-title" names="a title">
1825         <title>
1826             A Title
1827         <paragraph>
1828             A paragraph.
1829
1830
1831 ``emphasis``
1832 ============
1833
1834 `To be completed`_.
1835
1836
1837 ``entry``
1838 =========
1839
1840 `To be completed`_.
1841
1842
1843 ``enumerated_list``
1844 ===================
1845
1846 The ``enumerated_list`` element contains list_item_ elements which are
1847 uniformly marked with enumerator labels.
1848
1849
1850 Details
1851 -------
1852
1853 :Category:
1854     `Compound Body Elements`_
1855
1856 :Parents:
1857     All elements employing the `%body.elements;`_ or
1858     `%structure.model;`_ parameter entities in their content models
1859     may contain ``enumerated_list``.
1860
1861 :Children:
1862     ``enumerated_list`` elements contain one or more list_item_
1863     elements.
1864
1865 :Analogues:
1866     ``enumerated_list`` is analogous to the HTML "ol" element and to
1867     the DocBook "orderedlist" element.
1868
1869 :Processing:
1870     Each list item should begin a new vertical block, prefaced by a
1871     enumeration marker (such as "1.").
1872
1873
1874 Content Model
1875 -------------
1876
1877 .. parsed-literal::
1878
1879     (list_item_ +)
1880
1881 :Attributes:
1882     The ``enumerated_list`` element contains the `common attributes`_
1883     (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
1884     prefix_, suffix_, and start_.
1885
1886     ``enumtype`` is used to record the intended enumeration sequence,
1887     one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1888     "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1889     mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1890     MMMMCMXCIX [4999]).
1891
1892     ``prefix`` stores the formatting characters used before the
1893     enumerator.  In documents originating from reStructuredText_ data,
1894     it will contain either "" (empty string) or "(" (left
1895     parenthesis).  It may or may not affect processing.
1896
1897     ``suffix`` stores the formatting characters used after the
1898     enumerator.  In documents originating from reStructuredText_ data,
1899     it will contain either "." (period) or ")" (right parenthesis).
1900     Depending on the capabilities of the output format, this attribute
1901     may or may not affect processing.
1902
1903     ``start`` contains the ordinal value of the first item in the
1904     list, in decimal.  For lists beginning at value 1 ("1", "a", "A",
1905     "i", or "I"), this attribute may be omitted.
1906
1907 :Parameter Entities:
1908     The `%body.elements;`_ parameter entity directly includes
1909     ``enumerated_list``.  The `%structure.model;`_ parameter entity
1910     indirectly includes ``enumerated_list``.
1911
1912
1913 Examples
1914 --------
1915
1916 reStructuredText_ source::
1917
1918     1. Item 1.
1919
1920        (A) Item A.
1921        (B) Item B.
1922        (C) Item C.
1923
1924     2. Item 2.
1925
1926 Pseudo-XML_ fragment from simple parsing::
1927
1928     <enumerated_list enumtype="arabic" prefix="" suffix=".">
1929         <list_item>
1930             <paragraph>
1931                 Item 1.
1932             <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1933                 <list_item>
1934                     <paragraph>
1935                         Item A.
1936                 <list_item>
1937                     <paragraph>
1938                         Item B.
1939                 <list_item>
1940                     <paragraph>
1941                         Item C.
1942         <list_item>
1943             <paragraph>
1944                 Item 2.
1945
1946 See list_item_ for another example.
1947
1948
1949 ``error``
1950 =========
1951
1952 The ``error`` element is an admonition, a distinctive and
1953 self-contained notice.  Also see the other admonition elements
1954 Docutils offers (in alphabetical order): attention_, caution_,
1955 danger_, hint_, important_, note_, tip_, warning_, and the generic
1956 admonition_.
1957
1958
1959 Details
1960 -------
1961
1962 :Category:
1963     `Compound Body Elements`_
1964
1965 :Parents:
1966     All elements employing the `%body.elements;`_ or
1967     `%structure.model;`_ parameter entities in their content models
1968     may contain ``error``.
1969
1970 :Children:
1971     ``error`` elements contain one or more `body elements`_.
1972
1973 :Analogues:
1974     ``error`` has no direct analogues in common DTDs.  It can be
1975     emulated with primitives and type effects.
1976
1977 :Processing:
1978     Rendered distinctly (inset and/or in a box, etc.), with the
1979     generated title "Error" (or similar).
1980
1981
1982 Content Model
1983 -------------
1984
1985 .. parsed-literal::
1986
1987    (`%body.elements;`_)+
1988
1989 :Attributes:
1990     The ``error`` element contains only the `common attributes`_: ids_,
1991     names_, dupnames_, source_, and classes_.
1992
1993 :Parameter Entities:
1994     The `%body.elements;`_ parameter entity directly includes
1995     ``error``.  The `%structure.model;`_ parameter entity indirectly
1996     includes ``error``.
1997
1998
1999 Examples
2000 --------
2001
2002 reStructuredText source::
2003
2004     .. Error:: Does not compute.
2005
2006 Pseudo-XML_ fragment from simple parsing::
2007
2008     <error>
2009         <paragraph>
2010             Does not compute.
2011
2012
2013 ``field``
2014 =========
2015
2016 The ``field`` element contains a pair of field_name_ and field_body_
2017 elements.
2018
2019
2020 Details
2021 -------
2022
2023 :Category:
2024     `Body Subelements`_
2025
2026 :Parents:
2027     The following elements may contain ``field``: docinfo_,
2028     field_list_
2029
2030 :Children:
2031     Each ``field`` element contains one field_name_ and one
2032     field_body_ element.
2033
2034 :Analogues:
2035     ``field`` has no direct analogues in common DTDs.
2036
2037 :Processing:
2038     See field_list_.
2039
2040
2041 Content Model
2042 -------------
2043
2044 .. parsed-literal::
2045
2046    (field_name_, field_body_)
2047
2048 :Attributes:
2049     The ``field`` element contains only the `common attributes`_:
2050     ids_, names_, dupnames_, source_, and classes_.
2051
2052 :Parameter Entities:
2053     The `%bibliographic.elements;`_ parameter entity directly includes
2054     ``field``.
2055
2056
2057 Examples
2058 --------
2059
2060 See the examples for the field_list_ and docinfo_ elements.
2061
2062
2063 ``field_body``
2064 ==============
2065
2066 The ``field_body`` element contains body elements.  It is analogous to
2067 a database field's data.
2068
2069
2070 Details
2071 -------
2072
2073 :Category:
2074     `Body Subelements`_
2075
2076 :Parents:
2077     Only the field_ element contains ``field_body``.
2078
2079 :Children:
2080     ``field_body`` elements may contain `body elements`_.
2081
2082 :Analogues:
2083     ``field_body`` has no direct analogues in common DTDs.
2084
2085 :Processing:
2086     See field_list_.
2087
2088
2089 Content Model
2090 -------------
2091
2092 .. parsed-literal::
2093
2094    (`%body.elements;`_)*
2095
2096 :Attributes:
2097     The ``field_body`` element contains only the `common attributes`_:
2098     ids_, names_, dupnames_, source_, and classes_.
2099
2100
2101 Examples
2102 --------
2103
2104 See the examples for the field_list_ and docinfo_ elements.
2105
2106
2107 ``field_list``
2108 ==============
2109
2110 The ``field_list`` element contains two-column table-like structures
2111 resembling database records (label & data pairs).  Field lists are
2112 often meant for further processing.  In reStructuredText_, field lists
2113 are used to represent bibliographic fields (contents of the docinfo_
2114 element) and directive options.
2115
2116
2117 Details
2118 -------
2119
2120 :Category:
2121     `Compound Body Elements`_
2122
2123 :Parents:
2124     All elements employing the `%body.elements;`_ or
2125     `%structure.model;`_ parameter entities in their content models
2126     may contain ``field_list``.
2127
2128 :Children:
2129     ``field_list`` elements contain one or more field_ elements.
2130
2131 :Analogues:
2132     ``field_list`` has no direct analogues in common DTDs.  It can be
2133     emulated with primitives such as tables.
2134
2135 :Processing:
2136     A ``field_list`` is typically rendered as a two-column list, where
2137     the first column contains "labels" (usually with a colon suffix).
2138     However, field lists are often used for extension syntax or
2139     special processing.  Such structures do not survive as field lists
2140     to be rendered.
2141
2142
2143 Content Model
2144 -------------
2145
2146 .. parsed-literal::
2147
2148    (field_ +)
2149
2150 :Attributes:
2151     The ``field_list`` element contains only the `common attributes`_:
2152     ids_, names_, dupnames_, source_, and classes_.
2153
2154 :Parameter Entities:
2155     The `%body.elements;`_ parameter entity directly includes
2156     ``field_list``.  The `%structure.model;`_ parameter entity
2157     indirectly includes ``field_list``.
2158
2159
2160 Examples
2161 --------
2162
2163 reStructuredText_ source::
2164
2165     :Author: Me
2166     :Version: 1
2167     :Date: 2001-08-11
2168     :Parameter i: integer
2169
2170 Pseudo-XML_ fragment from simple parsing::
2171
2172     <field_list>
2173         <field>
2174             <field_name>
2175                 Author
2176             <field_body>
2177                 <paragraph>
2178                     Me
2179         <field>
2180             <field_name>
2181                 Version
2182             <field_body>
2183                 <paragraph>
2184                     1
2185         <field>
2186             <field_name>
2187                 Date
2188             <field_body>
2189                 <paragraph>
2190                     2001-08-11
2191         <field>
2192             <field_name>
2193                 Parameter i
2194             <field_body>
2195                 <paragraph>
2196                     integer
2197
2198
2199 ``field_name``
2200 ==============
2201
2202 The ``field_name`` element contains text; it is analogous to a
2203 database field's name.
2204
2205
2206 Details
2207 -------
2208
2209 :Category:
2210     `Body Subelements`_ (simple)
2211
2212 :Parents:
2213     Only the field_ element contains ``field_name``.
2214
2215 :Children:
2216     ``field_name`` elements may contain text data plus `inline elements`_.
2217
2218 :Analogues:
2219     ``field_name`` has no direct analogues in common DTDs.
2220
2221 :Processing:
2222     See field_list_.
2223
2224
2225 Content Model
2226 -------------
2227
2228 .. parsed-literal::
2229
2230     `%text.model;`_
2231
2232 :Attributes:
2233     The ``field_name`` element contains only the `common attributes`_:
2234     ids_, names_, dupnames_, source_, and classes_.
2235
2236
2237 Examples
2238 --------
2239
2240 See the examples for the field_list_ and docinfo_ elements.
2241
2242
2243 ``figure``
2244 ==========
2245
2246 `To be completed`_.
2247
2248
2249 ``footer``
2250 ==========
2251
2252 The ``footer`` element is a container element whose contents are meant
2253 to appear at the bottom of a web page, or repeated at the bottom of
2254 every printed page.  The ``footer`` element may contain processing
2255 information (datestamp, a link to Docutils_, etc.) as well as custom
2256 content.
2257
2258
2259 Details
2260 -------
2261
2262 :Category:
2263     `Decorative Elements`_
2264
2265 :Parents:
2266     Only the decoration_ element contains ``footer``.
2267
2268 :Children:
2269     ``footer`` elements may contain `body elements`_.
2270
2271 :Analogues:
2272     There are no direct analogies to ``footer`` in HTML or DocBook.
2273     Equivalents are typically constructed from primitives and/or
2274     generated by the processing system.
2275
2276
2277 Content Model
2278 -------------
2279
2280 .. parsed-literal::
2281
2282     (`%body.elements;`_)+
2283
2284 :Attributes:
2285     The ``footer`` element contains only the `common attributes`_:
2286     ids_, names_, dupnames_, source_, and classes_.
2287
2288
2289 Examples
2290 --------
2291
2292 reStructuredText_ source::
2293
2294     A paragraph.
2295
2296 Complete pseudo-XML_ result after parsing and applying transforms,
2297 assuming that the datestamp command-line option or configuration
2298 setting has been supplied::
2299
2300     <document>
2301         <decoration>
2302             <footer>
2303                 <paragraph>
2304                     Generated on: 2002-08-20.
2305         <paragraph>
2306             A paragraph.
2307
2308
2309 ``footnote``
2310 ============
2311
2312 `To be completed`_.
2313
2314
2315 ``footnote_reference``
2316 ======================
2317
2318 `To be completed`_.
2319
2320
2321 ``generated``
2322 =============
2323
2324 Docutils wraps ``generated`` elements around text that is inserted
2325 (generated) by Docutils; i.e., text that was not in the document, like
2326 section numbers inserted by the "sectnum" directive.
2327
2328 `To be completed`_.
2329
2330
2331 ``header``
2332 ==========
2333
2334 The ``header`` element is a container element whose contents are meant
2335 to appear at the top of a web page, or at the top of every printed
2336 page.
2337
2338
2339 Details
2340 -------
2341
2342 :Category:
2343     `Decorative Elements`_
2344
2345 :Parents:
2346     Only the decoration_ element contains ``header``.
2347
2348 :Children:
2349     ``header`` elements may contain `body elements`_.
2350
2351 :Analogues:
2352     There are no direct analogies to ``header`` in HTML or DocBook.
2353     Equivalents are typically constructed from primitives and/or
2354     generated by the processing system.
2355
2356
2357 Content Model
2358 -------------
2359
2360 .. parsed-literal::
2361
2362     (`%body.elements;`_)+
2363
2364 :Attributes:
2365     The ``header`` element contains only the `common attributes`_:
2366     ids_, names_, dupnames_, source_, and classes_.
2367
2368
2369 Examples
2370 --------
2371
2372 reStructuredText source fragment::
2373
2374     .. header:: This space for rent.
2375
2376 Pseudo-XML_ fragment from simple parsing::
2377
2378     <document>
2379         <decoration>
2380             <header>
2381                 <paragraph>
2382                     This space for rent.
2383
2384
2385 ``hint``
2386 ========
2387
2388 The ``hint`` element is an admonition, a distinctive and
2389 self-contained notice.  Also see the other admonition elements
2390 Docutils offers (in alphabetical order): attention_, caution_,
2391 danger_, error_, important_, note_, tip_, warning_, and the generic
2392 admonition_.
2393
2394
2395 Details
2396 -------
2397
2398 :Category:
2399     `Compound Body Elements`_
2400
2401 :Parents:
2402     All elements employing the `%body.elements;`_ or
2403     `%structure.model;`_ parameter entities in their content models
2404     may contain ``hint``.
2405
2406 :Children:
2407     ``hint`` elements contain one or more `body elements`_.
2408
2409 :Analogues:
2410     ``hint`` has no direct analogues in common DTDs.  It can be
2411     emulated with primitives and type effects.
2412
2413 :Processing:
2414     Rendered distinctly (inset and/or in a box, etc.), with the
2415     generated title "Hint" (or similar).
2416
2417
2418 Content Model
2419 -------------
2420
2421 .. parsed-literal::
2422
2423    (`%body.elements;`_)+
2424
2425 :Attributes:
2426     The ``hint`` element contains only the `common attributes`_: ids_,
2427     names_, dupnames_, source_, and classes_.
2428
2429 :Parameter Entities:
2430     The `%body.elements;`_ parameter entity directly includes
2431     ``hint``.  The `%structure.model;`_ parameter entity indirectly
2432     includes ``hint``.
2433
2434
2435 Examples
2436 --------
2437
2438 reStructuredText source::
2439
2440     .. Hint:: It's bigger than a bread box.
2441
2442 Pseudo-XML_ fragment from simple parsing::
2443
2444     <hint>
2445         <paragraph>
2446             It's bigger than a bread box.
2447
2448
2449 ``image``
2450 =========
2451
2452 `To be completed`_.
2453
2454
2455 ``important``
2456 =============
2457
2458 The ``important`` element is an admonition, a distinctive and
2459 self-contained notice.  Also see the other admonition elements
2460 Docutils offers (in alphabetical order): attention_, caution_,
2461 danger_, error_, hint_, note_, tip_, warning_, and the generic
2462 admonition_.
2463
2464
2465 Details
2466 -------
2467
2468 :Category:
2469     `Compound Body Elements`_
2470
2471 :Parents:
2472     All elements employing the `%body.elements;`_ or
2473     `%structure.model;`_ parameter entities in their content models
2474     may contain ``important``.
2475
2476 :Children:
2477     ``important`` elements contain one or more `body elements`_.
2478
2479 :Analogues:
2480     ``important`` is analogous to the DocBook "important" element.
2481
2482 :Processing:
2483     Rendered distinctly (inset and/or in a box, etc.), with the
2484     generated title "Important" (or similar).
2485
2486
2487 Content Model
2488 -------------
2489
2490 .. parsed-literal::
2491
2492    (`%body.elements;`_)+
2493
2494 :Attributes:
2495     The ``important`` element contains only the `common attributes`_:
2496     ids_, names_, dupnames_, source_, and classes_.
2497
2498 :Parameter Entities:
2499     The `%body.elements;`_ parameter entity directly includes
2500     ``important``.  The `%structure.model;`_ parameter entity
2501     indirectly includes ``important``.
2502
2503
2504 Examples
2505 --------
2506
2507 reStructuredText source::
2508
2509     .. Important::
2510
2511        * Wash behind your ears.
2512        * Clean up your room.
2513        * Back up your data.
2514        * Call your mother.
2515
2516 Pseudo-XML_ fragment from simple parsing::
2517
2518     <important>
2519         <bullet_list>
2520             <list_item>
2521                 <paragraph>
2522                     Wash behind your ears.
2523             <list_item>
2524                 <paragraph>
2525                     Clean up your room.
2526             <list_item>
2527                 <paragraph>
2528                     Back up your data.
2529             <list_item>
2530                 <paragraph>
2531                     Call your mother.
2532
2533
2534 ``inline``
2535 ==========
2536
2537 `To be completed`_.
2538
2539
2540 ``label``
2541 =========
2542
2543 `To be completed`_.
2544
2545
2546 ``legend``
2547 ==========
2548
2549 `To be completed`_.
2550
2551
2552 ``line``
2553 ========
2554
2555 The ``line`` element contains a single line of text, part of a
2556 `line_block`_.
2557
2558
2559 Details
2560 -------
2561
2562 :Category:
2563     `Body Subelements`_ (simple)
2564
2565 :Parents:
2566     Only the `line_block`_ element contains ``line``.
2567
2568 :Children:
2569     ``line`` elements may contain text data plus `inline elements`_.
2570
2571 :Analogues:
2572     ``line`` has no direct analogues in common DTDs.  It can be
2573     emulated with primitives or type effects.
2574
2575 :Processing:
2576     See `line_block`_.
2577
2578
2579 Content Model
2580 -------------
2581
2582 .. parsed-literal::
2583
2584    `%text.model;`_
2585
2586 :Attributes:
2587     The ``line`` element contains the `common attributes`_ (ids_,
2588     names_, dupnames_, source_, and classes_), plus `xml:space`_.
2589
2590
2591 Examples
2592 --------
2593
2594 See `line_block`_.
2595
2596
2597 ``line_block``
2598 ==============
2599
2600 The ``line_block`` element contains a sequence of lines and nested
2601 line blocks.  Line breaks (implied between elements) and leading
2602 whitespace (indicated by nesting) is significant and must be
2603 preserved.  ``line_block`` elements are commonly used for verse and
2604 addresses.  See `literal_block`_ for an alternative useful for program
2605 listings and interactive computer sessions.
2606
2607
2608 Details
2609 -------
2610
2611 :Category:
2612     `Compound Body Elements`_
2613
2614 :Parents:
2615     All elements employing the `%body.elements;`_ or
2616     `%structure.model;`_ parameter entities in their content models
2617     may contain ``line_block``.
2618
2619 :Children:
2620     ``line_block`` elements may contain line_ elements and nested
2621     ``line_block`` elements.
2622
2623 :Analogues:
2624     ``line_block`` is analogous to the DocBook "literallayout" element
2625     and to the HTML "pre" element (with modifications to typeface
2626     styles).
2627
2628 :Processing:
2629     Unlike ``literal_block``, ``line_block`` elements are typically
2630     rendered in an ordinary text typeface.  It is crucial that leading
2631     whitespace and line breaks are preserved in the rendered form.
2632
2633
2634 Content Model
2635 -------------
2636
2637 .. parsed-literal::
2638
2639    (line_ | line_block_)+
2640
2641 :Attributes:
2642     The ``line_block`` element contains the `common attributes`_ (ids_,
2643     names_, dupnames_, source_, and classes_), plus `xml:space`_.
2644
2645 :Parameter Entities:
2646     The `%body.elements;`_ parameter entity directly includes
2647     ``line_block``.  The `%structure.model;`_ parameter entity
2648     indirectly includes ``line_block``.
2649
2650
2651 Examples
2652 --------
2653
2654 reStructuredText uses a directive to indicate a ``line_block``.
2655 Example source::
2656
2657     Take it away, Eric the Orchestra Leader!
2658
2659     | A one, two, a one two three four
2660     |
2661     | Half a bee, philosophically,
2662     |     must, *ipso facto*, half not be.
2663     | But half the bee has got to be,
2664     |     *vis a vis* its entity.  D'you see?
2665     |
2666     | But can a bee be said to be
2667     |     or not to be an entire bee,
2668     |         when half the bee is not a bee,
2669     |             due to some ancient injury?
2670     |
2671     | Singing...
2672
2673 Pseudo-XML_ fragment from simple parsing::
2674
2675     <paragraph>
2676         Take it away, Eric the Orchestra Leader!
2677     <line_block>
2678         <line>
2679             A one, two, a one two three four
2680         <line>
2681         <line>
2682             Half a bee, philosophically,
2683         <line_block>
2684             <line>
2685                 must,
2686                 <emphasis>
2687                     ipso facto
2688                 , half not be.
2689         <line>
2690             But half the bee has got to be,
2691         <line_block>
2692             <line>
2693                 <emphasis>
2694                     vis a vis
2695                  its entity.  D'you see?
2696             <line>
2697         <line>
2698             But can a bee be said to be
2699         <line_block>
2700             <line>
2701                 or not to be an entire bee,
2702             <line_block>
2703                 <line>
2704                     when half the bee is not a bee,
2705                 <line_block>
2706                     <line>
2707                         due to some ancient injury?
2708                     <line>
2709         <line>
2710             Singing...
2711
2712
2713 ``list_item``
2714 =============
2715
2716 The ``list_item`` element is a container for the elements of a list
2717 item.
2718
2719
2720 Details
2721 -------
2722
2723 :Category:
2724     `Body Subelements`_ (compound)
2725
2726 :Parents:
2727     The bullet_list_ and enumerated_list_ elements contain
2728     ``list_item``.
2729
2730 :Children:
2731     ``list_item`` elements may contain `body elements`_.
2732
2733 :Analogues:
2734     ``list_item`` is analogous to the HTML "li" element and to the
2735     DocBook "listitem" element.
2736
2737 :Processing:
2738     See bullet_list_ or enumerated_list_.
2739
2740
2741 Content Model
2742 -------------
2743
2744 .. parsed-literal::
2745
2746     (`%body.elements;`_)*
2747
2748 :Attributes:
2749     The ``list_item`` element contains only the `common attributes`_:
2750     ids_, names_, dupnames_, source_, and classes_.
2751
2752
2753 Examples
2754 --------
2755
2756 reStructuredText_ source::
2757
2758     1. Outer list, item 1.
2759
2760        * Inner list, item 1.
2761        * Inner list, item 2.
2762
2763     2. Outer list, item 2.
2764
2765 Pseudo-XML_ fragment from simple parsing::
2766
2767     <enumerated_list enumtype="arabic" prefix="" suffix=".">
2768         <list_item>
2769             <paragraph>
2770                 Outer list, item 1.
2771             <bullet_list bullet="*">
2772                 <list_item>
2773                     <paragraph>
2774                         Inner list, item 1.
2775                 <list_item>
2776                     <paragraph>
2777                         Inner list, item 2.
2778         <list_item>
2779             <paragraph>
2780                 Outer list, item 2.
2781
2782 See bullet_list_ or enumerated_list_ for further examples.
2783
2784
2785 ``literal``
2786 ===========
2787
2788 `To be completed`_.
2789
2790
2791 ``literal_block``
2792 =================
2793
2794 The ``literal_block`` element contains a block of text where line
2795 breaks and whitespace are significant and must be preserved.
2796 ``literal_block`` elements are commonly used for program listings and
2797 interactive computer sessions.  See `line_block`_ for an alternative
2798 useful for verse and addresses.
2799
2800
2801 Details
2802 -------
2803
2804 :Category:
2805     `Simple Body Elements`_
2806
2807 :Parents:
2808     All elements employing the `%body.elements;`_ or
2809     `%structure.model;`_ parameter entities in their content models
2810     may contain ``literal_block``.
2811
2812 :Children:
2813     ``literal_block`` elements may contain text data plus `inline
2814     elements`_.
2815
2816 :Analogues:
2817     ``literal_block`` is analogous to the HTML "pre" element and to
2818     the DocBook "programlisting" and "screen" elements.
2819
2820 :Processing:
2821     ``literal_block`` elements are typically rendered in a monospaced
2822     typeface.  It is crucial that all whitespace and line breaks are
2823     preserved in the rendered form.
2824
2825
2826 Content Model
2827 -------------
2828
2829 .. parsed-literal::
2830
2831    `%text.model;`_
2832
2833 :Attributes:
2834     The ``literal_block`` element contains the `common attributes`_
2835     (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
2836
2837 :Parameter Entities:
2838     The `%body.elements;`_ parameter entity directly includes
2839     ``literal_block``.  The `%structure.model;`_ parameter entity
2840     indirectly includes ``literal_block``.
2841
2842
2843 Examples
2844 --------
2845
2846 reStructuredText source::
2847
2848     Here is a literal block::
2849
2850         if literal_block:
2851             text = 'is left as-is'
2852             spaces_and_linebreaks = 'are preserved'
2853             markup_processing = None
2854
2855 Pseudo-XML_ fragment from simple parsing::
2856
2857     <paragraph>
2858         Here is a literal block:
2859     <literal_block xml:space="preserve">
2860         if literal_block:
2861             text = 'is left as-is'
2862             spaces_and_linebreaks = 'are preserved'
2863             markup_processing = None
2864
2865 ``math``
2866 ========
2867
2868 The ``math`` element contains text in `LaTeX math format` that is typeset
2869 as mathematical notation (inline formula).
2870
2871 If the output format does not support math typesetting, the content is
2872 inserted verbatim.
2873
2874 Details
2875 -------
2876
2877 :Category:
2878     `Inline Elements`_
2879
2880 :Parents:
2881     All elements employing the `%inline.elements;`_ parameter entities in
2882     their content models may contain ``math``.
2883
2884 :Children:
2885     ``math`` elements may contain text data.
2886
2887 :Analogues:
2888     ``math`` is analogous to a MathML "math" element or
2889     the LaTeX (``$ math $``) mode.
2890
2891 :Processing:
2892     Rendered as mathematical notation.
2893
2894 Content Model
2895 -------------
2896
2897 .. parsed-literal::
2898
2899     `%text.model;`_
2900
2901 :Attributes:
2902     The ``math`` element contains the `common attributes`_
2903     (ids_, names_, dupnames_, source_, and classes_).
2904
2905
2906 ``math_block``
2907 ==============
2908
2909 The ``math_block`` element contains a block of text in `LaTeX math
2910 format` that is typeset as mathematical notation (display formula).
2911 The ``math_block`` element is generated during the initial parse from a
2912 "math" directive.
2913
2914 If the output format does not support math typesetting, the content is
2915 inserted verbatim.
2916
2917 Details
2918 -------
2919
2920 :Category:
2921     `Simple Body Elements`_
2922
2923 :Parents:
2924     All elements employing the `%body.elements;`_ or
2925     `%structure.model;`_ parameter entities in their content models
2926     may contain ``math_block``.
2927
2928 :Children:
2929     ``math_block`` elements may contain text data.
2930
2931 :Analogues:
2932     ``math_block`` is analogous to a LaTeX "equation*" environment or
2933     a MathML "math" element displayed as block-level element.
2934
2935 :Processing:
2936     Rendered in a block as mathematical notation, typically centered or with
2937     indentation
2938
2939 Content Model
2940 -------------
2941
2942 .. parsed-literal::
2943
2944     `%text.model;`_
2945
2946 :Attributes:
2947     The ``math`` element contains the `common attributes`_
2948     (ids_, names_, dupnames_, source_, and classes_).
2949
2950
2951 ``note``
2952 ========
2953
2954 The ``note`` element is an admonition, a distinctive and
2955 self-contained notice.  Also see the other admonition elements
2956 Docutils offers (in alphabetical order): attention_, caution_,
2957 danger_, error_, hint_, important_, tip_, warning_, and the generic
2958 admonition_.
2959
2960
2961 Details
2962 -------
2963
2964 :Category:
2965     `Compound Body Elements`_
2966
2967 :Parents:
2968     All elements employing the `%body.elements;`_ or
2969     `%structure.model;`_ parameter entities in their content models
2970     may contain ``note``.
2971
2972 :Children:
2973     ``note`` elements contain one or more `body elements`_.
2974
2975 :Analogues:
2976     ``note`` is analogous to the DocBook "note" element.
2977
2978 :Processing:
2979     Rendered distinctly (inset and/or in a box, etc.), with the
2980     generated title "Note" (or similar).
2981
2982
2983 Content Model
2984 -------------
2985
2986 .. parsed-literal::
2987
2988    (`%body.elements;`_)+
2989
2990 :Attributes:
2991     The ``note`` element contains only the `common attributes`_: ids_,
2992     names_, dupnames_, source_, and classes_.
2993
2994 :Parameter Entities:
2995     The `%body.elements;`_ parameter entity directly includes
2996     ``note``.  The `%structure.model;`_ parameter entity indirectly
2997     includes ``note``.
2998
2999
3000 Examples
3001 --------
3002
3003 reStructuredText source::
3004
3005     .. Note:: Admonitions can be handy to break up a
3006        long boring technical document.
3007
3008 Pseudo-XML_ fragment from simple parsing::
3009
3010     <note>
3011         <paragraph>
3012             Admonitions can be handy to break up a
3013             long boring technical document.
3014
3015 ``option``
3016 ==========
3017
3018 The ``option`` element groups an option string together with zero or
3019 more option argument placeholders.  Note that reStructuredText_
3020 currently supports only one argument per option.
3021
3022
3023 Details
3024 -------
3025
3026 :Category:
3027     `Body Subelements`_
3028
3029 :Parents:
3030     Only the option_group_ element contains ``option``.
3031
3032 :Children:
3033     Each ``option`` element contains one option_string_ and zero or
3034     more option_argument_ elements.
3035
3036 :Analogues:
3037     ``option`` has no direct analogues in common DTDs.
3038
3039 :Processing:
3040     See option_list_.
3041
3042
3043 Content Model
3044 -------------
3045
3046 .. parsed-literal::
3047
3048    (option_string_, option_argument_ \*)
3049
3050 :Attributes:
3051     The ``option`` element contains only the `common attributes`_:
3052     ids_, names_, dupnames_, source_, and classes_.
3053
3054
3055 Examples
3056 --------
3057
3058 See the examples for the option_list_ element.
3059
3060
3061 ``option_argument``
3062 ===================
3063
3064 The ``option_argument`` element contains placeholder text for option
3065 arguments.
3066
3067
3068 Details
3069 -------
3070
3071 :Category:
3072     `Body Subelements`_
3073
3074 :Parents:
3075     Only the option_ element contains ``option_argument``.
3076
3077 :Children:
3078     ``option_argument`` elements contain text data only.
3079
3080 :Analogues:
3081     ``option_argument`` has no direct analogues in common DTDs.
3082
3083 :Processing:
3084     The value of the "delimiter" attribute is prefixed to the
3085     ``option_argument``, separating it from its option_string_ or a
3086     preceding ``option_argument``.  The ``option_argument`` text is
3087     typically rendered in a monospaced typeface, possibly italicized
3088     or otherwise altered to indicate its placeholder nature.
3089
3090
3091 Content Model
3092 -------------
3093
3094 .. parsed-literal::
3095
3096    (#PCDATA)
3097
3098 :Attributes:
3099     The ``option_argument`` element contains the `common attributes`_ (ids_,
3100     names_, dupnames_, source_, and classes_), plus delimiter_.
3101
3102     ``delimiter`` contains the text preceding the ``option_argument``:
3103     either the text separating it from the option_string_ (typically
3104     either "=" or " ") or the text between option arguments (typically
3105     either "," or " ").
3106
3107
3108 Examples
3109 --------
3110
3111 See the examples for the option_list_ element.
3112
3113
3114 ``option_group``
3115 ================
3116
3117 The ``option_group`` element groups together one or more option_
3118 elements, all synonyms.
3119
3120
3121 Details
3122 -------
3123
3124 :Category:
3125     `Body Subelements`_
3126
3127 :Parents:
3128     Only the option_list_item_ element contains ``option_group``.
3129
3130 :Children:
3131     ``option_group`` elements contain one or more option_ elements.
3132
3133     ``option_group`` is an empty element and has no children.
3134
3135     Each ``option_group`` element contains one _ and
3136     one _ element.
3137
3138 :Analogues:
3139     ``option_group`` has no direct analogues in common DTDs.
3140
3141 :Processing:
3142     Typically option_ elements within an ``option_group`` are joined
3143     together in a comma-separated list.
3144
3145
3146 Content Model
3147 -------------
3148
3149 .. parsed-literal::
3150
3151    (option_group_, description_)
3152
3153 :Attributes:
3154     The ``option_group`` element contains only the `common attributes`_:
3155     ids_, names_, dupnames_, source_, and classes_.
3156
3157
3158 Examples
3159 --------
3160
3161 See the examples for the option_list_ element.
3162
3163
3164 ``option_list``
3165 ===============
3166
3167 Each ``option_list`` element contains a two-column list of
3168 command-line options and descriptions, documenting a program's
3169 options.
3170
3171
3172 Details
3173 -------
3174
3175 :Category:
3176     `Compound Body Elements`_
3177
3178 :Parents:
3179     All elements employing the `%body.elements;`_ or
3180     `%structure.model;`_ parameter entities in their content models
3181     may contain ``option_list``.
3182
3183 :Children:
3184     ``option_list`` elements contain one or more option_list_item_
3185     elements.
3186
3187 :Analogues:
3188     ``option_list`` has no direct analogues in common DTDs.  It can be
3189     emulated with primitives such as tables.
3190
3191 :Processing:
3192     An ``option_list`` is typically rendered as a two-column list,
3193     where the first column contains option strings and arguments, and
3194     the second column contains descriptions.
3195
3196
3197 Content Model
3198 -------------
3199
3200 .. parsed-literal::
3201
3202    (option_list_item_ +)
3203
3204 :Attributes:
3205     The ``option_list`` element contains only the `common attributes`_:
3206     ids_, names_, dupnames_, source_, and classes_.
3207
3208 :Parameter Entities:
3209     The `%body.elements;`_ parameter entity directly includes
3210     ``option_list``.  The `%structure.model;`_ parameter entity
3211     indirectly includes ``option_list``.
3212
3213
3214 Examples
3215 --------
3216
3217 reStructuredText_ source::
3218
3219     -a            command-line option "a"
3220     -1 file, --one=file, --two file
3221                   Multiple options with arguments.
3222
3223 Pseudo-XML_ fragment from simple parsing::
3224
3225     <option_list>
3226         <option_list_item>
3227             <option_group>
3228                 <option>
3229                     <option_string>
3230                         -a
3231             <description>
3232                 <paragraph>
3233                     command-line option "a"
3234         <option_list_item>
3235             <option_group>
3236                 <option>
3237                     <option_string>
3238                         -1
3239                     <option_argument delimiter=" ">
3240                         file
3241                 <option>
3242                     <option_string>
3243                         --one
3244                     <option_argument delimiter="=">
3245                         file
3246                 <option>
3247                     <option_string>
3248                         --two
3249                     <option_argument delimiter=" ">
3250                         file
3251             <description>
3252                 <paragraph>
3253                     Multiple options with arguments.
3254
3255
3256 ``option_list_item``
3257 ====================
3258
3259 The ``option_list_item`` element is a container for a pair of
3260 option_group_ and description_ elements.
3261
3262
3263 Details
3264 -------
3265
3266 :Category:
3267     `Body Subelements`_
3268
3269 :Parents:
3270     Only the option_list_ element contains ``option_list_item``.
3271
3272 :Children:
3273     Each ``option_list_item`` element contains one option_group_ and
3274     one description_ element.
3275
3276 :Analogues:
3277     ``option_list_item`` has no direct analogues in common DTDs.
3278
3279 :Processing:
3280     See option_list_.
3281
3282
3283 Content Model
3284 -------------
3285
3286 .. parsed-literal::
3287
3288    (option_group_, description_)
3289
3290 :Attributes:
3291     The ``option_list_item`` element contains only the `common attributes`_:
3292     ids_, names_, dupnames_, source_, and classes_.
3293
3294
3295 Examples
3296 --------
3297
3298 See the examples for the option_list_ element.
3299
3300
3301 ``option_string``
3302 =================
3303
3304 The ``option_string`` element contains the text of a command-line
3305 option.
3306
3307
3308 Details
3309 -------
3310
3311 :Category:
3312     `Body Subelements`_
3313
3314 :Parents:
3315     Only the option_ element contains ``option_string``.
3316
3317 :Children:
3318     ``option_string`` elements contain text data only.
3319
3320 :Analogues:
3321     ``option_string`` has no direct analogues in common DTDs.
3322
3323 :Processing:
3324     The ``option_string`` text is typically rendered in a monospaced
3325     typeface.
3326
3327
3328 Content Model
3329 -------------
3330
3331 .. parsed-literal::
3332
3333    (#PCDATA)
3334
3335 :Attributes:
3336     The ``option_string`` element contains only the `common attributes`_:
3337     ids_, names_, dupnames_, source_, and classes_.
3338
3339
3340 Examples
3341 --------
3342
3343 See the examples for the option_list_ element.
3344
3345
3346 ``organization``
3347 ================
3348
3349 The ``organization`` element contains the name of document author's
3350 organization, or the organization responsible for the document.
3351
3352
3353 Details
3354 -------
3355
3356 :Category:
3357     `Bibliographic Elements`_
3358
3359 :Parents:
3360     Only the docinfo_ element contains ``organization``.
3361
3362 :Children:
3363     ``organization`` elements may contain text data plus `inline
3364     elements`_.
3365
3366 :Analogues:
3367     ``organization`` is analogous to the DocBook "orgname",
3368     "corpname", or "publishername" elements.
3369
3370 :Processing:
3371     See docinfo_.
3372
3373
3374 Content Model
3375 -------------
3376
3377 .. parsed-literal::
3378
3379     `%text.model;`_
3380
3381 :Attributes:
3382     The ``organization`` element contains only the `common attributes`_:
3383     ids_, names_, dupnames_, source_, and classes_.
3384
3385 :Parameter Entities:
3386     The `%bibliographic.elements;`_ parameter entity directly includes
3387     ``organization``.
3388
3389
3390 Examples
3391 --------
3392
3393 reStructuredText_ source::
3394
3395     Document Title
3396     ==============
3397
3398     :Organization: Humankind
3399
3400 Complete pseudo-XML_ result after parsing and applying transforms::
3401
3402     <document ids="document-title" names="document title">
3403         <title>
3404             Document Title
3405         <docinfo>
3406             <organization>
3407                 Humankind
3408
3409 See docinfo_ for a more complete example, including processing
3410 context.
3411
3412
3413 ``paragraph``
3414 =============
3415
3416 The ``paragraph`` element contains the text and inline elements of a
3417 single paragraph, a fundamental building block of documents.
3418
3419
3420 Details
3421 -------
3422
3423 :Category:
3424     `Simple Body Elements`_
3425
3426 :Parents:
3427     All elements employing the `%body.elements;`_ or
3428     `%structure.model;`_ parameter entities in their content models
3429     may contain ``paragraph``.
3430
3431 :Children:
3432     ``paragraph`` elements may contain text data plus `inline
3433     elements`_.
3434
3435 :Analogues:
3436     ``paragraph`` is analogous to the HTML "p" element and to the
3437     DocBook "para" elements.
3438
3439
3440 Content Model
3441 -------------
3442
3443 .. parsed-literal::
3444
3445     `%text.model;`_
3446
3447 :Attributes:
3448     The ``paragraph`` element contains only the `common attributes`_:
3449     ids_, names_, dupnames_, source_, and classes_.
3450
3451 :Parameter Entities:
3452     The `%body.elements;`_ parameter entity directly includes
3453     ``paragraph``.  The `%structure.model;`_ parameter entity
3454     indirectly includes ``paragraph``.
3455
3456
3457 Examples
3458 --------
3459
3460 reStructuredText_ source::
3461
3462     A paragraph.
3463
3464 Pseudo-XML_ fragment from simple parsing::
3465
3466     <paragraph>
3467         A paragraph.
3468
3469
3470 ``pending``
3471 ===========
3472
3473 `To be completed`_.
3474
3475
3476 ``problematic``
3477 ===============
3478
3479 `To be completed`_.
3480
3481
3482 ``raw``
3483 =======
3484
3485 `To be completed`_.
3486
3487
3488 ``reference``
3489 =============
3490
3491 `To be completed`_.
3492
3493
3494 ``revision``
3495 ============
3496
3497 The ``revision`` element contains the revision number of the document.
3498 It can be used alone or in conjunction with version_.
3499
3500
3501 Details
3502 -------
3503
3504 :Category:
3505     `Bibliographic Elements`_
3506
3507 :Parents:
3508     Only the docinfo_ element contains ``revision``.
3509
3510 :Children:
3511     ``revision`` elements may contain text data plus `inline
3512     elements`_.
3513
3514 :Analogues:
3515     ``revision`` is analogous to but simpler than the DocBook
3516     "revision" element.  It closely matches the DocBook "revnumber"
3517     element, but in a simpler context.
3518
3519 :Processing:
3520     Often used with the RCS/CVS keyword "Revision".  See docinfo_.
3521
3522
3523 Content Model
3524 -------------
3525
3526 .. parsed-literal::
3527
3528     `%text.model;`_
3529
3530 :Attributes:
3531     The ``revision`` element contains only the `common attributes`_:
3532     ids_, names_, dupnames_, source_, and classes_.
3533
3534 :Parameter Entities:
3535     The `%bibliographic.elements;`_ parameter entity directly includes
3536     ``revision``.
3537
3538
3539 Examples
3540 --------
3541
3542 reStructuredText_ source::
3543
3544     Document Title
3545     ==============
3546
3547     :Version: 1
3548     :Revision: b
3549
3550 Complete pseudo-XML_ result after parsing and applying transforms::
3551
3552     <document ids="document-title" names="document title">
3553         <title>
3554             Document Title
3555         <docinfo>
3556             <version>
3557                 1
3558             <revision>
3559                 b
3560
3561 See docinfo_ for a more complete example, including processing
3562 context.
3563
3564
3565 ``row``
3566 =======
3567
3568 `To be completed`_.
3569
3570
3571 ``rubric``
3572 ==========
3573
3574      rubric n. 1. a title, heading, or the like, in a manuscript,
3575      book, statute, etc., written or printed in red or otherwise
3576      distinguished from the rest of the text. ...
3577
3578      -- Random House Webster's College Dictionary, 1991
3579
3580 A rubric is like an informal heading that doesn't correspond to the
3581 document's structure.
3582
3583 `To be completed`_.
3584
3585
3586 ``section``
3587 ===========
3588
3589 The ``section`` element is the main unit of hierarchy for Docutils
3590 documents.  Docutils ``section`` elements are a recursive structure; a
3591 ``section`` may contain other ``section`` elements, without limit.
3592 Paragraphs and other body elements may occur before a ``section``, but
3593 not after it.
3594
3595
3596 Details
3597 -------
3598
3599 :Category:
3600     `Structural Elements`_
3601
3602 :Parents:
3603     The following elements may contain ``section``: document_,
3604     section_
3605
3606 :Children:
3607     ``section`` elements begin with a title_, and may contain `body
3608     elements`_ as well as transition_, topic_, and sidebar_ elements.
3609
3610 :Analogues:
3611     ``section`` is analogous to DocBook recursive "section" elements,
3612     and to HTML "div" elements combined with "h1" etc. title elements.
3613
3614
3615 Content Model
3616 -------------
3617
3618 .. parsed-literal::
3619
3620     (title_,
3621      `%structure.model;`_)
3622
3623 See the `%structure.model;`_ parameter entity for details of the body
3624 of a ``section``.
3625
3626 :Attributes:
3627     The ``section`` element contains only the `common attributes`_:
3628     ids_, names_, dupnames_, source_, and classes_.
3629
3630 :Parameter Entities:
3631     The `%section.elements;`_ parameter entity directly includes
3632     ``section``.  The `%structure.model;`_ parameter entity indirectly
3633     includes ``section``.
3634
3635
3636 Examples
3637 --------
3638
3639 reStructuredText_ source::
3640
3641     Title 1
3642     =======
3643     Paragraph 1.
3644
3645     Title 2
3646     -------
3647     Paragraph 2.
3648
3649     Title 3
3650     =======
3651     Paragraph 3.
3652
3653     Title 4
3654     -------
3655     Paragraph 4.
3656
3657 Complete pseudo-XML_ result after parsing::
3658
3659     <document>
3660         <section ids="title-1" names="title 1">
3661             <title>
3662                 Title 1
3663             <paragraph>
3664                 Paragraph 1.
3665             <section ids="title-2" names="title 2">
3666                 <title>
3667                     Title 2
3668                 <paragraph>
3669                     Paragraph 2.
3670         <section ids="title-3" names="title 3">
3671             <title>
3672                 Title 3
3673             <paragraph>
3674                 Paragraph 3.
3675             <section ids="title-4" names="title 4">
3676                 <title>
3677                     Title 4
3678                 <paragraph>
3679                     Paragraph 4.
3680
3681
3682 ``sidebar``
3683 ===========
3684
3685 Sidebars are like miniature, parallel documents that occur inside
3686 other documents, providing related or reference material.  A
3687 ``sidebar`` is typically offset by a border and "floats" to the side
3688 of the page; the document's main text may flow around it.  Sidebars
3689 can also be likened to super-footnotes; their content is outside of
3690 the flow of the document's main text.
3691
3692 The ``sidebar`` element is a nonrecursive section_-like construct
3693 which may occur at the top level of a section_ wherever a body element
3694 (list, table, etc.) is allowed.  In other words, ``sidebar`` elements
3695 cannot nest inside body elements, so you can't have a ``sidebar``
3696 inside a ``table`` or a ``list``, or inside another ``sidebar`` (or
3697 topic_).
3698
3699
3700 Details
3701 -------
3702
3703 :Category:
3704     `Structural Elements`_
3705
3706 :Parents:
3707     The following elements may contain ``sidebar``: document_,
3708     section_
3709
3710 :Children:
3711     ``sidebar`` elements begin with a title_ and an optional subtitle_
3712     and contain `body elements`_ and topic_ elements.
3713
3714 :Analogues:
3715     ``sidebar`` is analogous to the DocBook "sidebar" element.
3716
3717 :Processing:
3718     A ``sidebar`` element should be set off from the rest of the
3719     document somehow, typically with a border.  Sidebars typically
3720     "float" to the side of the page and the document's main text flows
3721     around them.
3722
3723
3724 Content Model
3725 -------------
3726
3727 .. parsed-literal::
3728
3729     (title_, subtitle_?,
3730      (`%body.elements;`_ | topic_)+)
3731
3732 :Attributes:
3733     The ``sidebar`` element contains only the `common attributes`_:
3734     ids_, names_, dupnames_, source_, and classes_.
3735
3736 :Parameter Entities:
3737     The `%structure.model;`_ parameter entity directly includes
3738     ``sidebar``.
3739
3740
3741 Examples
3742 --------
3743
3744 The `"sidebar" directive`_ is used to create a ``sidebar`` element.
3745 reStructuredText_ source::
3746
3747     .. sidebar:: Title
3748        :subtitle: If Desired
3749
3750        Body.
3751
3752 Pseudo-XML_ fragment from simple parsing::
3753
3754     <sidebar>
3755         <title>
3756             Title
3757         <subtitle>
3758             If Desired
3759         <paragraph>
3760             Body.
3761
3762 .. _"sidebar" directive: rst/directives.html#sidebar
3763
3764
3765 ``status``
3766 ==========
3767
3768 The ``status`` element contains a status statement for the document,
3769 such as "Draft", "Final", "Work In Progress", etc.
3770
3771
3772 Details
3773 -------
3774
3775 :Category:
3776     `Bibliographic Elements`_
3777
3778 :Parents:
3779     Only the docinfo_ element contains ``status``.
3780
3781 :Children:
3782     ``status`` elements may contain text data plus `inline elements`_.
3783
3784 :Analogues:
3785     ``status`` is analogous to the DocBook "status" element.
3786
3787 :Processing:
3788     See docinfo_.
3789
3790
3791 Content Model
3792 -------------
3793
3794 .. parsed-literal::
3795
3796     `%text.model;`_
3797
3798 :Attributes:
3799     The ``status`` element contains only the `common attributes`_:
3800     ids_, names_, dupnames_, source_, and classes_.
3801
3802 :Parameter Entities:
3803     The `%bibliographic.elements;`_ parameter entity directly includes
3804     ``status``.
3805
3806
3807 Examples
3808 --------
3809
3810 reStructuredText_ source::
3811
3812     Document Title
3813     ==============
3814
3815     :Status: Work In Progress
3816
3817 Complete pseudo-XML_ result after parsing and applying transforms::
3818
3819     <document ids="document-title" names="document title">
3820         <title>
3821             Document Title
3822         <docinfo>
3823             <status>
3824                 Work In Progress
3825
3826 See docinfo_ for a more complete example, including processing
3827 context.
3828
3829
3830 ``strong``
3831 ==========
3832
3833 `To be completed`_.
3834
3835
3836 ``subscript``
3837 =============
3838
3839 `To be completed`_.
3840
3841
3842 ``substitution_definition``
3843 ===========================
3844
3845 `To be completed`_.
3846
3847
3848 ``substitution_reference``
3849 ==========================
3850
3851 `To be completed`_.
3852
3853
3854 ``subtitle``
3855 ============
3856
3857 The ``subtitle`` element stores the subtitle of a document_.
3858
3859
3860 Details
3861 -------
3862
3863 :Category:
3864     `Structural Subelements`_
3865
3866 :Parents:
3867     The document_ and sidebar_ elements may contain ``subtitle``.
3868
3869 :Children:
3870     ``subtitle`` elements may contain text data plus `inline
3871     elements`_.
3872
3873 :Analogues:
3874     ``subtitle`` is analogous to HTML header elements ("h2" etc.) and
3875     to the DocBook "subtitle" element.
3876
3877 :Processing:
3878     A document's subtitle is usually rendered smaller than its title_.
3879
3880
3881 Content Model
3882 -------------
3883
3884 .. parsed-literal::
3885
3886     `%text.model;`_
3887
3888 :Attributes:
3889     The ``subtitle`` element contains only the `common attributes`_:
3890     ids_, names_, dupnames_, source_, and classes_.
3891
3892
3893 Examples
3894 --------
3895
3896 reStructuredText_ source::
3897
3898     =======
3899      Title
3900     =======
3901     ----------
3902      Subtitle
3903     ----------
3904
3905     A paragraph.
3906
3907 Complete pseudo-XML_ result after parsing and applying transforms::
3908
3909     <document ids="title" names="title">
3910         <title>
3911             Title
3912         <subtitle ids="subtitle" names="subtitle">
3913             Subtitle
3914         <paragraph>
3915             A paragraph.
3916
3917 Note how two section levels have collapsed, promoting their titles to
3918 become the document's title and subtitle.  Since there is only one
3919 structural element (document), the subsection's ``ids`` and ``names``
3920 attributes are stored in the ``subtitle`` element.
3921
3922
3923 ``superscript``
3924 ===============
3925
3926 `To be completed`_.
3927
3928
3929 ``system_message``
3930 ==================
3931
3932 `To be completed`_.
3933
3934
3935 ``table``
3936 =========
3937
3938 `To be completed`_.
3939
3940
3941 ``target``
3942 ==========
3943
3944 `To be completed`_.
3945
3946
3947 ``tbody``
3948 =========
3949
3950 `To be completed`_.
3951
3952
3953 ``term``
3954 ========
3955
3956 The ``term`` element contains a word or phrase being defined in a
3957 definition_list_.
3958
3959
3960 Details
3961 -------
3962
3963 :Category:
3964     `Body Subelements`_ (simple)
3965
3966 :Parents:
3967     Only the definition_list_item_ element contains ``term``.
3968
3969 :Children:
3970     ``term`` elements may contain text data plus `inline elements`_.
3971
3972 :Analogues:
3973     ``term`` is analogous to the HTML "dt" element and to the DocBook
3974     "term" element.
3975
3976 :Processing:
3977     See definition_list_item_.
3978
3979
3980 Content Model
3981 -------------
3982
3983 .. parsed-literal::
3984
3985     `%text.model;`_
3986
3987 :Attributes:
3988     The ``term`` element contains only the `common attributes`_:
3989     ids_, names_, dupnames_, source_, and classes_.
3990
3991
3992 Examples
3993 --------
3994
3995 See the examples for the definition_list_, definition_list_item_, and
3996 classifier_ elements.
3997
3998
3999 ``tgroup``
4000 ==========
4001
4002 `To be completed`_.
4003
4004
4005 ``thead``
4006 =========
4007
4008 `To be completed`_.
4009
4010
4011 ``tip``
4012 =======
4013
4014 The ``tip`` element is an admonition, a distinctive and self-contained
4015 notice.  Also see the other admonition elements Docutils offers (in
4016 alphabetical order): attention_, caution_, danger_, error_, hint_,
4017 important_, note_, warning_, and the generic admonition_.
4018
4019
4020 Details
4021 -------
4022
4023 :Category:
4024     `Compound Body Elements`_
4025
4026 :Parents:
4027     All elements employing the `%body.elements;`_ or
4028     `%structure.model;`_ parameter entities in their content models
4029     may contain ``tip``.
4030
4031 :Children:
4032     ``tip`` elements contain one or more `body elements`_.
4033
4034 :Analogues:
4035     ``tip`` is analogous to the DocBook "tip" element.
4036
4037 :Processing:
4038     Rendered distinctly (inset and/or in a box, etc.), with the
4039     generated title "Tip" (or similar).
4040
4041
4042 Content Model
4043 -------------
4044
4045 .. parsed-literal::
4046
4047    (`%body.elements;`_)+
4048
4049 :Attributes:
4050     The ``tip`` element contains only the `common attributes`_: ids_,
4051     names_, dupnames_, source_, and classes_.
4052
4053 :Parameter Entities:
4054     The `%body.elements;`_ parameter entity directly includes ``tip``.
4055     The `%structure.model;`_ parameter entity indirectly includes
4056     ``tip``.
4057
4058
4059 Examples
4060 --------
4061
4062 reStructuredText source::
4063
4064     .. Tip:: 15% if the service is good.
4065
4066 Pseudo-XML_ fragment from simple parsing::
4067
4068     <tip>
4069         <paragraph>
4070             15% if the service is good.
4071
4072
4073 .. _title:
4074
4075 ``title``
4076 =========
4077
4078 The ``title`` element stores the title of a document_, section_,
4079 topic_, sidebar_, or generic admonition_.
4080
4081
4082 Details
4083 -------
4084
4085 :Category:
4086     `Structural Subelements`_
4087
4088 :Parents:
4089     The following elements may contain ``title``: document_, section_,
4090     topic_, sidebar_, admonition_
4091
4092 :Children:
4093     ``title`` elements may contain text data plus `inline elements`_.
4094
4095 :Analogues:
4096     ``title`` is analogous to HTML "title" and header ("h1" etc.)
4097     elements, and to the DocBook "title" element.
4098
4099
4100 Content Model
4101 -------------
4102
4103 .. parsed-literal::
4104
4105     `%text.model;`_
4106
4107 :Attributes:
4108     The ``title`` element contains the `common attributes`_ (ids_,
4109     names_, dupnames_, source_, and classes_), plus refid_ and auto_.
4110
4111     ``refid`` is used as a backlink to a table of contents entry.
4112
4113     ``auto`` is used to indicate (with value "1") that the ``title``
4114     has been numbered automatically.
4115
4116
4117 Examples
4118 --------
4119
4120 reStructuredText_ source::
4121
4122     A Title
4123     =======
4124
4125     A paragraph.
4126
4127 Pseudo-XML_ fragment from simple parsing::
4128
4129     <section ids="a-title" names="a title">
4130         <title>
4131             A Title
4132         <paragraph>
4133             A paragraph.
4134
4135
4136 ``title_reference``
4137 ===================
4138
4139 `To be completed`_.
4140
4141
4142 ``topic``
4143 =========
4144
4145 The ``topic`` element is a nonrecursive section_-like construct which
4146 may occur at the top level of a section_ wherever a body element
4147 (list, table, etc.) is allowed.  In other words, ``topic`` elements
4148 cannot nest inside body elements, so you can't have a ``topic`` inside
4149 a ``table`` or a ``list``, or inside another ``topic``.
4150
4151
4152 Details
4153 -------
4154
4155 :Category:
4156     `Structural Elements`_
4157
4158 :Parents:
4159     The following elements may contain ``topic``: document_, section_,
4160     sidebar_
4161
4162 :Children:
4163     ``topic`` elements begin with a title_ and may contain `body
4164     elements`_.
4165
4166 :Analogues:
4167     ``topic`` is analogous to the DocBook "simplesect" element.
4168
4169 :Processing:
4170     A ``topic`` element should be set off from the rest of the
4171     document somehow, such as with indentation or a border.
4172
4173
4174 Content Model
4175 -------------
4176
4177 .. parsed-literal::
4178
4179     (title_?,
4180      (`%body.elements;`_)+)
4181
4182 :Attributes:
4183     The ``topic`` element contains only the `common attributes`_:
4184     ids_, names_, dupnames_, source_, and classes_.
4185
4186 :Parameter Entities:
4187     The `%structure.model;`_ parameter entity directly includes
4188     ``topic``.
4189
4190
4191 Examples
4192 --------
4193
4194 The `"topic" directive`_ is used to create a ``topic`` element.
4195 reStructuredText_ source::
4196
4197     .. topic:: Title
4198
4199        Body.
4200
4201 Pseudo-XML_ fragment from simple parsing::
4202
4203     <topic>
4204         <title>
4205             Title
4206         <paragraph>
4207             Body.
4208
4209 .. _"topic" directive: rst/directives.html#topic
4210
4211
4212 ``transition``
4213 ==============
4214
4215 The ``transition`` element is commonly seen in novels and short
4216 fiction, as a gap spanning one or more lines, with or without a type
4217 ornament such as a row of asterisks.  Transitions separate body
4218 elements and sections, dividing a section into untitled divisions.  A
4219 transition may not begin or end a section [#]_ or document, nor may
4220 two transitions be immediately adjacent.
4221
4222 See `Doctree Representation of Transitions`__ in `A Record of
4223 reStructuredText Syntax Alternatives`__.
4224
4225 .. [#] In reStructuredText markup, a transition may appear to fall at
4226    the end of a section immediately before another section.  A
4227    transform recognizes this case and moves the transition so it
4228    separates the sections.
4229
4230 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
4231 __ ../dev/rst/alternatives.html
4232
4233
4234 Details
4235 -------
4236
4237 :Category:
4238     `Structural Subelements`_
4239
4240 :Parents:
4241     The following elements may contain ``transition``: document_,
4242     section_
4243
4244 :Children:
4245     ``transition`` is an empty element and has no children.
4246
4247 :Analogues:
4248     ``transition`` is analogous to the HTML "hr" element.
4249
4250 :Processing:
4251     The ``transition`` element is typically rendered as vertical
4252     whitespace (more than that separating paragraphs), with or without
4253     a horizontal line or row of asterisks.  In novels, transitions are
4254     often represented as a row of three well-spaced asterisks with
4255     vertical space above and below.
4256
4257
4258 Content Model
4259 -------------
4260
4261 ::
4262
4263     EMPTY
4264
4265 The ``transition`` element has no content; it is a "point element".
4266
4267 :Attributes:
4268     The ``transition`` element contains only the `common attributes`_:
4269     ids_, names_, dupnames_, source_, and classes_.
4270
4271 :Parameter Entities:
4272     The `%structure.model;`_ parameter entity directly includes
4273     ``transition``.
4274
4275
4276 Examples
4277 --------
4278
4279 reStructuredText_ source::
4280
4281     Paragraph 1.
4282
4283     --------
4284
4285     Paragraph 2.
4286
4287 Complete pseudo-XML_ result after parsing::
4288
4289     <document>
4290         <paragraph>
4291             Paragraph 1.
4292         <transition>
4293         <paragraph>
4294             Paragraph 2.
4295
4296
4297 ``version``
4298 ===========
4299
4300 The ``version`` element contains the version number of the document.
4301 It can be used alone or in conjunction with revision_.
4302
4303
4304 Details
4305 -------
4306
4307 :Category:
4308     `Bibliographic Elements`_
4309
4310 :Parents:
4311     Only the docinfo_ element contains ``version``.
4312
4313 :Children:
4314     ``version`` elements may contain text data plus `inline
4315     elements`_.
4316
4317 :Analogues:
4318     ``version`` may be considered analogous to the DocBook "revision",
4319     "revnumber", or "biblioid" elements.
4320
4321 :Processing:
4322     Sometimes used with the RCS/CVS keyword "Revision".  See docinfo_
4323     and revision_.
4324
4325
4326 Content Model
4327 -------------
4328
4329 .. parsed-literal::
4330
4331     `%text.model;`_
4332
4333 :Attributes:
4334     The ``version`` element contains only the `common attributes`_:
4335     ids_, names_, dupnames_, source_, and classes_.
4336
4337 :Parameter Entities:
4338     The `%bibliographic.elements;`_ parameter entity directly includes
4339     ``version``.
4340
4341
4342 Examples
4343 --------
4344
4345 reStructuredText_ source::
4346
4347     Document Title
4348     ==============
4349
4350     :Version: 1.1
4351
4352 Complete pseudo-XML_ result after parsing and applying transforms::
4353
4354     <document ids="document-title" names="document title">
4355         <title>
4356             Document Title
4357         <docinfo>
4358             <version>
4359                 1.1
4360
4361 See docinfo_ for a more complete example, including processing
4362 context.
4363
4364
4365 ``warning``
4366 ===========
4367
4368 The ``warning`` element is an admonition, a distinctive and
4369 self-contained notice.  Also see the other admonition elements
4370 Docutils offers (in alphabetical order): attention_, caution_,
4371 danger_, error_, hint_, important_, note_, tip_.
4372
4373
4374 Details
4375 -------
4376
4377 :Category:
4378     `Compound Body Elements`_
4379
4380 :Parents:
4381     All elements employing the `%body.elements;`_ or
4382     `%structure.model;`_ parameter entities in their content models
4383     may contain ``warning``.
4384
4385 :Children:
4386     ``warning`` elements contain one or more `body elements`_.
4387
4388 :Analogues:
4389     ``warning`` is analogous to the DocBook "warning" element.
4390
4391 :Processing:
4392     Rendered distinctly (inset and/or in a box, etc.), with the
4393     generated title "Warning" (or similar).
4394
4395
4396 Content Model
4397 -------------
4398
4399 .. parsed-literal::
4400
4401    (`%body.elements;`_)+
4402
4403 :Attributes:
4404     The ``warning`` element contains only the `common attributes`_:
4405     ids_, names_, dupnames_, source_, and classes_.
4406
4407 :Parameter Entities:
4408     The `%body.elements;`_ parameter entity directly includes
4409     ``warning``.  The `%structure.model;`_ parameter entity indirectly
4410     includes ``warning``.
4411
4412
4413 Examples
4414 --------
4415
4416 reStructuredText source::
4417
4418     .. WARNING:: Reader discretion is strongly advised.
4419
4420 Pseudo-XML_ fragment from simple parsing::
4421
4422     <warning>
4423         <paragraph>
4424             Reader discretion is strongly advised.
4425
4426
4427 ---------------------
4428  Attribute Reference
4429 ---------------------
4430
4431 .. contents:: :local:
4432               :depth: 1
4433
4434 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
4435 all elements contain the following attributes: ids_, names_, dupnames_,
4436 source_, and classes_.
4437
4438 .. _attribute type:
4439
4440 Attribute types:
4441
4442 ``CDATA``
4443     Character data.  ``CDATA`` attributes may contain arbitrary text.
4444
4445 ``ID``
4446     Like a ``NMTOKEN``, but it must begin with a letter (a "name
4447     production").  Identical ``ID`` values must not appear more than
4448     once in a document; i.e., ID values must uniquely identify their
4449     elements.
4450
4451 ``IDREF``
4452     A reference to an ``ID`` value (a name production) of another
4453     element.
4454
4455 ``IDREFS``
4456     One or more space-separated ``ID`` references (name productions).
4457
4458 ``NMTOKEN``
4459     A "name token".  One or more of letters, digits, ".", "-", and
4460     "_".
4461
4462 ``NMTOKENS``
4463     One or more space-separated ``NMTOKEN`` names.
4464
4465 ``%yesorno;``
4466     No if zero ("0"), yes if any other value.  This is a parameter
4467     entity which resolves to a ``NMTOKEN`` attribute type.
4468
4469 ``%number;``
4470     This emphasizes that the attribute value must be a number.  This
4471     is a parameter entity which resolves to a ``NMTOKEN`` attribute
4472     type.
4473
4474 enumeration
4475     The attribute value may be one of a specified list of values.
4476
4477
4478 ``anonymous``
4479 =============
4480
4481 `Attribute type`_: ``%yesorno;``.  Default value: none (implies no).
4482
4483 The ``anonymous`` attribute is used for unnamed hyperlinks in the
4484 target_ and reference_ elements (via the `%anonymous.att;`_ parameter
4485 entity).
4486
4487
4488 ``auto``
4489 ========
4490
4491 `Attribute type`_: ``CDATA``.  Default value: none.
4492
4493 The ``auto`` attribute is used to indicate automatically-numbered
4494 footnote_, footnote_reference_ and title_ elements (via the
4495 `%auto.att;`_ parameter entity).
4496
4497
4498 ``backrefs``
4499 ============
4500
4501 `Attribute type`_: ``IDREFS``.  Default value: none.
4502
4503 The ``backrefs`` attribute contains a space-separated list of ids_
4504 references, used for backlinks from footnote_, citation_, and
4505 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
4506
4507
4508 ``bullet``
4509 ==========
4510
4511 `Attribute type`_: ``CDATA``.  Default value: none.
4512
4513 The ``bullet`` attribute is used in the bullet_list_ element.
4514
4515
4516 ``classes``
4517 ===========
4518
4519 `Attribute type`_: ``NMTOKENS``.  Default value: none.
4520
4521 The ``classes`` attribute is a list containing zero or more names used
4522 to classify an element. The names are converted to conform to the
4523 regular expression ``[a-z](-?[a-z0-9]+)*`` (see the `"class"
4524 directive`_ description for details and rationale_).
4525
4526 The purpose of the attribute is to indicate
4527 an "is-a" variant relationship, to allow an extensible way of defining
4528 sub-classes of existing elements.  It can be used to carry context
4529 forward between a Docutils Reader and Writer, when a custom structure
4530 is reduced to a standardized document tree.  One common use is in
4531 conjunction with stylesheets, to add selection criteria.  It should
4532 not be used to carry formatting instructions or arbitrary content.
4533
4534 The ``classes`` attribute's contents should be ignorable.  Writers that
4535 are not familiar with the variant expressed should be able to ignore
4536 the attribute.
4537
4538 ``classes`` is one of the `common attributes`_, shared by all Docutils
4539 elements.
4540
4541 .. _"class" directive: rst/directives.html#class
4542 .. _rationale: rst/directives.html#rationale
4543
4544 ``delimiter``
4545 =============
4546
4547 `Attribute type`_: ``CDATA``.  Default value: none.
4548
4549 The ``delimiter`` attribute is used in the option_argument_ element.
4550
4551
4552 ``dupnames``
4553 ============
4554
4555 `Attribute type`_: ``CDATA``.  Default value: none.
4556
4557 The ``dupnames`` attribute is a list containing the names of an
4558 element when there has been a naming conflict.  The contents of the
4559 ``dupnames`` attribute would have been transferred from the `names`_
4560 attribute.  An element may have at most one of the ``names`` or
4561 ``dupnames`` attributes, but not both.  ``dupnames`` is one of the
4562 `common attributes`_, shared by all Docutils elements.
4563
4564
4565 ``enumtype``
4566 ============
4567
4568 `Attribute type`_: enumeration, one of "arabic", "loweralpha",
4569 "upperalpha", "lowerroman", or "upperroman".  Default value: none.
4570
4571 The ``enumtype`` attribute is used in the enumerated_list_ element.
4572
4573
4574 ``ids``
4575 =======
4576
4577 `Attribute type`_: ``NMTOKENS``.  Default value: none.
4578
4579 The ``ids`` attribute is a list containing one or more unique
4580 identifier keys.  ``ids`` is one of the `common attributes`_, shared
4581 by all Docutils elements.
4582
4583
4584 ``names``
4585 =========
4586
4587 `Attribute type`_: ``CDATA``.  Default value: none.
4588
4589 The ``names`` attribute is a list containing the names of an element,
4590 typically originating from the element's title or content.  Each name
4591 in ``names`` must be unique; if there are name conflicts (two or more
4592 elements want to the same name), the contents will be transferred to
4593 the `dupnames`_ attribute on the duplicate elements.  An element may
4594 have at most one of the ``names`` or ``dupnames`` attributes, but not
4595 both.  ``names`` is one of the `common attributes`_, shared by all
4596 Docutils elements.
4597
4598
4599 ``prefix``
4600 ==========
4601
4602 `Attribute type`_: ``CDATA``.  Default value: none.
4603
4604 The ``prefix`` attribute is used in the enumerated_list_ element.
4605
4606
4607 ``refid``
4608 =========
4609
4610 `Attribute type`_: ``IDREF``.  Default value: none.
4611
4612 The ``refid`` attribute contains references to `ids`_ attributes in
4613 other elements.  It is used by the target_, reference_,
4614 footnote_reference_, citation_reference_, title_ and problematic_
4615 elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter
4616 entities).
4617
4618
4619 ``refname``
4620 ===========
4621
4622 `Attribute type`_: ``NMTOKENS``.  Default value: none.
4623
4624 The ``refname`` attribute contains an internal reference to the
4625 `names`_ attribute of another element.  On a `target`_ element,
4626 ``refname`` indicates an indirect target which may resolve to either
4627 an internal or external reference.  ``refname`` is used by the
4628 target_, reference_, footnote_reference_, citation_reference_, and
4629 substitution_reference_ elements (via the `%refname.att;`_ and
4630 `%reference.atts;`_ parameter entities).
4631
4632
4633 ``refuri``
4634 ==========
4635
4636 `Attribute type`_: ``CDATA``.  Default value: none.
4637
4638 The ``refuri`` attribute contains an external reference to a URI/URL.
4639 It is used by the target_, reference_, footnote_reference_, and
4640 citation_reference_ elements (via the `%reference.atts;`_ parameter
4641 entity).
4642
4643
4644 ``source``
4645 ==========
4646
4647 `Attribute type`_: ``CDATA``.  Default value: none.
4648
4649 The ``source`` attribute is used to store the path or URL to the
4650 source text that was used to produce the document tree.  It is one of
4651 the `common attributes`_, shared by all Docutils elements.
4652
4653
4654 ``start``
4655 =========
4656
4657 `Attribute type`_: ``%number;``.  Default value: none.
4658
4659 The ``start`` attribute is used in the enumerated_list_ element.
4660
4661
4662 ``suffix``
4663 ==========
4664
4665 `Attribute type`_: ``CDATA``.  Default value: none.
4666
4667 The ``suffix`` attribute is used in the enumerated_list_ element.
4668
4669
4670 ``xml:space``
4671 =============
4672
4673 `Attribute type`_: one of "default" or "preserve".  Default value:
4674 "preserve" (fixed).
4675
4676 The ``xml:space`` attribute is a standard XML attribute for
4677 whitespace-preserving elements.  It is used by the literal_block_,
4678 line_block_, doctest_block_, comment_, and raw_ elements (via the
4679 `%fixedspace.att;`_ parameter entity).  It is a fixed attribute, meant
4680 to communicate to an XML parser that the element contains significant
4681 whitespace.  The attribute value should not be set in a document
4682 instance.
4683
4684
4685 .. _title (attribute):
4686
4687 ``title``
4688 =========
4689
4690 `Attribute type`_: ``CDATA``.  Default value: none.
4691
4692 The ``title`` attribute stores the title metadata of a document.  This
4693 title is typically not part of the rendered document.  It may for
4694 example be used in HTML's ``title`` element.
4695
4696
4697 ----------------------------
4698  Parameter Entity Reference
4699 ----------------------------
4700
4701 .. contents:: :local:
4702               :depth: 1
4703
4704 Parameter entities are used to simplify the DTD (to share definitions
4705 and reduce duplication) and to allow the DTD to be customized by
4706 wrapper DTDs (external client DTDs that use or import the Docutils
4707 DTD).  Parameter entities may be overridden by wrapper DTDs, replacing
4708 the definitions below with custom definitions.  Parameter entities
4709 whose names begin with "additional" are meant to allow easy extension
4710 by wrapper DTDs.
4711
4712
4713 ``%anonymous.att;``
4714 ===================
4715
4716 The ``%anonymous.att;`` parameter entity contains the anonymous_
4717 attribute, used for unnamed hyperlinks.
4718
4719 Entity definition:
4720
4721 .. parsed-literal::
4722
4723     anonymous_ %yesorno; #IMPLIED
4724
4725 The reference_ and target_ elements directly employ the
4726 ``%anonymous.att;`` parameter entity in their attribute lists.
4727
4728
4729 ``%auto.att;``
4730 ==============
4731
4732 The ``%auto.att;`` parameter entity contains the auto_ attribute, used
4733 to indicate an automatically-numbered footnote or title.
4734
4735 Entity definition:
4736
4737 .. parsed-literal::
4738
4739     auto_     CDATA     #IMPLIED
4740
4741 The footnote_, footnote_reference_, and title_ elements directly
4742 employ the ``%auto.att;`` parameter entity in their attribute lists.
4743
4744
4745 ``%backrefs.att;``
4746 ==================
4747
4748 The ``%backrefs.att;`` parameter entity contains the backrefs_
4749 attribute, a space-separated list of id references, for backlinks.
4750
4751 Entity definition:
4752
4753 .. parsed-literal::
4754
4755     backrefs_  IDREFS    #IMPLIED
4756
4757 The citation_, footnote_, and system_message_ elements directly employ
4758 the ``%backrefs.att;`` parameter entity in their attribute lists.
4759
4760
4761 ``%basic.atts;``
4762 ================
4763
4764 The ``%basic.atts;`` parameter entity lists attributes common to all
4765 Docutils elements.  See `Common Attributes`_.
4766
4767 Entity definition:
4768
4769 .. parsed-literal::
4770
4771     ids_      NMTOKENS  #IMPLIED
4772     names_    CDATA     #IMPLIED
4773     dupnames_ CDATA     #IMPLIED
4774     source_   CDATA     #IMPLIED
4775     classes_  NMTOKENS  #IMPLIED
4776     %additional.basic.atts;
4777
4778 The ``%additional.basic.atts;`` parameter entity can be used by
4779 wrapper DTDs to extend ``%basic.atts;``.
4780
4781
4782 ``%bibliographic.elements;``
4783 ============================
4784
4785 The ``%bibliographic.elements;`` parameter entity contains an OR-list of all
4786 `bibliographic elements`_.
4787
4788 Entity definition:
4789
4790 .. parsed-literal::
4791
4792     author_ | authors_ | organization_ | contact_ | address_
4793     | version_ | revision_ | status_ | date_ | copyright_
4794     | field_
4795     %additional.bibliographic.elements;
4796
4797 The ``%additional.bibliographic.elements;`` parameter entity can be used by
4798 wrapper DTDs to extend ``%bibliographic.elements;``.
4799
4800 Only the docinfo_ element directly employs the
4801 ``%bibliographic.elements;`` parameter entity in its content model.
4802
4803
4804 ``%body.elements;``
4805 ===================
4806
4807 The ``%body.elements;`` parameter entity contains an OR-list of all
4808 `body elements`_.  ``%body.elements;`` is itself contained within the
4809 `%structure.model;`_ parameter entity.
4810
4811 Entity definition:
4812
4813 .. parsed-literal::
4814
4815     admonition_ | attention_ | block_quote_ | bullet_list_ | caution_
4816     | citation_ | compound_ | comment_ | container_ | danger_ |
4817       definition_list_ | doctest_block_ | enumerated_list_ | error_ |
4818       field_list_ | figure_ | footnote_ | hint_ | image_ | important_
4819       | line_block_ | literal_block_ | note_ | option_list_ |
4820       paragraph_ | pending_ | raw_ reference_ | rubric_ |
4821       substitution_definition_ | system_message_ | table_ | target_ |
4822       tip_ | warning_ %additional.body.elements;
4823
4824 The ``%additional.body.elements;`` parameter entity can be used by
4825 wrapper DTDs to extend ``%body.elements;``.
4826
4827 The ``%body.elements;`` parameter entity is directly employed in the
4828 content models of the following elements: admonition_, attention_,
4829 block_quote_, caution_, citation_, compound_, danger_, definition_,
4830 description_, entry_, error_, field_body_, footer_, footnote_,
4831 header_, hint_, important_, legend_, list_item_, note_, sidebar_,
4832 system_message_, tip_, topic_, warning_
4833
4834 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
4835 indirectly employed in the content models of the document_ and
4836 section_ elements.
4837
4838
4839 ``%fixedspace.att;``
4840 ====================
4841
4842 The ``%fixedspace.att;`` parameter entity contains the `xml:space`_
4843 attribute, a standard XML attribute for whitespace-preserving
4844 elements.
4845
4846 Entity definition:
4847
4848 .. parsed-literal::
4849
4850     `xml:space`_ (default | preserve) #FIXED 'preserve'
4851
4852 The ``%fixedspace.att;`` parameter entity is directly employed in the
4853 attribute lists of the following elements: address_, comment_,
4854 doctest_block_, line_block_, literal_block_, raw_
4855
4856
4857 ``%inline.elements;``
4858 =====================
4859
4860 The ``%inline.elements;`` parameter entity contains an OR-list of all
4861 `inline elements`_.
4862
4863 Entity definition:
4864
4865 .. parsed-literal::
4866
4867     abbreviation_ | acronym_ | citation_reference_ | emphasis_ |
4868     footnote_reference_ | generated_ | image_ | inline_ | literal_ |
4869     problematic_ | raw_ | reference_ | strong_ | substitution_reference_ |
4870     subscript_ | superscript_ | target_ | title_reference_
4871     %additional.inline.elements;
4872
4873 The ``%additional.inline.elements;`` parameter entity can be used by
4874 wrapper DTDs to extend ``%inline.elements;``.
4875
4876 Via `%text.model;`_, the ``%inline.elements;`` parameter entity is
4877 indirectly employed in the content models of the following elements:
4878 abbreviation_, acronym_, address_, attribution_, author_, caption_,
4879 classifier_, contact_, copyright_, date_, doctest_block_, emphasis_,
4880 generated_, inline_, line_block_, literal_block_, math_, math_block_,
4881 organization_,
4882 paragraph_, problematic_, raw_, reference_, revision_, rubric_,
4883 status_, strong_, subscript_, substitution_definition_,
4884 substitution_reference_, subtitle_, superscript_, target_, term_,
4885 title_, title_reference_, version_
4886
4887
4888 ``%reference.atts;``
4889 ====================
4890
4891 The ``%reference.atts;`` parameter entity groups together the refuri_,
4892 refid_, and refname_ attributes.
4893
4894 Entity definition:
4895
4896 .. parsed-literal::
4897
4898     `%refuri.att;`_
4899     `%refid.att;`_
4900     `%refname.att;`_
4901     %additional.reference.atts;
4902
4903 The ``%additional.reference.atts;`` parameter entity can be used by
4904 wrapper DTDs to extend ``%additional.reference.atts;``.
4905
4906 The citation_reference_, footnote_reference_, reference_, and target_
4907 elements directly employ the ``%reference.att;`` parameter entity in
4908 their attribute lists.
4909
4910
4911 ``%refid.att;``
4912 ================
4913
4914 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
4915 internal reference to the `ids`_ attribute of another element.
4916
4917 Entity definition:
4918
4919 .. parsed-literal::
4920
4921     refid_   CDATA     #IMPLIED
4922
4923 The title_ and problematic_ elements directly employ the
4924 ``%refid.att;`` parameter entity in their attribute lists.
4925
4926 Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is
4927 indirectly employed in the attribute lists of the citation_reference_,
4928 footnote_reference_, reference_, and target_ elements.
4929
4930
4931 ``%refname.att;``
4932 =================
4933
4934 The ``%refname.att;`` parameter entity contains the refname_
4935 attribute, an internal reference to the `names`_ attribute of another
4936 element.  On a `target`_ element, ``refname`` indicates an indirect
4937 target which may resolve to either an internal or external
4938 reference.
4939
4940 Entity definition:
4941
4942 .. parsed-literal::
4943
4944     refname_  NMTOKENS  #IMPLIED
4945
4946 The substitution_reference_ element directly employs the
4947 ``%refname.att;`` parameter entity in its attribute list.
4948
4949 Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is
4950 indirectly employed in the attribute lists of the citation_reference_,
4951 footnote_reference_, reference_, and target_ elements.
4952
4953
4954 ``%refuri.att;``
4955 ================
4956
4957 The ``%refuri.att;`` parameter entity contains the refuri_ attribute,
4958 an external reference to a URI/URL.
4959
4960 Entity definition:
4961
4962 .. parsed-literal::
4963
4964     refuri_   CDATA     #IMPLIED
4965
4966 Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is
4967 indirectly employed in the attribute lists of the citation_reference_,
4968 footnote_reference_, reference_, and target_ elements.
4969
4970
4971 ``%section.elements;``
4972 ======================
4973
4974 The ``%section.elements;`` parameter entity contains an OR-list of all
4975 section_-equivalent elements.  ``%section.elements;`` is itself
4976 contained within the `%structure.model;`_ parameter entity.
4977
4978 Entity definition:
4979
4980 .. parsed-literal::
4981
4982     section_
4983     %additional.section.elements;
4984
4985 The ``%additional.section.elements;`` parameter entity can be used
4986 by wrapper DTDs to extend ``%section.elements;``.
4987
4988 Via `%structure.model;`_, the ``%section.elements;`` parameter entity
4989 is indirectly employed in the content models of the document_ and
4990 section_ elements.
4991
4992
4993 ``%structure.model;``
4994 =====================
4995
4996 The ``%structure.model;`` parameter entity encapsulates the
4997 hierarchical structure of a document and of its constituent parts.
4998 See the discussion of the `element hierarchy`_ above.
4999
5000 Entity definition:
5001
5002 .. parsed-literal::
5003
5004    ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*,
5005      ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
5006
5007 Each document_ or section_ contains zero or more body elements,
5008 topics, and/or sidebars, optionally interspersed with single
5009 transitions, followed by zero or more sections (whose contents are
5010 recursively the same as this model) optionally interspersed with
5011 transitions.
5012
5013 The following restrictions are imposed by this model:
5014
5015 * Transitions must be separated by other elements (body elements,
5016   sections, etc.).  In other words, a transition may not be
5017   immediately adjacent to another transition.
5018
5019 * A transition may not occur at the beginning of a document or
5020   section.
5021
5022 An additional restriction, which cannot be expressed in the language
5023 of DTDs, is imposed by software:
5024
5025 * A transition may not occur at the end of a document or section.
5026
5027 The `%structure.model;`_ parameter entity is directly employed in the
5028 content models of the document_ and section_ elements.
5029
5030
5031 ``%text.model;``
5032 ================
5033
5034 The ``%text.model;`` parameter entity is used by many elements to
5035 represent text data mixed with `inline elements`_.
5036
5037 Entity definition:
5038
5039 .. parsed-literal::
5040
5041     (#PCDATA | `%inline.elements;`_)*
5042
5043 The ``%text.model;`` parameter entity is directly employed in the
5044 content models of the following elements: abbreviation_, acronym_,
5045 address_, author_, caption_, classifier_, contact_, copyright_, date_,
5046 doctest_block_, emphasis_, field_name_, generated_, line_block_,
5047 literal_block_, organization_, paragraph_, problematic_, raw_,
5048 reference_, revision_, status_, strong_, substitution_definition_,
5049 substitution_reference_, subtitle_, target_, term_, title_, version_
5050
5051
5052 \f
5053 ..
5054    Local Variables:
5055    mode: indented-text
5056    indent-tabs-mode: nil
5057    sentence-end-double-space: t
5058    fill-column: 70
5059    End: