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
 156 Decorative Elements
 157 -------------------
 158
 159 Decorative elements are used to generate page headers and footers. They
 160 are child elements of `\<decoration>`_ and contain `body elements`_.
 161
 162 .. class:: field-indent-11em
 163
 164 :Category members: `\<footer>`_, `\<header>`_
 165 :Docutils class:   ``nodes.Decorative``
 166
 167
 168 Bibliographic Elements
 169 ----------------------
 170
 171 Bibliographic elements store document meta-data like title or author.
 172 They are child elements of `\<docinfo>`_.
 173 The elements `\<authors>`_ and `\<field>`_ are `compound elements`_,
 174 the others are `simple elements`_ containing text and `inline elements`_.
 175
 176 .. class:: field-indent-11em
 177
 178 :Category members: `\<address>`_, `\<author>`_, `\<authors>`_,
 179                    `\<contact>`_, `\<copyright>`_, `\<date>`_,
 180                    `\<field>`_, `\<organization>`_, `\<revision>`_,
 181                    `\<status>`_, `\<version>`_
 182 :Docutils class:   ``nodes.Bibliographic``
 183 :Parameter entity: `%bibliographic.elements`_
 184
 185
 186 .. _simple body elements:
 187 .. _compound body elements:
 188
 189 Body Elements
 190 -------------
 191
 192 Body elements are children of the `root element`, `structural elements`_,
 193 or compound body elements. Compound body elements may contain `body
 194 subelements`_ or further body elements.
 195
 196 .. class:: narrow run-in
 197
 198 :Category members:
 199   .. class:: narrow run-in
 200
 201   :empty:
 202     `\<image>`_ , `\<pending>`_
 203   :simple:
 204     `\<comment>`_, `\<doctest_block>`_, `\<literal_block>`_, `\<math_block>`_,
 205     `\<paragraph>`_, `\<raw>`_, `\<reference>`_, `\<rubric>`_,
 206     `\<substitution_definition>`_, `\<target>`_
 207   :compound:
 208     `\<admonition>`_, `\<attention>`_, `\<block_quote>`_, `\<bullet_list>`_,
 209     `\<caution>`_, `\<citation>`_, `\<compound>`_, `\<container>`_,
 210     `\<danger>`_, `\<definition_list>`_, `\<enumerated_list>`_, `\<error>`_,
 211     `\<field_list>`_, `\<figure>`_, `\<footnote>`_, `\<hint>`_,
 212     `\<important>`_, `\<line_block>`_, `\<note>`_, `\<option_list>`_,
 213     `\<system_message>`_, `\<table>`_, `\<tip>`_, `\<warning>`_
 214
 215 :Docutils class: ``nodes.Body``
 216
 217 :Parameter entity: `%body.elements`_
 218
 219
 220 Body Subelements
 221 ----------------
 222
 223 Body subelements always occur within specific parent elements
 224 (e.g. `\<bullet_list>`_ contains `\<list_item>`_), never at the
 225 body element level (beside paragraphs, etc.).
 226 Body subelements may be `compound elements`_ (containing `body elements`_ or
 227 further body subelements) or `simple elements`_.
 228
 229 .. class:: narrow run-in
 230
 231 :Category members:
 232   .. class:: narrow run-in
 233
 234   :empty:
 235     `\<colspec>`_
 236   :simple:
 237     `\<attribution>`_, `\<caption>`_, `\<classifier>`_,
 238     `\<field_name>`_, `\<label>`_, `\<line>`_,
 239     `\<option_argument>`_, `\<option_string>`_, `\<term>`_, `\<title>`_
 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`_
 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:   `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:   <option> elements start with an `\<option_string>`_ and
