docutils/docs/ref/doctree.txt

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