2813              may contain `\<option_argument>`_ elements::
2814
2815                  (option_string, option_argument*)
2816
2817 :Attributes: The <option> element contains only the `common attributes`_.
2818
2819 Examples
2820 --------
2821 See the examples for the `\<option_list>`_ element.
2822
2823
2824 <option_argument>
2825 =================
2826
2827 The <option_argument> element contains placeholder text for option
2828 arguments.
2829
2830 Details
2831 -------
2832
2833 :Category:   `Body Subelements`_
2834 :Analogues:  <option_argument> has no direct analogues in common DTDs.
2835 :Processing: The value of the "delimiter" attribute is prefixed to the
2836              <option_argument>, separating it from its
2837              `\<option_string>`_ or a preceding <option_argument>.
2838              The <option_argument> text is typically rendered in a
2839              monospaced typeface, possibly italicized or otherwise
2840              altered to indicate its placeholder nature.
2841 :Parents:    Only the `\<option>`_ element contains <option_argument>.
2842 :Children:   <option_argument> elements contain text data only.
2843 :Attributes: The <option_argument> element contains
2844              the `common attributes`_ plus delimiter_.
2845
2846 Examples
2847 --------
2848 See the examples for the `\<option_list>`_ element.
2849
2850
2851 <option_group>
2852 ==============
2853
2854 The <option_group> element groups together one or more `\<option>`_
2855 elements, all synonyms.
2856
2857 Details
2858 -------
2859
2860 :Category:   `Body Subelements`_
2861 :Analogues:  <option_group> has no direct analogues in common DTDs.
2862 :Processing: Typically `\<option>`_ elements within an <option_group> are
2863              joined together in a comma-separated list.
2864 :Parents:    Only the `\<option_list_item>`_ element contains <option_group>.
2865 :Children:   <option_group> elements contain one or more `\<option>`_
2866              elements.
2867 :Attributes: The <option_group> element contains only the `common attributes`_.
2868
2869 Examples
2870 --------
2871 See the examples for the `\<option_list>`_ element.
2872
2873
2874 <option_list>
2875 =============
2876
2877 Each <option_list> element contains a two-column list of command-line
2878 options and descriptions, documenting a program's options.
2879
2880 Details
2881 -------
2882
2883 :Category:   `Compound Body Elements`_
2884 :Analogues:  <option_list> has no direct analogues in common DTDs.
2885              It can be emulated with primitives such as tables.
2886 :Processing: An <option_list> is typically rendered as a two-column list,
2887              where the first column contains option strings and
2888              arguments, and the second column contains descriptions.
2889 :Parents:    All elements employing the `%body.elements`_ or
2890              `%structure.model`_ parameter entities in their
2891              content models may contain <option_list>.
2892 :Children:   <option_list> elements contain one or more `\<option_list_item>`_
2893              elements.
2894 :Attributes: The <option_list> element contains only the `common attributes`_.
2895 :Parameter Entities: The `%body.elements`_ parameter entity
2896              directly includes <option_list>.  The `%structure.model`_
2897              parameter entity indirectly includes <option_list>.
2898
2899 Examples
2900 --------
2901
2902 A reStructuredText `option list`_::
2903
2904     -a            command-line option "a"
2905     -1 file, --one=file, --two file
2906                   Multiple options with arguments.
2907
2908 Pseudo-XML_ fragment from simple parsing::
2909
2910     <option_list>
2911         <option_list_item>
2912             <option_group>
2913                 <option>
2914                     <option_string>
2915                         -a
2916             <description>
2917                 <paragraph>
2918                     command-line option "a"
2919         <option_list_item>
2920             <option_group>
2921                 <option>
2922                     <option_string>
2923                         -1
2924                     <option_argument delimiter=" ">
2925                         file
2926                 <option>
2927                     <option_string>
2928                         --one
2929                     <option_argument delimiter="=">
2930                         file
2931                 <option>
2932                     <option_string>
2933                         --two
2934                     <option_argument delimiter=" ">
2935                         file
2936             <description>
2937                 <paragraph>
2938                     Multiple options with arguments.
2939
2940
2941 <option_list_item>
2942 ==================
2943
2944 The <option_list_item> element is a container for a pair of
2945 `\<option_group>`_ and `\<description>`_ elements.
2946
2947
2948 Details
2949 -------
2950
2951 :Category:   `Body Subelements`_
2952 :Analogues:  <option_list_item> has no direct analogues in common DTDs.
2953 :Processing: See `\<option_list>`_.
2954 :Parents:    Only the `\<option_list>`_ element contains <option_list_item>.
2955 :Children:   Each <option_list_item> element contains one `\<option_group>`_
2956              and one `\<description>`_ element.
2957 :Attributes: The <option_list_item> element contains only the
2958              `common attributes`_.
2959
2960 Examples
2961 --------
2962 See the examples for the `\<option_list>`_ element.
2963
2964
2965 <option_string>
2966 ===============
2967
2968 The <option_string> element contains the text of a command-line option.
2969
2970 Details
2971 -------
2972
2973 :Category:   `Body Subelements`_
2974 :Analogues:  <option_string> has no direct analogues in common DTDs.
2975 :Processing: The <option_string> text is typically rendered in a
2976              monospaced typeface.
2977 :Parents:    Only the `\<option>`_ element contains <option_string>.
2978 :Children:   <option_string> elements contain text data only.
2979 :Attributes: The <option_string> element contains only the
2980              `common attributes`_.
2981
2982 Examples
2983 --------
2984 See the examples for the `\<option_list>`_ element.
2985
2986
2987 <organization>
2988 ==============
2989
2990 The <organization> element contains the name of document author's
2991 organization, or the organization responsible for the document.
2992
2993 Details
2994 -------
2995
2996 :Category:   `Bibliographic Elements`_
2997 :Analogues:  <organization> is analogous to the DocBook_ <orgname>,
2998              <corpname>, or <publishername> elements.
2999 :Processing: See `\<docinfo>`_.
3000 :Parents:    Only the `\<docinfo>`_ element contains <organization>.
3001 :Children:   <organization> elements may contain text data
3002              plus `inline elements`_ (`%text.model`_).
3003 :Attributes: The <organization> element contains only the
3004              `common attributes`_.
3005 :Parameter Entities: The `%bibliographic.elements`_ parameter entity
3006              directly includes <organization>.
3007
3008 Examples
3009 --------
3010
3011 In reStructuredText, "organization" is one of the registered
3012 `bibliographic fields`_::
3013
3014     Document Title
3015     ==============
3016
3017     :Organization: Humankind
3018
3019 Complete pseudo-XML_ result after parsing and applying transforms_::
3020
3021     <document ids="document-title" names="document title">
3022         <title>
3023             Document Title
3024         <docinfo>
3025             <organization>
3026                 Humankind
3027
3028 See `\<docinfo>`_ for a more complete example, including processing
3029 context.
3030
3031
3032 <paragraph>
3033 ===========
3034
3035 The <paragraph> element contains the text and inline elements of a
3036 single paragraph, a fundamental building block of documents.
3037
3038 Details
3039 -------
3040
3041 :Category:   `Simple Body Elements`_
3042 :Analogues:  <paragraph> is analogous to the HTML <p> element
3043              and to the DocBook_ <para> elements.
3044 :Parents:    All elements employing the `%body.elements`_ or
3045              `%structure.model`_ parameter entities in their content models
3046              may contain <paragraph>.
3047 :Children:   <paragraph> elements may contain text data
3048              plus `inline elements`_ (`%text.model`_).
3049 :Attributes: The <paragraph> element contains only the `common attributes`_.
3050 :Parameter Entities: The `%body.elements`_ parameter entity
3051              directly includes <paragraph>.  The `%structure.model`_
3052              parameter entity indirectly includes <paragraph>.
3053
3054 Examples
3055 --------
3056
3057 In reStructuredText_, blocks of left-aligned text are paragraphs unless
3058 marked up as another body element::
3059
3060     A paragraph must be
3061     left-aligned.
3062
3063 Pseudo-XML_ fragment from simple parsing::
3064
3065     <paragraph>
3066         A paragraph must be
3067         left-aligned.
3068
3069
3070 <pending>
3071 =========
3072
3073 `To be completed`_.
3074
3075
3076 <problematic>
3077 =============
3078
3079 `To be completed`_.
3080
3081
3082 <raw>
3083 =====
3084
3085 The <raw> element contains non-reStructuredText data that is to be passed
3086 untouched to the Writer.
3087
3088 Details
3089 -------
3090
3091 :Category:   `Simple Body Elements`_, `Inline Elements`_
3092 :Analogues:  The <raw> element has no direct analogues in common DTDs.
3093 :Processing: Passed untouched to the Writer_.
3094              The interpretation is up to the Writer.
3095              A Writer may ignore <raw> elements not matching its format_.
3096 :Parents:    All elements employing the `%body.elements`_,
3097              `%inline.elements`_, or `%structure.model`_ parameter entities
3098              in their content models may contain <raw>.
3099 :Children:   <raw> elements contain text data only.
3100 :Attributes: The <raw> element contains the `common attributes`_
3101              plus format_ and `xml:space`_.
3102 :Parameter Entities:
3103              The `%body.elements`_ and `%inline.elements`_ parameter
3104              entities directly include <raw>.  The `%structure.model`_
3105              parameter entity indirectly  includes <raw>.
3106
3107 Examples
3108 --------
3109
3110 The reStructuredText `"raw" directive`_ [#]_ creates a <raw> element::
3111
3112     .. raw:: html
3113
3114        <hr width=50 size=10>
3115
3116 Pseudo-XML_ fragment from simple parsing::
3117
3118     <raw format="html" xml:space="preserve">
3119         <hr width=50 size=10>
3120
3121 .. [#] For raw data pass-through in inline context, use `custom
3122    interpreted text roles`_ derived from the `"raw" role`_.
3123
3124
3125 <reference>
3126 ===========
3127
3128 `To be completed`_.
3129
3130
3131 <revision>
3132 ==========
3133
3134 The <revision> element contains the revision number of the document.
3135 It can be used alone or in conjunction with `\<version>`_.
3136
3137 Details
3138 -------
3139
3140 :Category:   `Bibliographic Elements`_
3141 :Analogues:  <revision> is analogous to but simpler than the DocBook_
3142              <revision> element.  It closely matches the DocBook
3143              <revnumber> element, but in a simpler context.
3144 :Processing: Often used with the RCS/CVS keyword "Revision".
3145              See `\<docinfo>`_.
3146 :Parents:    Only the `\<docinfo>`_ element contains <revision>.
3147 :Children:   <revision> elements may contain text data
3148              plus `inline elements`_ (`%text.model`_).
3149 :Attributes: The <revision> element contains only the `common attributes`_.
3150 :Parameter Entities: The `%bibliographic.elements`_ parameter entity
3151              directly includes <revision>.
3152
3153 Examples
3154 --------
3155
3156 In reStructuredText, "revision" is one of the registered
3157 `bibliographic fields`_::
3158
3159     Document Title
3160     ==============
3161
3162     :Version: 1
3163     :Revision: b
3164
3165 Complete pseudo-XML_ result after parsing and applying transforms_::
3166
3167     <document ids="document-title" names="document title">
3168         <title>
3169             Document Title
3170         <docinfo>
3171             <version>
3172                 1
3173             <revision>
3174                 b
3175
3176 See `\<docinfo>`_ for a more complete example, including processing
3177 context.
3178
3179
3180 <row>
3181 =====
3182
3183 `To be completed`_.
3184
3185
3186 <rubric>
3187 ========
3188
3189      rubric n. 1. a title, heading, or the like, in a manuscript,
3190      book, statute, etc., written or printed in red or otherwise
3191      distinguished from the rest of the text. ...
3192
3193      -- Random House Webster's College Dictionary, 1991
3194
3195 A rubric is like an informal heading that doesn't correspond to the
3196 document's structure.
3197
3198 `To be completed`_.
3199
3200
3201 <section>
3202 =========
3203
3204 The <section> element is the main unit of hierarchy for Docutils documents.
3205
3206 The Docutils document model uses a simple, recursive model for section
3207 structure.  A `\<document>`_ node may contain <section> elements.
3208 Sections in turn may contain other <section> elements, without limit.
3209 The level (depth) of a section element is determined from its physical
3210 nesting level.
3211
3212 Paragraphs and other body elements may occur before a <section>,
3213 but not after it.
3214
3215 Details
3216 -------
3217
3218 :Category:   `Structural Elements`_
3219
3220 :Analogues:  <section> is analogous to the section elements in DocBook and
3221              HTML. Unlike ``<h1>`` … ``<h6>`` in HTML_, ``<sect1>`` …
3222              ``<sect5>`` in DocBook_, or ``<div1>`` … in XMLSpec_, the
3223              level is not incorporated into the element name.
3224
3225 :Parents:    The following elements may contain <section>:
3226              `\<document>`_, `\<section>`_
3227
3228 :Children:   <section> elements begin with a `\<title>`_,
3229              followed by an optional `\<subtitle>`_.
3230              They may contain `body elements`_ as well as
3231              `\<transition>`_, `\<topic>`_, and `\<sidebar>`_ elements:
3232
3233              .. parsed-literal::
3234
3235                 (title, subtitle?, `%structure.model`_;)
3236
3237 :Attributes: The <section> element contains only the `common attributes`_.
3238
3239 :Parameter Entities: The `%section.elements`_ parameter entity
3240              directly includes <section>.  The `%structure.model`_
3241              parameter entity indirectly includes <section>.
3242
3243 Examples
3244 --------
3245
3246 reStructuredText does not impose a fixed number and order of section_
3247 title adornment styles. The order enforced will be the order as
3248 encountered. ::
3249
3250     Title 1
3251     =======
3252     Paragraph 1.
3253
3254     Title 2
3255     -------
3256     Paragraph 2.
3257
3258     Title 3
3259     =======
3260     Paragraph 3.
3261
3262     Title 4
3263     -------
3264     Paragraph 4.
3265
3266 Complete pseudo-XML_ result after parsing::
3267
3268     <document>
3269         <section ids="title-1" names="title 1">
3270             <title>
3271                 Title 1
3272             <paragraph>
3273                 Paragraph 1.
3274             <section ids="title-2" names="title 2">
3275                 <title>
3276                     Title 2
3277                 <paragraph>
3278                     Paragraph 2.
3279         <section ids="title-3" names="title 3">
3280             <title>
3281                 Title 3
3282             <paragraph>
3283                 Paragraph 3.
3284             <section ids="title-4" names="title 4">
3285                 <title>
3286                     Title 4
3287                 <paragraph>
3288                     Paragraph 4.
3289
3290
3291 <sidebar>
3292 =========
3293
3294 Sidebars are like miniature, parallel documents that occur inside other
3295 documents, providing related or reference material.
3296 A <sidebar> is typically offset by a border and "floats" to the side of
3297 the page; the document's main text may flow around it.  Sidebars can also
3298 be likened to super-footnotes; their content is outside of the flow of
3299 the document's main text.
3300
3301 The <sidebar> element is a non-recursive `\<section>`_-like construct
3302 which may occur at the top level of a `\<section>`_ wherever a body
3303 element (list, table, etc.) is allowed.  In other words, <sidebar>
3304 elements cannot nest inside body elements, so you can't have a <sidebar>
3305 inside a ``table`` or a ``list``, or inside another <sidebar> or
3306 `\<topic>`_.
3307
3308 Details
3309 -------
3310
3311 :Category:   `Structural Elements`_
3312
3313 :Analogues:  <sidebar> is analogous to the DocBook_ <sidebar> and
3314              the HTML <aside> elements.
3315
3316 :Processing: A <sidebar> element should be set off from the rest of the
3317              document somehow, typically with a border.  Sidebars
3318              typically "float" to the side of the page and the document's
3319              main text flows around them.
3320
3321 :Parents:    The following elements may contain <sidebar>:
3322              `\<document>`_, `\<section>`_.
3323
3324 :Children:   <sidebar> elements begin with optional
3325              `\<title>`_ and `\<subtitle>`_ and contain
3326              `body elements`_ and `\<topic>`_ elements.
3327              There must not be a <subtitle> without title. ::
3328
3329                ((title, subtitle?)?,
3330                 (%body.elements; | topic)+)
3331
3332 :Attributes: The <sidebar> element contains only the `common attributes`_.
3333
3334 :Parameter Entities: The `%structure.model`_ parameter entity
3335              directly includes <sidebar>.
3336
3337
3338 Examples
3339 --------
3340
3341 A reStructuredText `"sidebar" directive`_::
3342
3343     .. sidebar:: Optional Title
3344        :subtitle: If Desired
3345
3346        Body.
3347
3348 Pseudo-XML_ fragment from simple parsing::
3349
3350     <sidebar>
3351         <title>
3352             Optional Title
3353         <subtitle>
3354             If Desired
3355         <paragraph>
3356             Body.
3357
3358
3359 <status>
3360 ========
3361
3362 The <status> element contains a status statement for the document,
3363 such as "Draft", "Final", "Work In Progress", etc.
3364
3365 Details
3366 -------
3367
3368 :Category:   `Bibliographic Elements`_
3369 :Analogues:  <status> is analogous to the DocBook_ <status> element.
3370 :Processing: See `\<docinfo>`_.
3371 :Parents:    Only the `\<docinfo>`_ element contains <status>.
3372 :Children:   <status> elements may contain text data
3373              plus `inline elements`_ (`%text.model`_).
3374 :Attributes: The <status> element contains only the `common attributes`_.
3375 :Parameter Entities: The `%bibliographic.elements`_ parameter entity
3376              directly includes <status>.
3377
3378 Examples
3379 --------
3380
3381 In reStructuredText, "status" is one of the registered
3382 `bibliographic fields`_::
3383
3384     Document Title
3385     ==============
3386
3387     :Status: Work In Progress
3388
3389 Complete pseudo-XML_ result after parsing and applying transforms_::
3390
3391     <document ids="document-title" names="document title">
3392         <title>
3393             Document Title
3394         <docinfo>
3395             <status>
3396                 Work In Progress
3397
3398 See `\<docinfo>`_ for a more complete example, including processing
3399 context.
3400
3401
3402 <strong>
3403 ========
3404
3405 The <strong> element is an inline element representing
3406 text that has strong importance, seriousness, or urgency.
3407
3408 Details
3409 -------
3410
3411 :Category:   `Inline Elements`_
3412 :Analogues:  <strong> is analogous to the HTML_ <strong> element.
3413 :Processing: Typically displayed in boldface.
3414 :Parents:    All elements employing the `%inline.elements`_ parameter
3415              entity in their content models may contain <strong>.
3416 :Children:   <strong> elements may contain text data
3417              plus `inline elements`_ (`%text.model`_).
3418 :Attributes: The <strong> element contains only the `common attributes`_.
3419
3420 Examples
3421 --------
3422
3423 The reStructuredText there are two alternatives to mark text with
3424 `strong emphasis`_::
3425
3426     There are :strong:`two` ways to **strongly emphasize** text.
3427
3428 Pseudo-XML_ fragment from simple parsing::
3429
3430     <paragraph>
3431         There are
3432         <strong>
3433             two
3434          ways to
3435         <strong>
3436             strongly emphasize
3437          text.
3438
3439
3440 <subscript>
3441 ===========
3442
3443 The <subscript> element is an inline element representing text which
3444 should be displayed as subscript.
3445
3446 Details
3447 -------
3448
3449 :Category:   `Inline Elements`_
3450 :Analogues:  <subscript> is analogous to the HTML_ <sub> element
3451              and the DocBook_ <subscript> element.
3452 :Processing: Typically rendered with a lowered baseline using smaller text.
3453 :Parents:    All elements employing the `%inline.elements`_ parameter
3454              entity in their content models may contain <subscript>.
3455 :Children:   <subscript> elements may contain text data
3456              plus `inline elements`_ (`%text.model`_).
3457 :Attributes: The <subscript> element contains only the `common attributes`_.
3458
3459 Examples
3460 --------
3461
3462 The reStructuredText `"subscript" role`_ creates a <subscript> element::
3463
3464     The chemical formula for water is H\ :sub:`2`\ O.
3465
3466 Pseudo-XML_ fragment from simple parsing::
3467
3468     <paragraph>
3469         The chemical formula for water is H
3470         <subscript>
3471             2
3472         O.
3473
3474
3475 <substitution_definition>
3476 =========================
3477
3478 The <substitution_definition> element stores a
3479 reStructuredText `substitution definition`_.
3480
3481 `To be completed`_.
3482
3483
3484 <substitution_reference>
3485 ========================
3486
3487 `To be completed`_.
3488
3489
3490 <subtitle>
3491 ==========
3492
3493 The <subtitle> element stores the subtitle of a `\<document>`_,
3494 `\<section>`, or `\<sidebar>`.
3495
3496 Details
3497 -------
3498
3499 :Category:   `Structural Subelements`_
3500 :Analogues:  <subtitle> is analogous to the DocBook_ <subtitle> element.
3501              In HTML, subtitles are represented by a <p> element inside
3502              a <hgroup_> element.
3503 :Processing: A document's subtitle is usually rendered smaller
3504              than its `\<title>`_.
3505 :Parents:    The `\<document>`_, `\<section>`, and `\<sidebar>`_ elements
3506              may contain <subtitle>.
3507 :Children:   <subtitle> elements may contain text data
3508              plus `inline elements`_ (`%text.model`_).
3509 :Attributes: The <subtitle> element contains only the `common attributes`_.
3510
3511 Examples
3512 --------
3513
3514 In reStructuredText, a lone second-level section title immediately after
3515 the “document title” can become the document subtitle::
3516
3517     =======
3518      Title
3519     =======
3520     ----------
3521      Subtitle
3522     ----------
3523
3524     A paragraph.
3525
3526 Complete pseudo-XML_ result after parsing and applying the
3527 `DocTitle transform`_::
3528
3529     <document ids="title" names="title">
3530         <title>
3531             Title
3532         <subtitle ids="subtitle" names="subtitle">
3533             Subtitle
3534         <paragraph>
3535             A paragraph.
3536
3537 Note how two section levels have collapsed, promoting their titles to
3538 become the document's title and subtitle.  Since there is only one
3539 structural element (document), the subsection's ``ids`` and ``names``
3540 attributes are stored in the <subtitle> element.
3541
3542 .. _hgroup: https://html.spec.whatwg.org/multipage/sections.html
3543             #the-hgroup-element
3544
3545
3546 <superscript>
3547 =============
3548
3549 The <superscript> element is an inline element representing text which
3550 should be displayed as superscript.
3551
3552 Details
3553 -------
3554
3555 :Category:   `Inline Elements`_
3556 :Analogues:  <superscript> is analogous to the HTML_ <sup> element
3557              and the DocBook_ <superscript> element.
3558 :Processing: Typically rendered with a raised baseline using smaller text.
3559 :Parents:    All elements employing the `%inline.elements`_ parameter
3560              entity in their content models may contain <superscript>.
3561 :Children:   <superscript> elements may contain text data
3562              plus `inline elements`_ (`%text.model`_).
3563 :Attributes: The <superscript> element contains only the `common attributes`_.
3564
3565 Examples
3566 --------
3567
3568 The reStructuredText `"superscript" role`_ creates a <superscript> element::
3569
3570     Key events of the 20\ :sup:`th` century.
3571
3572 Pseudo-XML_ fragment from simple parsing::
3573
3574     <paragraph>
3575         Key events of the 20
3576         <superscript>
3577             th
3578          century.
3579
3580
3581 <system_message>
3582 ================
3583
3584 `To be completed`_.
3585
3586
3587 <table>
3588 =======
3589
3590 The <table> element identifies a data arrangement with rows and columns.
3591 It is defined in the `XML Exchange Table Model DTD` [tm9901]_. [#]_
3592
3593 .. [#] The interpretation of column widths in `\<colspec>`_ differs from the
3594    specification.
3595
3596 Details
3597 -------
3598
3599 :Category:   `Compound Body Elements`_
3600
3601 :Analogues:  <table> is analogous to the HTML <table> element and the
3602              DocBook_ <table> and <informaltable> elements.
3603
3604 :Processing: Content is rendered in rows and columns.
3605
3606 :Parents:    All elements employing the `%body.elements`_ or
3607              `%structure.model`_ parameter entities in their
3608              content models may contain <table>.
3609
3610 :Children:   <table> elements begin with an optional `\<title>`_ (caption)
3611              and may contain one or more `\<tgroup>`_ elements. ::
3612
3613                (title?, tgroup+)
3614
3615 :Attributes: The <table> element contains the `common attributes`_ plus
3616              align_, and width_ as well as the attributes "frame", colsep_,
3617              rowsep_, and "pgwide" defined in the exchange-table-model_.
3618
3619 :Parameter Entities: The `%body.elements`_ parameter entity
3620              directly includes <table>.  The `%structure.model`_
3621              parameter entity indirectly includes <table>.
3622
3623 Examples
3624 --------
3625
3626 In reStructuredText, tables can be specified via the
3627 `"table" <"table" directive_>`__, `"csv-table"`_, or `"list-table"`_
3628 directives or directly as `grid table`_ or `simple table`_, e.g. ::
3629
3630     ======== ====
3631      bread   £2
3632      butter  £30
3633     ======== ====
3634
3635 Pseudo-XML_ fragment from simple parsing::
3636
3637     <table>
3638         <tgroup cols="2">
3639             <colspec colwidth="8">
3640             <colspec colwidth="4">
3641             <tbody>
3642                 <row>
3643                     <entry>
3644                         <paragraph>
3645                             bread
3646                     <entry>
3647                         <paragraph>
3648                             £2
3649                 <row>
3650                     <entry>
3651                         <paragraph>
3652                             butter
3653                     <entry>
3654                         <paragraph>
3655                             £30
3656
3657
3658 <target>
3659 ========
3660
3661 `To be completed`_.
3662
3663
3664 <tbody>
3665 =======
3666
3667 `To be completed`_.
3668
3669
3670 <term>
3671 ======
3672
3673 The <term> element contains a word or phrase being defined in a
3674 `\<definition_list>`_.
3675
3676 Details
3677 -------
3678
3679 :Category:   `Body Subelements`_ (simple)
3680 :Analogues:  <term> is analogous to the HTML <dt> element
3681              and to the DocBook_ <term> element.
3682 :Processing: See `\<definition_list_item>`_.
3683 :Parents:    Only the `\<definition_list_item>`_ element contains <term>.
3684 :Children:   <term> elements may contain text data
3685              plus `inline elements`_ (`%text.model`_).
3686 :Attributes: The <term> element contains only the `common attributes`_.
3687
3688 Examples
3689 --------
3690 See the examples for the `\<definition_list>`_,
3691 `\<definition_list_item>`_, and `\<classifier>`_ elements.
3692
3693
3694 <tgroup>
3695 ========
3696
3697 See [exchange-table-model]_. ::
3698
3699     (colspec*, thead?, tbody)
3700
3701 `To be completed`_.
3702
3703
3704 <thead>
3705 =======
3706
3707 `To be completed`_.
3708
3709
3710 <tip>
3711 =====
3712
3713 The <tip> element is an *admonition*, a distinctive and self-contained notice.
3714 See also the generic `\<admonition>`_ and the other specific admonition
3715 elements `\<attention>`_, `\<caution>`_, `\<danger>`_,
3716 `\<error>`_, `\<hint>`_, `\<note>`_, and `\<warning>`_.
3717
3718 Details
3719 -------
3720
3721 :Category:   `Compound Body Elements`_
3722 :Analogues:  <tip> is analogous to the `DocBook \<tip>`_ element.
3723 :Processing: Rendered distinctly (inset and/or in a box, etc.),
3724              with the generated title "Tip" (or similar).
3725 :Parents:    All elements employing the `%body.elements`_ or
3726              `%structure.model`_ parameter entities in their content models
3727              may contain <tip>.
3728 :Children:   <tip> elements contain one or more `body elements`_.
3729 :Attributes: The <tip> element contains only the `common attributes`_.
3730 :Parameter Entities: The `%body.elements`_ parameter entity
3731              directly includes <tip>. The `%structure.model`_
3732              parameter entity indirectly includes <tip>.
3733
3734 Examples
3735 --------
3736
3737 A reStructuredText `"tip" directive`_::
3738
3739     .. Tip:: 15% if the service is good.
3740
3741 Pseudo-XML_ fragment from simple parsing::
3742
3743     <tip>
3744         <paragraph>
3745             15% if the service is good.
3746
3747
3748 <title>
3749 =======
3750
3751 The <title> element stores the title of a `\<document>`_, `structural
3752 elements`_, or a generic `\<admonition>`_.
3753
3754 The title of a <document> may differ from its *metadata title*
3755 stored in the `title attribute`_.
3756
3757 Details
3758 -------
3759
3760 :Category:   `Structural Subelements`_, `Body Subelements`_
3761 :Analogues:  <title> is analogous to HTML_ header elements (<h1> etc.)
3762              and to the DocBook_ <title> element.
3763              In contrast, the HTML <title> element corresponds to a
3764              <document>'s `title attribute`_.
3765              As child of a `\<table>`_, <title> corresponds to
3766              the HTML <caption> element.
3767 :Parents:    The following elements may contain <title>:
3768              `\<admonition>`_, `\<document>`_, `\<section>`_,
3769              `\<sidebar>`_, `\<table>`_, `\<topic>`_.
3770 :Children:   <title> elements may contain text data
3771              plus `inline elements`_ (`%text.model`_).
3772 :Attributes: The <title> element contains the `common attributes`_
3773              plus refid_ (used as a backlink to a table of contents entry)
3774              and auto_.
3775
3776 Examples
3777 --------
3778
3779 Section_ titles are marked up with "underlines" below the title text (or
3780 underlines and matching overlines)::
3781
3782     A Title
3783     =======
3784
3785     A paragraph.
3786
3787     The next section's title
3788     ========================
3789
3790 Pseudo-XML_ fragment from simple parsing::
3791
3792     <section ids="a-title" names="a\ title">
3793         <title>
3794             A Title
3795         <paragraph>
3796             A paragraph.
3797     <section ids="the-next-section-s-title" names="the\ next\ section's\ title">
3798         <title>
3799             The next section’s title
3800
3801 See also the examples for `\<admonition>`_, `\<document>`_,
3802 `\<section>`_, `\<sidebar>`_, `\<subtitle>`_, `\<table>`_,
3803 and `\<topic>`_.
3804
3805
3806 <title_reference>
3807 =================
3808
3809 The <title_reference> element is an inline element representing
3810 the titles of a cited creative work.
3811
3812 Details
3813 -------
3814
3815 :Category:   `Inline Elements`_
3816 :Analogues:  <title_reference> is analogous to the HTML_ <cite> element
3817              and the DocBook_ <citetitle> element.
3818 :Processing: Typically displayed in italic type.
3819 :Parents:    All elements employing the `%inline.elements`_ parameter
3820              entity in their content models may contain <title_reference>.
3821 :Children:   <title_reference> elements may contain text data
3822              plus `inline elements`_ (`%text.model`_).
3823 :Attributes: The <title_reference> element contains only the `common attributes`_.
3824
3825 Examples
3826 --------
3827
3828 The reStructuredText `"title-reference" role`_ creates a <title_reference>
3829 element::
3830
3831     The term "spam" is derived from the 1970 :title:`Spam` sketch.
3832
3833
3834 Pseudo-XML_ fragment from simple parsing::
3835
3836     <paragraph>
3837         The term “spam” is derived from the 1970
3838         <title_reference>
3839             Spam
3840          sketch.
3841
3842
3843 <topic>
3844 =======
3845
3846 The <topic> element is a non-recursive section-like construct which may
3847 occur at the top level of a `\<document>`_, `\<section>`_, or `\<sidebar>`_
3848 wherever a body element (list, table, etc.) is allowed.  In other words,
3849 <topic> elements cannot nest inside body elements. You may use a
3850 `\<rubric>`_ element to get an informal heading inside a <table>
3851 or a <list>, or inside another <topic>.
3852
3853 Docutils uses the <topic> element also for a generated `table of contents`_,
3854 and the "abstract" and "dedication" `bibliographic fields`_.
3855
3856 Details
3857 -------
3858
3859 :Category:   `Structural Elements`_
3860
3861 :Analogues:  <topic> is analogous to the DocBook_ <simplesect> element.
3862
3863 :Processing: A <topic> element should be set off from the rest of the
3864              document somehow, such as with indentation or a border.
3865
3866 :Parents:    The following elements may contain <topic>:
3867              `\<document>`_, `\<section>`_, `\<sidebar>`_
3868
3869 :Children:   <topic> elements may begin with a `\<title>`_ and contain
3870              `body elements`_::
3871
3872                  (title?, (%body.elements;)+)
3873
3874 :Attributes: The <topic> element contains the `common attributes`_ plus
3875              depth_ and local_.
3876
3877 :Parameter Entities: The `%structure.model`_ parameter entity
3878              directly includes <topic>.
3879
3880 Examples
3881 --------
3882
3883 A reStructuredText `"topic" directive`_::
3884
3885     .. topic:: Title
3886
3887        Body.
3888
3889 Pseudo-XML_ fragment from simple parsing::
3890
3891     <topic>
3892         <title>
3893             Title
3894         <paragraph>
3895             Body.
3896
3897
3898 <transition>
3899 ============
3900
3901 The <transition> element is commonly seen in novels and short
3902 fiction, as a gap spanning one or more lines, with or without a type
3903 ornament such as a row of asterisks.
3904
3905 Transitions separate body elements and sections, dividing a section into
3906 untitled divisions.  A transition may not begin or end a section [#]_ or
3907 document, nor may two transitions be immediately adjacent.
3908
3909 See also `Doctree Representation of Transitions`__ in
3910 `A Record of reStructuredText Syntax Alternatives`__.
3911
3912 .. [#] In reStructuredText markup, a transition may appear to fall at
3913    the end of a section immediately before another section.  A
3914    transform recognizes this case and moves the transition so it
3915    separates the sections.
3916
3917 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
3918 __ ../dev/rst/alternatives.html
3919
3920 Details
3921 -------
3922
3923 :Category:   `Structural Subelements`_
3924 :Analogues:  <transition> is analogous to the HTML <hr> element.
3925 :Processing: The <transition> element is typically rendered as vertical
3926              whitespace (more than that separating paragraphs), with or
3927              without a horizontal line or row of asterisks.  In novels,
3928              transitions are often represented as a row of three
3929              well-spaced asterisks with vertical space above and below.
3930 :Parents:    The following elements may contain <transition>:
3931              `\<document>`_, `\<section>`_
3932 :Children:   The <transition> element has no content.
3933 :Attributes: The <transition> element contains only the `common attributes`_.
3934 :Parameter Entities: The `%structure.model`_ parameter entity
3935              directly includes <transition>.
3936
3937 Examples
3938 --------
3939
3940 A transition_ in the reStructuredText source::
3941
3942     Paragraph 1.
3943
3944     --------
3945
3946     Paragraph 2.
3947
3948 Complete pseudo-XML_ result after parsing::
3949
3950     <document>
3951         <paragraph>
3952             Paragraph 1.
3953         <transition>
3954         <paragraph>
3955             Paragraph 2.
3956
3957
3958 <version>
3959 =========
3960
3961 The <version> element contains the version number of the document.
3962 It can be used alone or in conjunction with `\<revision>`_.
3963
3964 Details
3965 -------
3966
3967 :Category:   `Bibliographic Elements`_
3968 :Analogues:  <version> may be considered analogous to the DocBook_
3969              <revision>, <revnumber>, or <biblioid> elements.
3970 :Processing: Sometimes used with the RCS/CVS keyword "Revision".
3971              See `\<docinfo>`_ and `\<revision>`_.
3972 :Parents:    Only the `\<docinfo>`_ element contains <version>.
3973 :Children:   <version> elements may contain text data
3974              plus `inline elements`_ (`%text.model`_).
3975 :Attributes: The <version> element contains only the `common attributes`_.
3976 :Parameter Entities: The `%bibliographic.elements`_ parameter entity
3977              directly includes <version>.
3978
3979 Examples
3980 --------
3981
3982 In reStructuredText, "version" is one of the registered
3983 `bibliographic fields`_::
3984
3985     Document Title
3986     ==============
3987
3988     :Version: 1.1
3989
3990 Complete pseudo-XML_ result after parsing and applying transforms_::
3991
3992     <document ids="document-title" names="document title">
3993         <title>
3994             Document Title
3995         <docinfo>
3996             <version>
3997                 1.1
3998
3999 See `\<docinfo>`_ for a more complete example, including processing
4000 context.
4001
4002
4003 <warning>
4004 =========
4005
4006 The <warning> element is an *admonition*, a distinctive and
4007 self-contained notice.  See also the generic `\<admonition>`_
4008 and the other specific admonition elements `\<attention>`_,
4009 `\<caution>`_, `\<danger>`_, `\<error>`_, `\<hint>`_,
4010 `\<important>`_, `\<note>`_, and `\<tip>`_.
4011
4012 Details
4013 -------
4014
4015 :Category:   `Compound Body Elements`_
4016 :Analogues:  <warning> is analogous to the `DocBook \<warning>`_ element.
4017 :Processing: Rendered distinctly (inset and/or in a box, etc.),
4018              with the generated title "Warning" (or similar).
4019 :Parents:    All elements employing the `%body.elements`_ or
4020              `%structure.model`_ parameter entities in their content models
4021              may contain <warning>.
4022 :Children:   <warning> elements contain one or more `body elements`_.
4023 :Attributes: The <warning> element contains only the `common attributes`_.
4024 :Parameter Entities: The `%body.elements`_ parameter entity
4025              directly includes <warning>.  The `%structure.model`_
4026              parameter entity indirectly includes <warning>.
4027
4028 Examples
4029 --------
4030
4031 A reStructuredText `"warning" directive`_::
4032
4033     .. WARNING:: Reader discretion is strongly advised.
4034
4035 Pseudo-XML_ fragment from simple parsing::
4036
4037     <warning>
4038         <paragraph>
4039             Reader discretion is strongly advised.
4040
4041
4042 ---------------
4043 Attribute Types
4044 ---------------
4045
4046 *Standard attribute types* are defined in the `attribute types
4047 <XML attribute types_>`__ section of the `XML 1.0 specification`_.
4048
4049 _`CDATA`
4050     Character data.  CDATA attributes may contain arbitrary text.
4051
4052 _`NMTOKEN`
4053     A "name token".  One or more of letters, digits, ".", "-", and
4054     "_".
4055
4056 _`NMTOKENS`
4057     One or more space-separated NMTOKEN_ values.
4058
4059 _`EnumeratedType`
4060     The attribute value may be one of a specified list of values.
4061
4062 .. _custom attribute types:
4063
4064 The Docutils DTD defines *custom attribute types* via `parameter entities
4065 <parameter entity reference_>`__ that resolve to standard attribute types
4066 to highlight specific attribute value constraints.
4067 In the docutils.nodes_ reference implementation, values are stored using
4068 the specified Python data types.
4069
4070 _`%classnames.type`
4071   | Space-separated list of `class names`_.  Resolves to NMTOKEN_.
4072   | Used in the `classes`_ attribute.  Python data type: ``list[str]``.
4073
4074 _`%idref.type`
4075   | A reference to another element by its identifier_.
4076     Resolves to NMTOKEN_. [#id-vc]_
4077   | Used in the `refid`_ attribute.  Python data type: ``str``.
4078
4079   .. _identifier: identifiers_
4080
4081 _`%idrefs.type`
4082   | Space separated list of references to other elements by their identifiers_.
4083     Resolves to NMTOKENS_. [#id-vc]_
4084   | Used in the `backrefs`_ attribute.  Python data type: ``list[str]``.
4085
4086 _`%ids.type`
4087   | A space-separated list of unique `identifiers`_.
4088     Resolves to NMTOKENS_. [#id-vc]_
4089   | Used in the `ids`_ attribute.  Python data type: ``list[str]``.
4090
4091 _`%measure`
4092   | A number which may be immediately followed by a unit or percent sign.
4093     Resolves to CDATA_.
4094   | Used in the `height`_ and `width`_ attributes.  Python data type: ``str``.
4095
4096 _`%number`
4097   | The attribute value must be a positive interger.  Resolves to NMTOKEN_.
4098   | Used in the `level`_, `morecols`_, `scale`_, and `start`_ attributes.
4099     Python data type: ``int``.
4100
4101 _`%refname.type`
4102   | A `reference name`_.  Resolves to CDATA_.
4103   | Used in the `refname`_ attribute.  Python data type: ``str``.
4104
4105 _`%refnames.type`
4106   | Space-separated list of `reference names`_.  Resolves to CDATA_.
4107   | Used in the `names`_ and `dupnames`_ attributes.
4108     Python data type: ``list[str]``.
4109
4110   Backslash escaping is used for space characters inside a `reference
4111   name`.
4112
4113 _`%yesorno`
4114   | Boolean: False if zero ("0"), true for any other value.
4115     Resolves to NMTOKEN_.
4116   | Used in the `anonymous`_, `ltrim`_, `rtrim`_, and `stub`_ attributes.
4117     Python data type: ``int``.
4118
4119 .. _XML 1.0 specification: https://www.w3.org/TR/REC-xml
4120 .. _XML attribute types: https://www.w3.org/TR/REC-xml/#sec-attribute-types
4121 .. _One ID per Element Type: https://www.w3.org/TR/REC-xml/#one-id-per-el
4122
4123
4124 Names and identifiers
4125 =====================
4126
4127 .. class:: description
4128
4129 _`Class names`
4130   define sub-classes of existing elements.
4131
4132   Docutils employs the `identifier normalization`_ to ensure class names
4133   conform to both, HTML4.1 and CSS1.0 `name` requirements (the regular
4134   expression ``[a-z](-?[a-z0-9]+)*``).
4135
4136   In reStructuredText, custom class names can be specified using the
4137   `"class" directive`_, a directive's `class option`_, or `custom
4138   interpreted text roles`_.
4139
4140   Class names are used in the classes_ attribute (`%classnames.type`_).
4141
4142   .. _reference name:
4143
4144 _`Reference names`
4145   are identifiers assigned in the markup.
4146
4147   Reference names may consist of any text.
4148   Whitespace is normalized. [#whitespace-normalization]_
4149
4150   In reStructuredText, `reference names <rST reference names_>`__
4151   originate from `internal hyperlink targets`_, a directive's `name
4152   option`_, or the element's title or content and are used for internal
4153   cross-references.
4154
4155   Hyperlinks_, footnotes_, and citations_ all share the same namespace
4156   for reference names. Comparison ignores case.
4157
4158   Substitutions_ use a distinct namespace.  Comparison is case-sensitive
4159   but forgiving.
4160
4161   Reference names are used in the name_, names_, refname_, and dupnames_
4162   attributes (`%refname.type`_ or `%refnames.type`_).
4163
4164 _`Identifiers`
4165   are used for cross references in generated documents.
4166
4167   Docutils employs the `identifier normalization`_ to comply with
4168   restrictions in the supported output formats (HTML4.1__, HTML5__,
4169   `polyglot HTML`__, LaTeX__, ODT__, manpage, XML__).
4170
4171   Identifiers cannot be specified directly in reStructuredText.
4172   Docutils generates them from `reference names`_ or from the
4173   auto_id_prefix_, prepending the id_prefix_ and appending numbers
4174   for disambiguation if required.
4175
4176   Identifiers are used in the ids_, refid_, and backrefs_ attributes
4177   (`%ids.type`_, `%idref.type`_, or `%idrefs.type`_) [#id-vc]_.
4178
4179 .. [#whitespace-normalization] Adjacent spaces, horizontal or vertical
4180    tabs, newlines, carriage returns, or form feeds, are replaced by a
4181    single space.  Leading and trailing whitespace is removed.
4182
4183 .. [#id-vc] Docutils cannot use the ID, IDREF, and IDREFS standard types
4184    because it does not adhere to the `One ID per Element Type`_ validity
4185    constraint.
4186
4187 __ https://www.w3.org/TR/html401/types.html#type-name
4188 __ https://www.w3.org/TR/html50/dom.html#the-id-attribute
4189 __ https://www.w3.org/TR/html-polyglot/#id-attribute
4190 __ https://tex.stackexchange.com/questions/18311/
4191    what-are-the-valid-names-as-labels
4192 __ https://help.libreoffice.org/6.3/en-US/text/swriter/01/04040000.html
4193    ?DbPAR=WRITER#bm_id4974211
4194 __ `XML attribute types`_
4195
4196
4197 -----------------
4198 Common Attributes
4199 -----------------
4200
4201 Through the `%basic.atts`_ parameter entity, all elements support the
4202 following attributes: ids_, names_ or dupnames_, source_, and classes_.
4203
4204
4205 ---------------------
4206  Attribute Reference
4207 ---------------------
4208
4209 .. contents:: :local:
4210               :depth: 1
4211
4212 ``alt``
4213 =======
4214
4215 Attribute type: `CDATA`_.  Default value: none.
4216
4217 The ``alt`` attribute is used to store a text description in the
4218 `\<image>`_ element.
4219
4220
4221 ``align``
4222 =========
4223
4224 Attribute type: `CDATA`_.  Default value: none (inherit).
4225
4226 The ``align`` attribute is used in the `\<figure>`_,
4227 `\<image>`_, `\<table>`_, and `\<tgroup>`_ elements
4228 (via the `%align-h.att`_ and `%align-hv.att`_ parameter entities).
4229
4230
4231 ``anonymous``
4232 =============
4233
4234 Attribute type: `%yesorno`_.  Default value: none (implies no).
4235
4236 The ``anonymous`` attribute is used for unnamed hyperlinks in the
4237 `\<target>`_ and `\<reference>`_ elements (via the `%anonymous.att`_
4238 parameter entity).
4239
4240
4241 ``auto``
4242 ========
4243
4244 Attribute type: `CDATA`_.  Default value: none.
4245
4246 The ``auto`` attribute is used to indicate automatically-numbered
4247 `\<footnote>`_, `\<footnote_reference>`_ and `\<title>`_ elements
4248 (via the `%auto.att`_ parameter entity).
4249
4250
4251 ``backrefs``
4252 ============
4253
4254 Attribute type: `%idrefs.type`_.  Default value: none.
4255
4256 The ``backrefs`` attribute contains a space-separated list of identifier_
4257 references, used for backlinks from `\<footnote>`_, `\<citation>`_, and
4258 `\<system_message>`_ elements (via the `%backrefs.att`_ parameter entity).
4259
4260
4261 ``bullet``
4262 ==========
4263
4264 Attribute type: `CDATA`_.  Default value: none.
4265
4266 The ``bullet`` attribute is used in the `\<bullet_list>`_ element to
4267 record the style of bullet from the input data.  In documents processed
4268 from reStructuredText_, it contains one of "-", "+", or "*".
4269 It may be ignored in processing.
4270
4271
4272 ``classes``
4273 ===========
4274
4275 Attribute type: `%classnames.type`_.  Default value: none.
4276
4277 The ``classes`` attribute is a space separated list containing zero or
4278 more `class names`_.
4279
4280 The purpose of the attribute is to indicate an "is-a" variant relationship,
4281 to allow an extensible way of defining sub-classes of existing elements.
4282 It can be used to carry context forward between a Docutils Reader_ and
4283 Writer_, when a custom structure is reduced to a standardized document
4284 tree.  One common use is in conjunction with stylesheets, to add
4285 selection criteria. It should not be used to carry formatting
4286 instructions or arbitrary content.
4287
4288 The ``classes`` attribute's contents should be ignorable.  Writers that
4289 are not familiar with the variant expressed should be able to ignore
4290 the attribute.
4291
4292 ``classes`` is one of the `common attributes`_, shared by all
4293 Docutils elements.
4294
4295 .. _reader: ../peps/pep-0258.html#readers
4296 .. _writer:
4297 .. _writers: ../peps/pep-0258.html#writers
4298
4299
4300 ``cols``
4301 =========
4302
4303 Attribute type: NMTOKEN_.  Default value: none.
4304
4305 The ``cols`` attribute is used in the `\<tgroup>`_ element.
4306
4307 ``colsep``
4308 ==========
4309
4310 Attribute type: `%yesorno`_.  Default value: none (implies no).
4311
4312 The ``colsep`` attribute is used in the `\<table>`_ and `\<tgroup>`_
4313 elements.
4314
4315
4316 ``colwidth``
4317 ============
4318
4319 Attribute type: CDATA_.  Default value: "1*" (`sic!`__)
4320
4321 Column width specification used in the `\<colspec>`_ element.
4322 Defined in the exchange-table-model_.
4323
4324 Either proportional measure of the form number*, e.g., “5*” for 5 times
4325 the proportion, or “*” (which is equivalent to “1*”); fixed measure,
4326 e.g., 2pt for 2 point, 3pi for 3 pica.
4327
4328 The fixed unit values are case insensitive. The standard list of allowed
4329 unit values is “pt” (points), “cm” (centimeters), “mm” (millimeters),
4330 “pi” (picas), and “in” (inches). The default fixed unit should be
4331 interpreted as “pt” if neither a proportion nor a fixed unit is
4332 specified.
4333
4334 __
4335 .. important::
4336    Currently, Docutils only allows unitless integers in the ``colwidth``
4337    attribute and interprets them as proportions.
4338
4339
4340 ``delimiter``
4341 =============
4342
4343 Attribute type: `CDATA`_.  Default value: none.
4344
4345 The ``delimiter`` attribute is used in the `\<option_argument>`_ element
4346 and contains the text preceding the <option_argument>: either the text
4347 separating it from the `\<option_string>`_ (typically either "=" or " ")
4348 or the text between option arguments (typically either "," or " ").
4349
4350 ``depth``
4351 =========
4352
4353 Attribute type: `%number`_. Default value: none.
4354
4355 The ``depth`` attribute may be used in a `\<topic>`_ element generated by
4356 the `"contents" directive`_ to hold the value of the "depth" option.
4357
4358
4359 ``dupnames``
4360 ============
4361
4362 Attribute type: `%refnames.type`_.  Default value: none.
4363
4364 ``dupnames`` is one of the `common attributes`_, shared by all
4365 Docutils elements. It replaces the `names`_ attribute when there
4366 has been a naming conflict.
4367
4368
4369 ``enumtype``
4370 ============
4371
4372 Attribute type: EnumeratedType_, one of "arabic", "loweralpha",
4373 "upperalpha", "lowerroman", or "upperroman".  Default value: none.
4374
4375 The ``enumtype`` attribute is used in the `\<enumerated_list>`_ element.
4376
4377
4378 ``format``
4379 ==========
4380
4381 Attribute type: NMTOKENS_.  Default value: none.
4382
4383 The ``format`` attribute is a string containing one or more space
4384 separated output format names.
4385
4386 The ``format`` attribute is used in the `\<raw>`_ element.
4387
4388
4389 ``height``
4390 ==========
4391
4392 Attribute type: `%measure`_.  Default value: none.
4393
4394 The ``height`` attribute is used in the `\<image>`_ element.
4395
4396
4397 ``ids``
4398 =======
4399
4400 Attribute type: `%ids.type`_.  Default value: none.
4401
4402 The ``ids`` attribute is a space separated list containing one or more
4403 unique `identifiers`_, typically assigned by the system.
4404
4405 ``ids`` is one of the `common attributes`_, shared by all Docutils
4406 elements.
4407
4408 .. TODO:
4409    * Use 'id' for primary identifier key?
4410    * Keep additional keys in `ids`
4411      or in the preceding target elements?
4412
4413
4414 ``level``
4415 =========
4416
4417 Attribute type: `%number`_.  Default value: none.
4418
4419 The ``level`` attribute is used in the `\<system_message>`_ element.
4420
4421
4422 ``line``
4423 =========
4424
4425 Attribute type: `%number`_.  Default value: none.
4426
4427 The ``line`` attribute is used in the `\<system_message>`_ element.
4428
4429
4430 ``local``
4431 =========
4432
4433 Attribute type: `%yesorno`_. Default value: none.
4434
4435 The ``local`` attribute may be used in a `\<topic>` element generated by
4436 the `"contents" directive`_ to hold the value of the "local" option.
4437
4438
4439 ``ltrim``
4440 =========
4441
4442 Attribute type: `%yesorno`_.  Default value: none (implies no).
4443
4444 The ``ltrim`` attribute is used in the `\<substitution_definition>`_ element.
4445
4446
4447 ``loading``
4448 ===========
4449
4450 Attribute type: EnumeratedType_, one of "embed", "link", or "lazy".
4451 Default value: none.
4452
4453 The ``loading`` attribute is used in the `\<image>`_ element to
4454 indicate the preferred handling by the Docutils writer_. [#]_
4455 The default depends on the writer and the image_loading_
4456 configuration setting.
4457
4458 New in Docutils 0.21
4459
4460 .. [#] Currently only recognized by the HTML5 writer.
4461    The ODF/ODT writer always embeds images in the
4462    output document, XML and LaTeX writers link to the image.
4463    The behaviour may change for the ODT and XML writers
4464    (images cannot be embedded in a LaTeX source).
4465
4466
4467 ``morecols``
4468 ============
4469
4470 Attribute type: `%number`_.  Default value: none.
4471
4472 The ``morecols`` attribute is used in the `\<entry>`_ element.
4473
4474
4475 ``morerows``
4476 ============
4477
4478 Attribute type: `%number`_.  Default value: none.
4479
4480 The ``morerows`` attribute is used in the `\<entry>`_ element.
4481
4482
4483 ``name``
4484 =========
4485
4486 Attribute type: `NMTOKEN`_ or `CDATA`_.
4487 Default value: none.
4488
4489 The ``name`` attribute in the `\<meta>`_ element accepts `NMTOKEN`_ values.
4490 The output format may limit valid values to a set of keywords
4491 (EnumeratedType_).
4492
4493 The ``name`` attribute in the `\<reference>`_ element holds the
4494 `reference name`_ of the referenced element.  Whitespace is normalized
4495 but case is preserved.  The attribute will no longer be used with
4496 <reference> elements in Docutils 1.0.
4497
4498
4499 ``names``
4500 =========
4501
4502 Attribute type: `%refnames.type`_.  Default value: none.
4503
4504 The ``names`` attribute is a space-separated list containing
4505 `reference names`_ of an element.
4506 Spaces inside a name are backslash-escaped.
4507
4508 Each name in the list must be unique; if there are name conflicts (two or
4509 more elements want to the same name), the contents will be transferred to
4510 the `dupnames`_ attribute on the duplicate elements. An element may have
4511 at most one of the ``names`` or ``dupnames`` attributes, but not both.
4512
4513 ``names`` is one of the `common attributes`_, shared by all
4514 Docutils elements.
4515
4516
4517 ``prefix``
4518 ==========
4519
4520 Attribute type: `CDATA`_.  Default value: none.
4521
4522 The ``prefix`` attribute is used in the `\<enumerated_list>`_ element.
4523
4524
4525 ``refid``
4526 =========
4527
4528 Attribute type: `%idref.type`_.  Default value: none.
4529
4530 The ``refid`` attribute contains a reference to another element via its
4531 `identifier`_.
4532
4533 ``refid`` is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
4534 `\<problematic>`_, `\<reference>`_, `\<target>`_, and `\<title>`_ elements
4535 (via the `%refid.att`_ and `%reference.atts`_ parameter entities).
4536
4537
4538 ``refname``
4539 ===========
4540
4541 Attribute type: `%refname.type`_.  Default value: none.
4542
4543 The ``refname`` attribute contains a reference to one of the `names`_ of
4544 another element.
4545
4546 ``refname`` is used by the `\<citation_reference>`_, `\<footnote_reference>`_,
4547 `\<reference>`_, `\<substitution_reference>`_, and `\<target>`_ elements. [#]_
4548
4549 On a `\<target>`_ element, ``refname`` indicates an `indirect target`_
4550 which may resolve to either an internal or external reference.
4551 Docutils transforms_ replace the ``refname`` attribute with a refid_
4552 pointing to the same element.
4553
4554 .. [#] Via the `%refname.att`_ and `%reference.atts`_ parameter entities.
4555
4556
4557 ``refuri``
4558 ==========
4559
4560 Attribute type: `CDATA`_.  Default value: none.
4561
4562 The ``refuri`` attribute contains an external reference to a URI/URL.
4563 It is used by the `\<target>`_, `\<reference>`_,
4564 `\<footnote_reference>`_, and `\<citation_reference>`_ elements
4565 (via the `%reference.atts`_ parameter entity).
4566
4567
4568 ``rowsep``
4569 ==========
4570
4571 Attribute type: `%yesorno`_.  Default value: none (implies no).
4572
4573 The ``rowsep`` attribute is used in the `\<table>`_ and `\<tgroup>`_
4574 elements.
4575
4576
4577 ``rtrim``
4578 =========
4579
4580 Attribute type: `%yesorno`_.  Default value: none (implies no).
4581
4582 The ``rtrim`` attribute is used in the `\<substitution_definition>`_ element.
4583
4584
4585 ``scale``
4586 ==========
4587
4588 Attribute type: `%number`_.  Default value: none.
4589
4590 The ``scale`` attribute is used in the `\<image>`_ element to store
4591 a uniform scaling factor (integer percentage value).
4592
4593
4594 ``source``
4595 ==========
4596
4597 Attribute type: `CDATA`_.  Default value: none.
4598
4599 The ``source`` attribute is used to store the path or URL to the
4600 source text that was used to produce the document tree.  It is one of
4601 the `common attributes`_, declared for all Docutils elements.
4602
4603
4604 ``start``
4605 =========
4606
4607 Attribute type: `%number`_.  Default value: none.
4608
4609 The ``start`` attribute is used in the `\<enumerated_list>`_ element.
4610
4611
4612 ``stub``
4613 =========
4614
4615 Attribute type: `%yesorno`_.  Default value: none.
4616
4617 The ``stub`` attribute is used in the `\<colspec>`_ element.
4618 It marks a table column containing *stubs* (row titles, on the left).
4619 See also the `"csv-table"`_ and `"list-table"`_ directives.
4620
4621
4622 ``suffix``
4623 ==========
4624
4625 Attribute type: `CDATA`_.  Default value: none.
4626
4627 The ``suffix`` attribute is used in the `\<enumerated_list>`_ element.
4628
4629
4630 .. _title attribute:
4631
4632 ``title``
4633 =========
4634
4635 Attribute type: `CDATA`_.  Default value: none.
4636
4637 The ``title`` attribute stores the *metadata title* of a `\<document>`_.
4638 It is set by the `"title" directive`_ or the `DocTitle transform`_.
4639 This title is typically not part of the rendered document.
4640 It is, for example, used as `HTML <title> element`_ and shown in a
4641 browser's title bar, in a user's history or bookmarks, or in search results.
4642
4643 .. _HTML <title> element:
4644     https://html.spec.whatwg.org/multipage/semantics.html#the-title-element
4645
4646 ``type``
4647 =========
4648
4649 Attribute type: NMTOKEN_.  Default value: none.
4650
4651 The ``type`` attribute is used in the `\<system_message>`_ element.
4652
4653
4654 ``uri``
4655 =======
4656
4657 Attribute type: `CDATA`_.  Default value: none.
4658
4659 The ``uri`` attribute is used in the `\<image>`_ and `\<figure>`_ elements
4660 to refer to the image via its Universal Resource Indicator.
4661
4662
4663 ``width``
4664 ==========
4665
4666 Attribute type: `%measure`_.  Default value: none.
4667
4668 The ``width`` attribute is used in the `\<figure>`_, `\<image>`_,
4669 and `\<table>`_ elements.
4670
4671
4672 ``xml:space``
4673 =============
4674
4675 | Attribute type: `EnumeratedType`_, one of "default" or "preserve".
4676 | Default value: "preserve" (fixed).
4677
4678 The ``xml:space`` attribute is a standard XML attribute for
4679 whitespace-preserving elements.  It is used by the `\<address>`_,
4680 `\<comment>`_, `\<doctest_block>`_, `\<literal_block>`_, `\<math_block>`_,
4681 and `\<raw>`_ elements (via the `%fixedspace.att`_ parameter entity).
4682 It is a fixed attribute, meant to communicate to an XML parser that the
4683 element contains significant whitespace.  The attribute value should not
4684 be set in a document instance.
4685
4686 ----------------------------
4687  Parameter Entity Reference
4688 ----------------------------
4689
4690 `Parameter entities`_ are used to simplify the DTD (to share definitions
4691 and reduce duplication) and to allow the DTD to be customized by
4692 wrapper DTDs (external client DTDs that use or import the Docutils
4693 DTD).  Parameter entities may be overridden by wrapper DTDs, replacing
4694 the definitions below with custom definitions.  Empty placeholder entities
4695 whose names begin with "additional" are provided to allow easy extension
4696 by wrapper DTDs.
4697
4698 .. _parameter entities: https://www.w3.org/TR/REC-xml/#dt-PE
4699
4700 .. contents:: :local:
4701
4702 In addition, the Docutils DTD defines parameter entities for
4703 `custom attribute types`_.
4704
4705 Attribute Entities
4706 ==================
4707
4708 ``%align-h.att``
4709 ----------------
4710
4711 The ``%align-h.att`` parameter entity contains the align_
4712 attribute for horizontal alignment.
4713
4714 Entity definition::
4715
4716     align (left | center | right) #IMPLIED
4717
4718 The `\<figure>`_ and `\<table>`_ elements directly employ the
4719 ``%align-h.att`` parameter entity in their attribute lists.
4720
4721
4722 ``%align-hv.att``
4723 -----------------
4724
4725 The ``%align-hv.att`` parameter entity contains the align_
4726 attribute for horizontal and vertical alignment.
4727
4728 Entity definition::
4729
4730     align (top | middle | bottom | left | center | right) #IMPLIED
4731
4732 The `\<image>`_ element directly employs the ``%align-hv.att``
4733 parameter entity in its attribute list.
4734
4735 ``%anonymous.att``
4736 ------------------
4737
4738 The ``%anonymous.att`` parameter entity contains the anonymous_
4739 attribute, used for unnamed hyperlinks.
4740
4741 Entity definition::
4742
4743     anonymous %yesorno; #IMPLIED
4744
4745 The `\<reference>`_ and `\<target>`_ elements directly employ the
4746 ``%anonymous.att`` parameter entity in their attribute lists.
4747
4748
4749 ``%auto.att``
4750 -------------
4751
4752 The ``%auto.att`` parameter entity contains the auto_ attribute, used
4753 to indicate an automatically-numbered footnote or title.
4754
4755 Entity definition::
4756
4757     auto CDATA #IMPLIED
4758
4759 The `\<footnote>`_, `\<footnote_reference>`_, and `\<title>`_ elements
4760 directly employ the ``%auto.att`` parameter entity in their attribute
4761 lists.
4762
4763
4764 ``%backrefs.att``
4765 -----------------
4766
4767 The ``%backrefs.att`` parameter entity contains the backrefs_
4768 attribute, a space-separated list of id references, for backlinks.
4769
4770 Entity definition::
4771
4772     backrefs %idrefs.type; #IMPLIED
4773
4774 The `\<citation>`_, `\<footnote>`_, and `\<system_message>`_ elements
4775 directly employ the ``%backrefs.att`` parameter entity in their
4776 attribute lists.
4777
4778
4779 ``%basic.atts``
4780 ---------------
4781
4782 The ``%basic.atts`` parameter entity lists the `common attributes`_.
4783
4784 Entity definition:
4785
4786 .. parsed-literal::
4787
4788     ids_      NMTOKENS  #IMPLIED
4789     names_    CDATA     #IMPLIED
4790     dupnames_ CDATA     #IMPLIED
4791     source_   CDATA     #IMPLIED
4792     classes_  NMTOKENS  #IMPLIED
4793     %additional.basic.atts;
4794
4795 The ``%additional.basic.atts`` parameter entity can be used by
4796 wrapper DTDs to extend ``%basic.atts``.
4797
4798
4799 ``%fixedspace.att``
4800 -------------------
4801
4802 The ``%fixedspace.att`` parameter entity contains the `xml:space`_
4803 attribute, a standard XML attribute for whitespace-preserving
4804 elements.
4805
4806 Entity definition::
4807
4808     xml:space (default | preserve) #FIXED 'preserve'
4809
4810 The ``%fixedspace.att`` parameter entity is directly employed in the
4811 attribute lists of the following elements: `\<address>`_, `\<comment>`_,
4812 `\<doctest_block>`_, `\<literal_block>`_, `\<math_block>`_, `\<raw>`_.
4813
4814
4815 ``%reference.atts``
4816 -------------------
4817
4818 The ``%reference.atts`` parameter entity groups together the refuri_,
4819 refid_, and refname_ attributes.
4820
4821 Entity definition:
4822
4823 .. parsed-literal::
4824
4825     `%refuri.att`_;
4826     `%refid.att`_;
4827     `%refname.att`_;
4828     %additional.reference.atts;
4829
4830 The ``%additional.reference.atts`` parameter entity can be used by
4831 wrapper DTDs to extend ``%additional.reference.atts``.
4832
4833 The `\<citation_reference>`_, `\<footnote_reference>`_, `\<reference>`_,
4834 and `\<target>`_ elements directly employ the ``%reference.att``
4835 parameter entity in their attribute lists.
4836
4837
4838 ``%refid.att``
4839 --------------
4840
4841 The ``%refid.att`` parameter entity contains the refid_ attribute, an
4842 internal reference to the `ids`_ attribute of another element.
4843
4844 Entity definition::
4845
4846     refid %idref.type; #IMPLIED
4847
4848 The `\<title>`_ and `\<problematic>`_ elements directly employ the
4849 ``%refid.att`` parameter entity in their attribute lists.
4850
4851 Via `%reference.atts`_, the ``%refid.att`` parameter entity is
4852 indirectly employed in the attribute lists of the `\<citation_reference>`_,
4853 `\<footnote_reference>`_, `\<reference>`_, and `\<target>`_ elements.
4854
4855
4856 ``%refname.att``
4857 ----------------
4858
4859 The ``%refname.att`` parameter entity contains the refname_
4860 attribute, an internal reference to the `names`_ attribute of another
4861 element.  On a `\<target>`_ element, ``refname`` indicates an indirect
4862 target which may resolve to either an internal or external
4863 reference.
4864
4865 Entity definition::
4866
4867     refname %refname.type; #IMPLIED
4868
4869 The `\<substitution_reference>`_ element directly employs the
4870 ``%refname.att`` parameter entity in its attribute list.
4871
4872 Via `%reference.atts`_, the ``%refname.att`` parameter entity is
4873 indirectly employed in the attribute lists of the `\<citation_reference>`_,
4874 `\<footnote_reference>`_, `\<reference>`_, and `\<target>`_ elements.
4875
4876
4877 ``%refuri.att``
4878 ---------------
4879
4880 The ``%refuri.att`` parameter entity contains the refuri_ attribute,
4881 an external reference to a URI/URL.
4882
4883 Entity definition::
4884
4885     refuri CDATA #IMPLIED
4886
4887 Via `%reference.atts`_, the ``%refuri.att`` parameter entity is
4888 indirectly employed in the attribute lists of the `\<citation_reference>`_,
4889 `\<footnote_reference>`_, `\<reference>`_, and `\<target>`_ elements.
4890
4891
4892 Element Category Entities
4893 =========================
4894
4895 ``%bibliographic.elements``
4896 ---------------------------
4897
4898 The ``%bibliographic.elements`` parameter entity contains an OR-list of all
4899 `Bibliographic Elements`_.
4900
4901 The ``%additional.bibliographic.elements`` parameter entity can be used by
4902 wrapper DTDs to extend ``%bibliographic.elements``.
4903
4904 Only the `\<docinfo>`_ element directly employs the
4905 ``%bibliographic.elements`` parameter entity in its content model.
4906
4907
4908 ``%body.elements``
4909 ------------------
4910
4911 The ``%body.elements`` parameter entity contains an OR-list of all
4912 `Body Elements`_.
4913
4914 The ``%additional.body.elements`` parameter entity can be used by
4915 wrapper DTDs to extend ``%body.elements``.
4916
4917 The ``%body.elements`` parameter entity is directly employed in the
4918 content models of the following elements: `\<admonition>`_,
4919 `\<attention>`_, `\<block_quote>`_, `\<caution>`_, `\<citation>`_,
4920 `\<compound>`_, `\<danger>`_, `\<definition>`_, `\<description>`_,
4921 `\<entry>`_, `\<error>`_, `\<field_body>`_, `\<footer>`_, `\<footnote>`_,
4922 `\<header>`_, `\<hint>`_, `\<important>`_, `\<legend>`_, `\<list_item>`_,
4923 `\<note>`_, `\<sidebar>`_, `\<system_message>`_, `\<tip>`_, `\<topic>`_,
4924 and `\<warning>`_
4925
4926 Via `%structure.model`_, the ``%body.elements`` parameter entity is
4927 indirectly employed in the content models of the `\<document>`_ and
4928 `\<section>`_ elements.
4929
4930
4931 ``%inline.elements``
4932 --------------------
4933
4934 The ``%inline.elements`` parameter entity contains an OR-list of all
4935 `Inline Elements`_.
4936
4937 The ``%additional.inline.elements`` parameter entity can be used by
4938 wrapper DTDs to extend ``%inline.elements``.
4939
4940 Via `%text.model`_, the ``%inline.elements`` parameter entity is
4941 indirectly employed in the content models of the following elements:
4942 `\<abbreviation>`_, `\<acronym>`_, `\<address>`_, `\<attribution>`_,
4943 `\<author>`_, `\<caption>`_, `\<classifier>`_, `\<contact>`_,
4944 `\<copyright>`_, `\<date>`_, `\<doctest_block>`_, `\<emphasis>`_,
4945 `\<generated>`_, `\<inline>`_, `\<line_block>`_, `\<literal_block>`_,
4946 `\<organization>`_, `\<paragraph>`_, `\<problematic>`_,
4947 `\<reference>`_, `\<revision>`_, `\<rubric>`_,
4948 `\<status>`_, `\<strong>`_, `\<subscript>`_, `\<substitution_definition>`_,
4949 `\<substitution_reference>`_, `\<subtitle>`_, `\<superscript>`_,
4950 `\<target>`_, `\<term>`_, `\<title>`_, `\<title_reference>`_, `\<version>`_
4951
4952
4953 ``%section.elements``
4954 ---------------------
4955
4956 The ``%section.elements`` parameter entity contains an OR-list of all
4957 `\<section>`_-equivalent elements.  ``%section.elements`` is itself
4958 contained within the `%structure.model`_ parameter entity.
4959
4960 Entity definition::
4961
4962     section
4963     %additional.section.elements;
4964
4965 The ``%additional.section.elements`` parameter entity can be used
4966 by wrapper DTDs to extend ``%section.elements``.
4967
4968 Via `%structure.model`_, the ``%section.elements`` parameter entity
4969 is indirectly employed in the content models of the `\<document>`_ and
4970 `\<section>`_ elements.
4971
4972
4973 Content Model Entities
4974 ======================
4975
4976 ``%structure.model``
4977 --------------------
4978
4979 The ``%structure.model`` parameter entity encapsulates the
4980 hierarchical structure of a document and of its constituent parts.
4981 See the discussion of the `element hierarchy`_ above.
4982
4983 Entity definition:
4984
4985 .. parsed-literal::
4986
4987    ( ( (`%body.elements`_; | topic | sidebar)+, transition? )*,
4988      ( (`%section.elements`_;), (transition?, (`%section.elements`_;) )* )? )
4989
4990 Each `\<document>`_ or `\<section>`_ contains zero or more body elements,
4991 topics, and/or sidebars, optionally interspersed with single
4992 transitions, followed by zero or more sections (whose contents are
4993 recursively the same as this model) optionally interspersed with
4994 transitions.
4995
4996 The following restrictions are imposed by this model:
4997
4998 * Transitions must be separated by other elements (body elements,
4999   sections, etc.).  In other words, a transition may not be
5000   immediately adjacent to another transition.
5001
5002 * A transition may not occur at the beginning of a document or
5003   section.
5004
5005 .. The following is not the case with Docutils (since at least 2004)
5006    (cf. test/functional/input/data/standard.txt)
5007
5008    An additional restriction, which cannot be expressed in the language
5009    of DTDs, is imposed by software:
5010
5011    * A transition may not occur at the end of a document or section.
5012
5013 The ``%structure.model`` parameter entity is directly employed in the
5014 content models of the `\<document>`_ and `\<section>`_ elements.
5015
5016
5017 ``%text.model``
5018 ---------------
5019
5020 The ``%text.model`` parameter entity is used by `simple elements`_ to
5021 represent text data mixed with `inline elements`_.
5022
5023 Entity definition:
5024
5025 .. parsed-literal::
5026
5027     (#PCDATA | `%inline.elements`_;)*
5028
5029 The ``%text.model`` parameter entity is directly employed in the content
5030 models of the following elements: `\<abbreviation>`_,
5031 `\<acronym>`_, `\<address>`_, `\<attribution>`_, `\<author>`_,
5032 `\<caption>`_, `\<classifier>`_, `\<contact>`_, `\<copyright>`_,
5033 `\<date>`_, `\<doctest_block>`_, `\<emphasis>`_, `\<field_name>`_,
5034 `\<generated>`_, `\<inline>`_, `\<line>`_, `\<literal>`_,  `\<literal_block>`_,
5035 `\<organization>`_, `\<paragraph>`_, `\<problematic>`_,
5036 `\<reference>`_, `\<revision>`_, `\<rubric>`_,
5037 `\<status>`_, `\<strong>`_, `\<subscript>`_, `\<substitution_definition>`_,
5038 `\<substitution_reference>`_, `\<subtitle>`_, `\<superscript>`_,
5039 `\<target>`_, `\<term>`_, `\<title>`_, `\<title_reference>`_, `\<version>`_
5040
5041
5042 ------------
5043 Bibliography
5044 ------------
5045
5046 .. _exchange-table-model:
5047 .. [tm9901]     `XML Exchange Table Model DTD`,
5048                 OASIS Technical Memorandum 9901:1999,
5049                 http://www.oasis-open.org/html/tm9901.html.
5050 .. [xml1.0]    `Extensible Markup Language (XML) 1.0`,
5051                 W3C Recommendation,
5052                 https://www.w3.org/TR/xml/.
5053 .. [DocBook5.1] `DocBook 5.1: The Definitive Guide`,
5054                 Norman Walsh,
5055                 https://tdg.docbook.org/tdg/5.1/.
5056 .. [html.spec]  `HTML Living Standard`,
5057                 WHATWG (Apple, Google, Mozilla, Microsoft),
5058                 https://html.spec.whatwg.org.
5059
5060 .. _XML: https://developer.mozilla.org/en-US/docs/Web/XML/XML_introduction
5061 .. _Introducing the Extensible Markup Language (XML):
5062     http://xml.coverpages.org/xmlIntro.html
5063 .. _XMLSpec: https://www.w3.org/XML/1998/06/xmlspec-report.htm
5064
5065 .. _DocBook: https://tdg.docbook.org/tdg/5.1/.
5066 .. _DocBook <caution>: https://tdg.docbook.org/tdg/5.1/caution.html
5067 .. _DocBook <footnote>: https://tdg.docbook.org/tdg/5.1/footnote.html
5068 .. _DocBook <footnoteref>: https://tdg.docbook.org/tdg/5.1/footnoteref.html
5069 .. _DocBook <imagedata>: https://tdg.docbook.org/tdg/5.1/imagedata
5070 .. _DocBook <important>: https://tdg.docbook.org/tdg/5.1/important.html
5071 .. _DocBook <note>: https://tdg.docbook.org/tdg/5.1/note.html
5072 .. _DocBook <tip>: https://tdg.docbook.org/tdg/5.1/tip.html
5073 .. _DocBook <warning>: https://tdg.docbook.org/tdg/5.1/warning.html
5074
5075 .. _HTML: https://html.spec.whatwg.org/multipage/.
5076
5077 .. _Python: https://www.python.org/
5078
5079
5080 .. _Docutils: https://docutils.sourceforge.io/.
5081 .. _reStructuredText: https://docutils.sourceforge.io/rst.html
5082
5083 .. _docutils.nodes: https://docutils.sourceforge.io/docutils/nodes.py
5084
5085 .. _Docutils Generic DTD:
5086 .. _Docutils DTD:
5087 .. _docutils.dtd: docutils.dtd
5088
5089 .. _auto_id_prefix: ../user/config.html#auto-id-prefix
5090 .. _datestamp:      ../user/config.html#datestamp
5091 .. _id_prefix:      ../user/config.html#id-prefix
5092 .. _image_loading:  ../user/config.html#image-loading
5093 .. _stylesheet:     ../user/config.html#stylesheet
5094
5095 .. _transform:
5096 .. _transforms:         ../api/transforms.html
5097 .. _DocInfo transform:  ../api/transforms.html#docinfo
5098 .. _DocTitle transform: ../api/transforms.html#frontmatter-doctitle
5099
5100 .. _A ReStructuredText Primer: ../user/rst/quickstart.html
5101 .. _reStructuredText Markup Specification: rst/restructuredtext.html
5102 .. _bibliographic data:
5103 .. _bibliographic fields:   rst/restructuredtext.html#bibliographic-fields
5104 .. _block quote:            rst/restructuredtext.html#block-quotes
5105 .. _bullet list:            rst/restructuredtext.html#bullet-lists
5106 .. _citations:              rst/restructuredtext.html#citations
5107 .. _definition list:        rst/restructuredtext.html#definition-lists
5108 .. _directive:              rst/restructuredtext.html#directives
5109 .. _doctest block:          rst/restructuredtext.html#doctest-blocks
5110 .. _emphasis markup:        rst/restructuredtext.html#emphasis
5111 .. _enumerated list:        rst/restructuredtext.html#enumerated-lists
5112 .. _explicit markup blocks: rst/restructuredtext.html#explicit-markup-blocks
5113 .. _footnote reference:     rst/restructuredtext.html#footnote-references
5114 .. _grid table:             rst/restructuredtext.html#grid-tables
5115 .. _indirect target:      rst/restructuredtext.html#indirect-hyperlink-targets
5116 .. _internal hyperlink targets:
5117                           rst/restructuredtext.html#internal-hyperlink-targets
5118 .. _line block:             rst/restructuredtext.html#line-blocks
5119 .. _literal block:          rst/restructuredtext.html#literal-blocks
5120 .. _footnotes:
5121 .. _footnote:               rst/restructuredtext.html#footnotes
5122 .. _hyperlinks:             rst/restructuredtext.html#hyperlinks
5123 .. _option list:            rst/restructuredtext.html#option-lists
5124 .. _RCS Keywords:           rst/restructuredtext.html#rcs-keywords
5125 .. _rST document:           rst/restructuredtext.html#document
5126 .. _rST field list:         rst/restructuredtext.html#field-lists
5127 .. _rST reference names:    rst/restructuredtext.html#reference-names
5128 .. _section:                rst/restructuredtext.html#sections
5129 .. _simple table:           rst/restructuredtext.html#simple-tables
5130 .. _strong emphasis:        rst/restructuredtext.html#strong-emphasis
5131 .. _substitution definition:
5132 .. _substitutions:          rst/restructuredtext.html#substitution-definitions
5133 .. _transition:             rst/restructuredtext.html#transitions
5134
5135 .. _standard role:              rst/roles.html
5136 .. _"abbreviation" role:        rst/roles.html#abbreviation
5137 .. _"acronym" role:             rst/roles.html#acronym
5138 .. _"raw" role:                 rst/roles.html#raw
5139 .. _"subscript" role:           rst/roles.html#subscript
5140 .. _"superscript" role:         rst/roles.html#superscript
5141 .. _"title-reference" role:     rst/roles.html#title-reference
5142
5143 .. _"admonition" directive:     rst/directives.html#admonition
5144 .. _"attention" directive:      rst/directives.html#attention
5145 .. _"caution" directive:        rst/directives.html#caution
5146 .. _"class" directive:          rst/directives.html#class
5147 .. _class option:               rst/directives.html#class-option
5148 .. _"code" directive:           rst/directives.html#code
5149 .. _"compound" directive:       rst/directives.html#compound-paragraph
5150 .. _"container" directive:      rst/directives.html#container
5151 .. _"contents" directive:
5152 .. _table of contents:          rst/directives.html#table-of-contents
5153 .. _"csv-table":                rst/directives.html#csv-table
5154 .. _"danger" directive:         rst/directives.html#danger
5155 .. _"error" directive:          rst/directives.html#error
5156 .. _"footer" directive:         rst/directives.html#footer
5157 .. _"header" directive:         rst/directives.html#header
5158 .. _"hint" directive:           rst/directives.html#hint
5159 .. _identifier normalization:   rst/directives.html#identifier-normalization
5160 .. _"image" directive:          rst/directives.html#image
5161 .. _"important" directive:      rst/directives.html#important
5162 .. _"list-table":               rst/directives.html#list-table
5163 .. _"math" directive:           rst/directives.html#math
5164 .. _"meta" directive:           rst/directives.html#meta
5165 .. _name option:                rst/directives.html#name
5166 .. _"note" directive:           rst/directives.html#note
5167 .. _"parsed-literal" directive: rst/directives.html#parsed-literal
5168 .. _"raw" directive:            rst/directives.html#raw
5169 .. _"sidebar" directive:        rst/directives.html#sidebar
5170 .. _"table" directive:          rst/directives.html#table
5171 .. _"tip" directive:            rst/directives.html#tip
5172 .. _"topic" directive:          rst/directives.html#topic
5173 .. _"title" directive:          rst/directives.html#title
5174 .. _"warning" directive:        rst/directives.html#admonition
5175 .. _custom interpreted text roles:
5176     rst/directives.html#custom-interpreted-text-roles
5177 .. _table of compatible image formats: rst/directives.html#image-formats
5178
5179
5180 \f
5181 ..
5182    Local Variables:
5183    mode: indented-text
5184    indent-tabs-mode: nil
5185    sentence-end-double-space: t
5186    fill-column: 70
5187    End: