| Server IP : 82.148.16.210 / Your IP : 216.73.216.19 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : root ( 0) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/746/root/usr/share/doc/python3-docutils/docs/ref/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>The Docutils Document Tree</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2022-06-19" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="header">
<a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a>
<hr class="header"/>
</div>
<div class="document" id="the-docutils-document-tree">
<h1 class="title">The Docutils Document Tree</h1>
<h2 class="subtitle" id="a-guide-to-the-docutils-dtd">A Guide to the Docutils DTD</h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>9080</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2022-06-19</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<!-- Minimal menu bar for inclusion in documentation sources
in ``docutils/docs/*/`` sub-diretories.
Attention: this is not a standalone document. -->
<div class="contents topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#element-hierarchy" id="toc-entry-1">Element Hierarchy</a></li>
<li><a class="reference internal" href="#element-reference" id="toc-entry-2">Element Reference</a></li>
<li><a class="reference internal" href="#attribute-types" id="toc-entry-3">Attribute types</a></li>
<li><a class="reference internal" href="#attribute-reference" id="toc-entry-4">Attribute Reference</a></li>
<li><a class="reference internal" href="#parameter-entity-reference" id="toc-entry-5">Parameter Entity Reference</a></li>
</ul>
</div>
<p>This document describes the XML data structure of <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a> documents:
the relationships and semantics of elements and attributes. The
Docutils document structure is formally defined by the <a class="reference external" href="docutils.dtd">Docutils
Generic DTD</a> XML document type definition, <a class="reference external" href="docutils.dtd">docutils.dtd</a>, which is
the definitive source for details of element structural relationships.</p>
<p>This document does not discuss implementation details. Those can be
found in internal documentation (docstrings) for the
<tt class="docutils literal">docutils.nodes</tt> module, where the document tree data structure is
implemented in a class library.</p>
<p>The reader is assumed to have some familiarity with XML or SGML, and
an understanding of the data structure meaning of "tree". For a list
of introductory articles, see <a class="reference external" href="http://xml.coverpages.org/xmlIntro.html">Introducing the Extensible Markup
Language (XML)</a>.</p>
<p>The <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> markup is used for illustrative examples
throughout this document. For a gentle introduction, see <a class="reference external" href="../user/rst/quickstart.html">A
ReStructuredText Primer</a>. For complete technical details, see the
<a class="reference external" href="rst/restructuredtext.html">reStructuredText Markup Specification</a>.</p>
<div class="section" id="element-hierarchy">
<h1><a class="toc-backref" href="#toc-entry-1">Element Hierarchy</a></h1>
<div class="contents local topic" id="topic-1">
<ul class="simple">
<li><a class="reference internal" href="#structural-elements" id="toc-entry-6">Structural Elements</a><ul>
<li><a class="reference internal" href="#structural-subelements" id="toc-entry-7">Structural Subelements</a><ul>
<li><a class="reference internal" href="#bibliographic-elements" id="toc-entry-8">Bibliographic Elements</a></li>
<li><a class="reference internal" href="#decorative-elements" id="toc-entry-9">Decorative Elements</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#body-elements" id="toc-entry-10">Body Elements</a><ul>
<li><a class="reference internal" href="#simple-body-elements" id="toc-entry-11">Simple Body Elements</a></li>
<li><a class="reference internal" href="#compound-body-elements" id="toc-entry-12">Compound Body Elements</a><ul>
<li><a class="reference internal" href="#body-subelements" id="toc-entry-13">Body Subelements</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#inline-elements" id="toc-entry-14">Inline Elements</a></li>
</ul>
</div>
<p>Below is a simplified diagram of the hierarchy of elements in the
Docutils document tree structure. An element may contain any other
elements immediately below it in the diagram. Notes are written in
square brackets. Element types in parentheses indicate recursive or
one-to-many relationships; sections may contain (sub)sections, tables
contain further body elements, etc.</p>
<pre class="literal-block">
+--------------------------------------------------------------------+
| document [may begin with a title, subtitle, decoration, docinfo] |
| +--------------------------------------+
| | sections [each begins with a title] |
+-----------------------------+-------------------------+------------+
| [body elements:] | (sections) |
| | - literal | - lists | | - hyperlink +------------+
| | blocks | - tables | | targets |
| para- | - doctest | - block | foot- | - sub. defs |
| graphs | blocks | quotes | notes | - comments |
+---------+-----------+----------+-------+--------------+
| [text]+ | [text] | (body elements) | [text] |
| (inline +-----------+------------------+--------------+
| markup) |
+---------+
</pre>
<p>The Docutils document model uses a simple, recursive model for section
structure. A <a class="reference internal" href="#document">document</a> node may contain body elements and <a class="reference internal" href="#section">section</a>
elements. Sections in turn may contain body elements and sections.
The level (depth) of a section element is determined from its physical
nesting level; unlike other document models (<tt class="docutils literal"><h1></tt> in <a class="reference external" href="https://www.w3.org/TR/html52/">HTML</a>,
<tt class="docutils literal"><sect1></tt> in <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/">DocBook</a>, <tt class="docutils literal"><div1></tt> in <a class="reference external" href="https://www.w3.org/XML/1998/06/xmlspec-report.htm">XMLSpec</a>) the level is not
incorporated into the element name.</p>
<p>The Docutils document model uses strict element content models. Every
element has a unique structure and semantics, but elements may be
classified into general categories (below). Only elements which are
meant to directly contain text data have a mixed content model, where
text data and inline elements may be intermixed. This is unlike the
much looser <a class="reference external" href="https://www.w3.org/TR/html52/">HTML</a> document model, where paragraphs and text data may
occur at the same level.</p>
<div class="section" id="structural-elements">
<h2><a class="toc-backref" href="#toc-entry-6">Structural Elements</a></h2>
<p>Structural elements may only contain child elements; they do not
directly contain text data. Structural elements may contain body
elements or further structural elements. Structural elements can only
be child elements of other structural elements.</p>
<p>Category members: <a class="reference internal" href="#document">document</a>, <a class="reference internal" href="#section">section</a>, <a class="reference internal" href="#topic">topic</a>, <a class="reference internal" href="#sidebar">sidebar</a></p>
<div class="section" id="structural-subelements">
<h3><a class="toc-backref" href="#toc-entry-7">Structural Subelements</a></h3>
<p>Structural subelements are child elements of structural elements.
Simple structuctural subelements (<a class="reference internal" href="#title">title</a>, <a class="reference internal" href="#subtitle">subtitle</a>) contain text
data; the others are compound and do not directly contain text data.</p>
<p>Category members: <a class="reference internal" href="#title">title</a>, <a class="reference internal" href="#subtitle">subtitle</a>, <a class="reference internal" href="#decoration">decoration</a>, <a class="reference internal" href="#docinfo">docinfo</a>, <a class="reference internal" href="#meta">meta</a>,
<a class="reference internal" href="#transition">transition</a></p>
<div class="section" id="bibliographic-elements">
<h4><a class="toc-backref" href="#toc-entry-8">Bibliographic Elements</a></h4>
<p>The <a class="reference internal" href="#docinfo">docinfo</a> element is an optional child of <a class="reference internal" href="#document">document</a>. It groups
bibliographic elements together. All bibliographic elements except
<a class="reference internal" href="#authors">authors</a> and <a class="reference internal" href="#field">field</a> contain text data. <a class="reference internal" href="#authors">authors</a> contains further
bibliographic elements (most notably <a class="reference internal" href="#author">author</a>). <a class="reference internal" href="#field">field</a> contains
<a class="reference internal" href="#field-name">field_name</a> and <a class="reference internal" href="#field-body">field_body</a> body subelements.</p>
<p>Category members: <a class="reference internal" href="#address">address</a>, <a class="reference internal" href="#author">author</a>, <a class="reference internal" href="#authors">authors</a>, <a class="reference internal" href="#contact">contact</a>, <a class="reference internal" href="#copyright">copyright</a>,
<a class="reference internal" href="#date">date</a>, <a class="reference internal" href="#field">field</a>, <a class="reference internal" href="#organization">organization</a>, <a class="reference internal" href="#revision">revision</a>, <a class="reference internal" href="#status">status</a>, <a class="reference internal" href="#version">version</a></p>
</div>
<div class="section" id="decorative-elements">
<h4><a class="toc-backref" href="#toc-entry-9">Decorative Elements</a></h4>
<p>The <a class="reference internal" href="#decoration">decoration</a> element is also an optional child of <a class="reference internal" href="#document">document</a>. It
groups together elements used to generate page headers and footers.</p>
<p>Category members: <a class="reference internal" href="#footer">footer</a>, <a class="reference internal" href="#header">header</a></p>
</div>
</div>
</div>
<div class="section" id="body-elements">
<h2><a class="toc-backref" href="#toc-entry-10">Body Elements</a></h2>
<p>Body elements are contained within structural elements and compound
body elements. There are two subcategories of body elements: simple
and compound.</p>
<p>Category members: <a class="reference internal" href="#admonition">admonition</a>, <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#block-quote">block_quote</a>, <a class="reference internal" href="#bullet-list">bullet_list</a>,
<a class="reference internal" href="#caution">caution</a>, <a class="reference internal" href="#citation">citation</a>, <a class="reference internal" href="#comment">comment</a>, <a class="reference internal" href="#compound">compound</a>, <a class="reference internal" href="#container">container</a>, <a class="reference internal" href="#danger">danger</a>,
<a class="reference internal" href="#definition-list">definition_list</a>, <a class="reference internal" href="#doctest-block">doctest_block</a>, <a class="reference internal" href="#enumerated-list">enumerated_list</a>, <a class="reference internal" href="#error">error</a>,
<a class="reference internal" href="#field-list">field_list</a>, <a class="reference internal" href="#figure">figure</a>, <a class="reference internal" href="#footnote">footnote</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#image">image</a>, <a class="reference internal" href="#important">important</a>,
<a class="reference internal" href="#line-block">line_block</a>, <a class="reference internal" href="#literal-block">literal_block</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#option-list">option_list</a>, <a class="reference internal" href="#paragraph">paragraph</a>,
<a class="reference internal" href="#pending">pending</a>, <a class="reference internal" href="#raw">raw</a>, <a class="reference internal" href="#rubric">rubric</a>, <a class="reference internal" href="#substitution-definition">substitution_definition</a>, <a class="reference internal" href="#system-message">system_message</a>,
<a class="reference internal" href="#table">table</a>, <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a></p>
<div class="section" id="simple-body-elements">
<h3><a class="toc-backref" href="#toc-entry-11">Simple Body Elements</a></h3>
<p>Simple body elements are empty or directly contain text data. Those
that contain text data may also contain inline elements. Such
elements therefore have a "mixed content model".</p>
<p>Category members: <a class="reference internal" href="#comment">comment</a>, <a class="reference internal" href="#doctest-block">doctest_block</a>, <a class="reference internal" href="#image">image</a>, <a class="reference internal" href="#literal-block">literal_block</a>,
<a class="reference internal" href="#math-block">math_block</a>, <a class="reference internal" href="#paragraph">paragraph</a>, <a class="reference internal" href="#pending">pending</a>, <a class="reference internal" href="#raw">raw</a>, <a class="reference internal" href="#rubric">rubric</a>, <a class="reference internal" href="#substitution-definition">substitution_definition</a>,
<a class="reference internal" href="#target">target</a></p>
</div>
<div class="section" id="compound-body-elements">
<h3><a class="toc-backref" href="#toc-entry-12">Compound Body Elements</a></h3>
<p>Compound body elements contain local substructure (body subelements)
and further body elements. They do not directly contain text data.</p>
<p>Category members: <a class="reference internal" href="#admonition">admonition</a>, <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#block-quote">block_quote</a>, <a class="reference internal" href="#bullet-list">bullet_list</a>,
<a class="reference internal" href="#caution">caution</a>, <a class="reference internal" href="#citation">citation</a>, <a class="reference internal" href="#compound">compound</a>, <a class="reference internal" href="#container">container</a>, <a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#definition-list">definition_list</a>,
<a class="reference internal" href="#enumerated-list">enumerated_list</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#field-list">field_list</a>, <a class="reference internal" href="#figure">figure</a>, <a class="reference internal" href="#footnote">footnote</a>, <a class="reference internal" href="#hint">hint</a>,
<a class="reference internal" href="#important">important</a>, line_block, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#option-list">option_list</a>, <a class="reference internal" href="#system-message">system_message</a>, <a class="reference internal" href="#table">table</a>,
<a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a></p>
<div class="section" id="body-subelements">
<h4><a class="toc-backref" href="#toc-entry-13">Body Subelements</a></h4>
<p>Compound body elements contain specific subelements (e.g. <a class="reference internal" href="#bullet-list">bullet_list</a>
contains <a class="reference internal" href="#list-item">list_item</a>). Subelements may themselves be compound elements
(containing further child elements, like <a class="reference internal" href="#field">field</a>) or simple data
elements (containing text data, like <a class="reference internal" href="#field-name">field_name</a>). These subelements
always occur within specific parent elements, never at the body
element level (beside paragraphs, etc.).</p>
<p>Category members (simple): <a class="reference internal" href="#attribution">attribution</a>, <a class="reference internal" href="#caption">caption</a>, <a class="reference internal" href="#classifier">classifier</a>,
<a class="reference internal" href="#colspec">colspec</a>, <a class="reference internal" href="#field-name">field_name</a>, <a class="reference internal" href="#label">label</a>, <a class="reference internal" href="#line">line</a>, <a class="reference internal" href="#option-argument">option_argument</a>,
<a class="reference internal" href="#option-string">option_string</a>, <a class="reference internal" href="#term">term</a></p>
<p>Category members (compound): <a class="reference internal" href="#definition">definition</a>, <a class="reference internal" href="#definition-list-item">definition_list_item</a>,
<a class="reference internal" href="#description">description</a>, <a class="reference internal" href="#entry">entry</a>, <a class="reference internal" href="#field">field</a>, <a class="reference internal" href="#field-body">field_body</a>, <a class="reference internal" href="#legend">legend</a>, <a class="reference internal" href="#list-item">list_item</a>,
<a class="reference internal" href="#option">option</a>, <a class="reference internal" href="#option-group">option_group</a>, <a class="reference internal" href="#option-list-item">option_list_item</a>, <a class="reference internal" href="#row">row</a>, <a class="reference internal" href="#tbody">tbody</a>, <a class="reference internal" href="#tgroup">tgroup</a>,
<a class="reference internal" href="#thead">thead</a></p>
</div>
</div>
</div>
<div class="section" id="inline-elements">
<h2><a class="toc-backref" href="#toc-entry-14">Inline Elements</a></h2>
<p>Inline elements directly contain text data, and may also contain
further inline elements. Inline elements are contained within simple
body elements. Most inline elements have a "mixed content model".</p>
<p>Category members: <a class="reference internal" href="#abbreviation">abbreviation</a>, <a class="reference internal" href="#acronym">acronym</a>, <a class="reference internal" href="#citation-reference">citation_reference</a>,
<a class="reference internal" href="#emphasis">emphasis</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a>, <a class="reference internal" href="#generated">generated</a>, <a class="reference internal" href="#image">image</a>, <a class="reference internal" href="#inline">inline</a>, <a class="reference internal" href="#literal">literal</a>,
<a class="reference internal" href="#math">math</a>, <a class="reference internal" href="#problematic">problematic</a>, <a class="reference internal" href="#reference">reference</a>, <a class="reference internal" href="#strong">strong</a>, <a class="reference internal" href="#subscript">subscript</a>,
<a class="reference internal" href="#substitution-reference">substitution_reference</a>, <a class="reference internal" href="#superscript">superscript</a>, <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#title-reference">title_reference</a>, <a class="reference internal" href="#raw">raw</a></p>
</div>
</div>
<div class="section" id="element-reference">
<h1><a class="toc-backref" href="#toc-entry-2">Element Reference</a></h1>
<div class="contents local topic" id="topic-2">
<ul class="simple">
<li><a class="reference internal" href="#abbreviation" id="toc-entry-15"><tt class="docutils literal">abbreviation</tt></a></li>
<li><a class="reference internal" href="#acronym" id="toc-entry-16"><tt class="docutils literal">acronym</tt></a></li>
<li><a class="reference internal" href="#address" id="toc-entry-17"><tt class="docutils literal">address</tt></a></li>
<li><a class="reference internal" href="#admonition" id="toc-entry-18"><tt class="docutils literal">admonition</tt></a></li>
<li><a class="reference internal" href="#attention" id="toc-entry-19"><tt class="docutils literal">attention</tt></a></li>
<li><a class="reference internal" href="#attribution" id="toc-entry-20"><tt class="docutils literal">attribution</tt></a></li>
<li><a class="reference internal" href="#author" id="toc-entry-21"><tt class="docutils literal">author</tt></a></li>
<li><a class="reference internal" href="#authors" id="toc-entry-22"><tt class="docutils literal">authors</tt></a></li>
<li><a class="reference internal" href="#block-quote" id="toc-entry-23"><tt class="docutils literal">block_quote</tt></a></li>
<li><a class="reference internal" href="#bullet-list" id="toc-entry-24"><tt class="docutils literal">bullet_list</tt></a></li>
<li><a class="reference internal" href="#caption" id="toc-entry-25"><tt class="docutils literal">caption</tt></a></li>
<li><a class="reference internal" href="#caution" id="toc-entry-26"><tt class="docutils literal">caution</tt></a></li>
<li><a class="reference internal" href="#citation" id="toc-entry-27"><tt class="docutils literal">citation</tt></a></li>
<li><a class="reference internal" href="#citation-reference" id="toc-entry-28"><tt class="docutils literal">citation_reference</tt></a></li>
<li><a class="reference internal" href="#classifier" id="toc-entry-29"><tt class="docutils literal">classifier</tt></a></li>
<li><a class="reference internal" href="#colspec" id="toc-entry-30"><tt class="docutils literal">colspec</tt></a></li>
<li><a class="reference internal" href="#comment" id="toc-entry-31"><tt class="docutils literal">comment</tt></a></li>
<li><a class="reference internal" href="#compound" id="toc-entry-32"><tt class="docutils literal">compound</tt></a></li>
<li><a class="reference internal" href="#contact" id="toc-entry-33"><tt class="docutils literal">contact</tt></a></li>
<li><a class="reference internal" href="#container" id="toc-entry-34"><tt class="docutils literal">container</tt></a></li>
<li><a class="reference internal" href="#copyright" id="toc-entry-35"><tt class="docutils literal">copyright</tt></a></li>
<li><a class="reference internal" href="#danger" id="toc-entry-36"><tt class="docutils literal">danger</tt></a></li>
<li><a class="reference internal" href="#date" id="toc-entry-37"><tt class="docutils literal">date</tt></a></li>
<li><a class="reference internal" href="#decoration" id="toc-entry-38"><tt class="docutils literal">decoration</tt></a></li>
<li><a class="reference internal" href="#definition" id="toc-entry-39"><tt class="docutils literal">definition</tt></a></li>
<li><a class="reference internal" href="#definition-list" id="toc-entry-40"><tt class="docutils literal">definition_list</tt></a></li>
<li><a class="reference internal" href="#definition-list-item" id="toc-entry-41"><tt class="docutils literal">definition_list_item</tt></a></li>
<li><a class="reference internal" href="#description" id="toc-entry-42"><tt class="docutils literal">description</tt></a></li>
<li><a class="reference internal" href="#docinfo" id="toc-entry-43"><tt class="docutils literal">docinfo</tt></a></li>
<li><a class="reference internal" href="#doctest-block" id="toc-entry-44"><tt class="docutils literal">doctest_block</tt></a></li>
<li><a class="reference internal" href="#document" id="toc-entry-45"><tt class="docutils literal">document</tt></a></li>
<li><a class="reference internal" href="#emphasis" id="toc-entry-46"><tt class="docutils literal">emphasis</tt></a></li>
<li><a class="reference internal" href="#entry" id="toc-entry-47"><tt class="docutils literal">entry</tt></a></li>
<li><a class="reference internal" href="#enumerated-list" id="toc-entry-48"><tt class="docutils literal">enumerated_list</tt></a></li>
<li><a class="reference internal" href="#error" id="toc-entry-49"><tt class="docutils literal">error</tt></a></li>
<li><a class="reference internal" href="#field" id="toc-entry-50"><tt class="docutils literal">field</tt></a></li>
<li><a class="reference internal" href="#field-body" id="toc-entry-51"><tt class="docutils literal">field_body</tt></a></li>
<li><a class="reference internal" href="#field-list" id="toc-entry-52"><tt class="docutils literal">field_list</tt></a></li>
<li><a class="reference internal" href="#field-name" id="toc-entry-53"><tt class="docutils literal">field_name</tt></a></li>
<li><a class="reference internal" href="#figure" id="toc-entry-54"><tt class="docutils literal">figure</tt></a></li>
<li><a class="reference internal" href="#footer" id="toc-entry-55"><tt class="docutils literal">footer</tt></a></li>
<li><a class="reference internal" href="#footnote" id="toc-entry-56"><tt class="docutils literal">footnote</tt></a></li>
<li><a class="reference internal" href="#footnote-reference" id="toc-entry-57"><tt class="docutils literal">footnote_reference</tt></a></li>
<li><a class="reference internal" href="#generated" id="toc-entry-58"><tt class="docutils literal">generated</tt></a></li>
<li><a class="reference internal" href="#header" id="toc-entry-59"><tt class="docutils literal">header</tt></a></li>
<li><a class="reference internal" href="#hint" id="toc-entry-60"><tt class="docutils literal">hint</tt></a></li>
<li><a class="reference internal" href="#image" id="toc-entry-61"><tt class="docutils literal">image</tt></a></li>
<li><a class="reference internal" href="#important" id="toc-entry-62"><tt class="docutils literal">important</tt></a></li>
<li><a class="reference internal" href="#inline" id="toc-entry-63"><tt class="docutils literal">inline</tt></a></li>
<li><a class="reference internal" href="#label" id="toc-entry-64"><tt class="docutils literal">label</tt></a></li>
<li><a class="reference internal" href="#legend" id="toc-entry-65"><tt class="docutils literal">legend</tt></a></li>
<li><a class="reference internal" href="#line" id="toc-entry-66"><tt class="docutils literal">line</tt></a></li>
<li><a class="reference internal" href="#line-block" id="toc-entry-67"><tt class="docutils literal">line_block</tt></a></li>
<li><a class="reference internal" href="#list-item" id="toc-entry-68"><tt class="docutils literal">list_item</tt></a></li>
<li><a class="reference internal" href="#literal" id="toc-entry-69"><tt class="docutils literal">literal</tt></a></li>
<li><a class="reference internal" href="#literal-block" id="toc-entry-70"><tt class="docutils literal">literal_block</tt></a></li>
<li><a class="reference internal" href="#math" id="toc-entry-71"><tt class="docutils literal">math</tt></a></li>
<li><a class="reference internal" href="#math-block" id="toc-entry-72"><tt class="docutils literal">math_block</tt></a></li>
<li><a class="reference internal" href="#meta" id="toc-entry-73"><tt class="docutils literal">meta</tt></a></li>
<li><a class="reference internal" href="#note" id="toc-entry-74"><tt class="docutils literal">note</tt></a></li>
<li><a class="reference internal" href="#option" id="toc-entry-75"><tt class="docutils literal">option</tt></a></li>
<li><a class="reference internal" href="#option-argument" id="toc-entry-76"><tt class="docutils literal">option_argument</tt></a></li>
<li><a class="reference internal" href="#option-group" id="toc-entry-77"><tt class="docutils literal">option_group</tt></a></li>
<li><a class="reference internal" href="#option-list" id="toc-entry-78"><tt class="docutils literal">option_list</tt></a></li>
<li><a class="reference internal" href="#option-list-item" id="toc-entry-79"><tt class="docutils literal">option_list_item</tt></a></li>
<li><a class="reference internal" href="#option-string" id="toc-entry-80"><tt class="docutils literal">option_string</tt></a></li>
<li><a class="reference internal" href="#organization" id="toc-entry-81"><tt class="docutils literal">organization</tt></a></li>
<li><a class="reference internal" href="#paragraph" id="toc-entry-82"><tt class="docutils literal">paragraph</tt></a></li>
<li><a class="reference internal" href="#pending" id="toc-entry-83"><tt class="docutils literal">pending</tt></a></li>
<li><a class="reference internal" href="#problematic" id="toc-entry-84"><tt class="docutils literal">problematic</tt></a></li>
<li><a class="reference internal" href="#raw" id="toc-entry-85"><tt class="docutils literal">raw</tt></a></li>
<li><a class="reference internal" href="#reference" id="toc-entry-86"><tt class="docutils literal">reference</tt></a></li>
<li><a class="reference internal" href="#revision" id="toc-entry-87"><tt class="docutils literal">revision</tt></a></li>
<li><a class="reference internal" href="#row" id="toc-entry-88"><tt class="docutils literal">row</tt></a></li>
<li><a class="reference internal" href="#rubric" id="toc-entry-89"><tt class="docutils literal">rubric</tt></a></li>
<li><a class="reference internal" href="#section" id="toc-entry-90"><tt class="docutils literal">section</tt></a></li>
<li><a class="reference internal" href="#sidebar" id="toc-entry-91"><tt class="docutils literal">sidebar</tt></a></li>
<li><a class="reference internal" href="#status" id="toc-entry-92"><tt class="docutils literal">status</tt></a></li>
<li><a class="reference internal" href="#strong" id="toc-entry-93"><tt class="docutils literal">strong</tt></a></li>
<li><a class="reference internal" href="#subscript" id="toc-entry-94"><tt class="docutils literal">subscript</tt></a></li>
<li><a class="reference internal" href="#substitution-definition" id="toc-entry-95"><tt class="docutils literal">substitution_definition</tt></a></li>
<li><a class="reference internal" href="#substitution-reference" id="toc-entry-96"><tt class="docutils literal">substitution_reference</tt></a></li>
<li><a class="reference internal" href="#subtitle" id="toc-entry-97"><tt class="docutils literal">subtitle</tt></a></li>
<li><a class="reference internal" href="#superscript" id="toc-entry-98"><tt class="docutils literal">superscript</tt></a></li>
<li><a class="reference internal" href="#system-message" id="toc-entry-99"><tt class="docutils literal">system_message</tt></a></li>
<li><a class="reference internal" href="#table" id="toc-entry-100"><tt class="docutils literal">table</tt></a></li>
<li><a class="reference internal" href="#target" id="toc-entry-101"><tt class="docutils literal">target</tt></a></li>
<li><a class="reference internal" href="#tbody" id="toc-entry-102"><tt class="docutils literal">tbody</tt></a></li>
<li><a class="reference internal" href="#term" id="toc-entry-103"><tt class="docutils literal">term</tt></a></li>
<li><a class="reference internal" href="#tgroup" id="toc-entry-104"><tt class="docutils literal">tgroup</tt></a></li>
<li><a class="reference internal" href="#thead" id="toc-entry-105"><tt class="docutils literal">thead</tt></a></li>
<li><a class="reference internal" href="#tip" id="toc-entry-106"><tt class="docutils literal">tip</tt></a></li>
<li><a class="reference internal" href="#title-1" id="toc-entry-107"><tt class="docutils literal">title</tt></a></li>
<li><a class="reference internal" href="#title-reference" id="toc-entry-108"><tt class="docutils literal">title_reference</tt></a></li>
<li><a class="reference internal" href="#topic" id="toc-entry-109"><tt class="docutils literal">topic</tt></a></li>
<li><a class="reference internal" href="#transition" id="toc-entry-110"><tt class="docutils literal">transition</tt></a></li>
<li><a class="reference internal" href="#version" id="toc-entry-111"><tt class="docutils literal">version</tt></a></li>
<li><a class="reference internal" href="#warning" id="toc-entry-112"><tt class="docutils literal">warning</tt></a></li>
</ul>
</div>
<p>Each element in the DTD (document type definition) is described in its
own section below. Each section contains an introduction plus the
following subsections:</p>
<ul>
<li><p class="first">Details (of element relationships and semantics):</p>
<ul class="simple">
<li>Category: One or more references to the element categories in
<a class="reference internal" href="#element-hierarchy">Element Hierarchy</a> above. Some elements belong to more than one
category.</li>
<li>Analogues: Describes analogous elements in well-known document
models such as <a class="reference external" href="https://www.w3.org/TR/html52/">HTML</a> or <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/">DocBook</a>. Lists similarities and
differences.</li>
<li>Processing: Lists formatting or rendering recommendations for the
element.</li>
<li>Parents: A list of elements which may contain the element.</li>
<li>Children: A list of elements which may occur within the element
followed by the formal XML content model from the <a class="reference external" href="docutils.dtd">Docutils DTD</a>.</li>
<li>Attributes: Describes (or refers to descriptions of) the possible
values and semantics of each attribute.</li>
<li>Parameter Entities: Lists the parameter entities which directly or
indirectly include the element.</li>
</ul>
</li>
<li><p class="first">Examples: <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> examples are shown along with
fragments of the document trees resulting from parsing.
<span class="target" id="pseudo-xml">Pseudo-XML</span> is used for the results of parsing and processing.
Pseudo-XML is a representation of XML where nesting is indicated by
indentation and end-tags are not shown. Some of the precision of
real XML is given up in exchange for easier readability. For
example, the following are equivalent:</p>
<ul>
<li><p class="first">Real XML:</p>
<pre class="literal-block">
<document>
<section ids="a-title" names="a title">
<title>A Title</title>
<paragraph>A paragraph.</paragraph>
</section>
</document>
</pre>
</li>
<li><p class="first">Pseudo-XML:</p>
<pre class="literal-block">
<document>
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
</pre>
</li>
</ul>
</li>
</ul>
<hr class="docutils" />
<p>Many of the element reference sections below are marked "<span class="target" id="to-be-completed">to be
completed</span>". Please help complete this document by contributing to
its writing.</p>
<div class="section" id="abbreviation">
<h2><a class="toc-backref" href="#toc-entry-15"><tt class="docutils literal">abbreviation</tt></a></h2>
<p>The <tt class="docutils literal">abbreviation</tt> element is an inline element used to represent an
abbreviation being used in the document. An example of an abbreviation is 'St'
being used instead of 'Street'.</p>
<div class="section" id="details">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#inline-elements">Inline Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">abbreviation</tt> is analogous to the HTML "abbr" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#inline-elements-1">%inline.elements;</a> parameter entity in their
content models may contain <tt class="docutils literal">abbreviation</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">abbreviation</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">abbreviation</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples">
<h3>Examples</h3>
<p>The <tt class="docutils literal">abbreviation</tt> element is not exposed in default restructured text. It
can only be accessed through custom roles.</p>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> example from a custom <cite>:abbr:</cite> role:</p>
<pre class="literal-block">
<paragraph>
<abbreviation explanation="Street">
St
is a common abbreviation for "street".
</pre>
</div>
</div>
<div class="section" id="acronym">
<h2><a class="toc-backref" href="#toc-entry-16"><tt class="docutils literal">acronym</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="address">
<h2><a class="toc-backref" href="#toc-entry-17"><tt class="docutils literal">address</tt></a></h2>
<p>The <tt class="docutils literal">address</tt> element holds the surface mailing address information
for the author (individual or group) of the document, or a third-party
contact address. Its structure is identical to that of the
<a class="reference internal" href="#literal-block">literal_block</a> element: whitespace is significant, especially
newlines.</p>
<div class="section" id="details-1">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">address</tt> is analogous to the DocBook "address" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">As with the <a class="reference internal" href="#literal-block">literal_block</a> element, newlines and other whitespace
is significant and must be preserved. However, a monospaced
typeface need not be used.</p>
<p>See also <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">address</tt>: <a class="reference internal" href="#docinfo">docinfo</a>, <a class="reference internal" href="#authors">authors</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">address</tt> elements contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<blockquote>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">address</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a> plus
<a class="reference internal" href="#xml-space">xml:space</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">address</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-1">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Address: 123 Example Ave.
Example, EX
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<address>
123 Example Ave.
Example, EX
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="admonition">
<h2><a class="toc-backref" href="#toc-entry-18"><tt class="docutils literal">admonition</tt></a></h2>
<p>This element is a generic, titled admonition. Also see the specific
admonition elements Docutils offers (in alphabetical order): <a class="reference internal" href="#caution">caution</a>,
<a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>.</p>
<div class="section" id="details-2">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">admonition</tt> has no direct analogues in common DTDs. It can be
emulated with primitives and type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">admonition</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">admonition</tt> elements begin with a <a class="reference internal" href="#title">title</a> and may contain one or
more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(title_, (`%body.elements;`_)+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">admonition</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">admonition</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">admonition</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-2">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. admonition:: And, by the way...
You can make up your own admonition too.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<admonition class="admonition-and-by-the-way">
<title>
And, by the way...
<paragraph>
You can make up your own admonition too.
</pre>
</div>
</div>
<div class="section" id="attention">
<h2><a class="toc-backref" href="#toc-entry-19"><tt class="docutils literal">attention</tt></a></h2>
<p>The <tt class="docutils literal">attention</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#caution">caution</a>, <a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>,
<a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic <a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-3">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">attention</tt> has no direct analogues in common DTDs. It can be
emulated with primitives and type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Attention!" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">attention</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">attention</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<blockquote>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">attention</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">attention</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">attention</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-3">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Attention:: All your base are belong to us.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<attention>
<paragraph>
All your base are belong to us.
</pre>
</div>
</div>
<div class="section" id="attribution">
<h2><a class="toc-backref" href="#toc-entry-20"><tt class="docutils literal">attribution</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="author">
<h2><a class="toc-backref" href="#toc-entry-21"><tt class="docutils literal">author</tt></a></h2>
<p>The <tt class="docutils literal">author</tt> element holds the name of the author of the document.</p>
<div class="section" id="details-4">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">author</tt> is analogous to the DocBook "author" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">author</tt>: <a class="reference internal" href="#docinfo">docinfo</a>, <a class="reference internal" href="#authors">authors</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">author</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<blockquote>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">author</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">author</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-4">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Author: J. Random Hacker
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<author>
J. Random Hacker
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="authors">
<h2><a class="toc-backref" href="#toc-entry-22"><tt class="docutils literal">authors</tt></a></h2>
<p>The <tt class="docutils literal">authors</tt> element is a container for author information for
documents with multiple authors.</p>
<div class="section" id="details-5">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">authors</tt> is analogous to the DocBook "authors" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">authors</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">authors</tt> elements may contain the following elements: <a class="reference internal" href="#author">author</a>,
<a class="reference internal" href="#organization">organization</a>, <a class="reference internal" href="#address">address</a>, <a class="reference internal" href="#contact">contact</a>:</p>
<pre class="literal-block">
((author, organization?, address?, contact?)+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">authors</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">authors</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-5">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Authors: J. Random Hacker; Jane Doe
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<authors>
<author>
J. Random Hacker
<author>
Jane Doe
</pre>
<p>In reStructuredText, multiple author's names are separated with
semicolons (";") or commas (","); semicolons take precedence. There
is currently no way to represent the author's organization, address,
or contact in a reStructuredText "Authors" field.</p>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="block-quote">
<h2><a class="toc-backref" href="#toc-entry-23"><tt class="docutils literal">block_quote</tt></a></h2>
<p>The <tt class="docutils literal">block_quote</tt> element is used for quotations set off from the
main text (standalone).</p>
<div class="section" id="details-6">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">block_quote</tt> is analogous to the "blockquote" element in both
HTML and DocBook.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first"><tt class="docutils literal">block_quote</tt> elements serve to set their contents off from the
main text, typically with indentation and/or other decoration.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">block_quote</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">block_quote</tt> elements contain <a class="reference internal" href="#body-elements">body elements</a> followed by an
optional <a class="reference internal" href="#attribution">attribution</a> element.</p>
<blockquote>
<pre class="literal-block">
((<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+, attribution?)
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">block_quote</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">block_quote</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">block_quote</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-6">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
As a great paleontologist once said,
This theory, that is mine, is mine.
-- Anne Elk (Miss)
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
As a great paleontologist once said,
<block_quote>
<paragraph>
This theory, that is mine, is mine.
<attribution>
Anne Elk (Miss)
</pre>
</div>
</div>
<div class="section" id="bullet-list">
<h2><a class="toc-backref" href="#toc-entry-24"><tt class="docutils literal">bullet_list</tt></a></h2>
<p>The <tt class="docutils literal">bullet_list</tt> element contains <a class="reference internal" href="#list-item">list_item</a> elements which are
uniformly marked with bullets. Bullets are typically simple dingbats
(symbols) such as circles and squares.</p>
<div class="section" id="details-7">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">bullet_list</tt> is analogous to the HTML "ul" element and to the
DocBook "itemizedlist" element. HTML's "ul" is short for
"unordered list", which we consider to be a misnomer. "Unordered"
implies that the list items may be randomly rearranged without
affecting the meaning of the list. Bullet lists <em>are</em> often
ordered; the ordering is simply left implicit.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Each list item should begin a new vertical block, prefaced by a
bullet/dingbat.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">bullet_list</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">bullet_list</tt> elements contain one or more <a class="reference internal" href="#list-item">list_item</a> elements:</p>
<pre class="literal-block">
(list_item_+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">bullet_list</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#bullet">bullet</a>.</p>
<p><tt class="docutils literal">bullet</tt> is used to record the style of bullet from the input
data. In documents processed from <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>, it contains
one of "-", "+", or "*". It may be ignored in processing.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">bullet_list</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">bullet_list</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-7">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
- Item 1, paragraph 1.
Item 1, paragraph 2.
- Item 2.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<bullet_list bullet="-">
<list_item>
<paragraph>
Item 1, paragraph 1.
<paragraph>
Item 1, paragraph 2.
<list_item>
<paragraph>
Item 2.
</pre>
<p>See <a class="reference internal" href="#list-item">list_item</a> for another example.</p>
</div>
</div>
<div class="section" id="caption">
<h2><a class="toc-backref" href="#toc-entry-25"><tt class="docutils literal">caption</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="caution">
<h2><a class="toc-backref" href="#toc-entry-26"><tt class="docutils literal">caution</tt></a></h2>
<p>The <tt class="docutils literal">caution</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>,
<a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic <a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-8">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><tt class="docutils literal">caution</tt> is analogous to the <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/caution.html">DocBook "caution"</a> element.</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Caution" (or similar).</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">caution</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">caution</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<blockquote>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">caution</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">caution</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">caution</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-8">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Caution:: Don't take any wooden nickels.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<caution>
<paragraph>
Don't take any wooden nickels.
</pre>
</div>
</div>
<div class="section" id="citation">
<h2><a class="toc-backref" href="#toc-entry-27"><tt class="docutils literal">citation</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="citation-reference">
<h2><a class="toc-backref" href="#toc-entry-28"><tt class="docutils literal">citation_reference</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="classifier">
<h2><a class="toc-backref" href="#toc-entry-29"><tt class="docutils literal">classifier</tt></a></h2>
<p>The <tt class="docutils literal">classifier</tt> element contains the classification or type of the
<a class="reference internal" href="#term">term</a> being defined in a <a class="reference internal" href="#definition-list">definition_list</a>. For example, it can be
used to indicate the type of a variable.</p>
<div class="section" id="details-9">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (simple)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">classifier</tt> has no direct analogues in common DTDs. It can be
emulated with primitives or type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#definition-list-item">definition_list_item</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#definition-list-item">definition_list_item</a> element contains <tt class="docutils literal">classifier</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">classifier</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<blockquote>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">classifier</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-9">
<h3>Examples</h3>
<p>Here is a hypothetical data dictionary. <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
name : string
Customer name.
i : int
Temporary index variable.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<definition_list>
<definition_list_item>
<term>
name
<classifier>
string
<definition>
<paragraph>
Customer name.
<definition_list_item>
<term>
i
<classifier>
int
<definition>
<paragraph>
Temporary index variable.
</pre>
</div>
</div>
<div class="section" id="colspec">
<h2><a class="toc-backref" href="#toc-entry-30"><tt class="docutils literal">colspec</tt></a></h2>
<p>Specifications for a column in a <a class="reference internal" href="#table">table</a>.</p>
<div class="section" id="details-10">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (simple)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">colspec</tt> is based on the <a class="citation-reference" href="#exchange-table-model" id="citation-reference-1">[exchange-table-model]</a> and
analogous to the DocBook "colspec" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">The <tt class="docutils literal">colspec</tt> element contains layout information for the parent
<a class="reference internal" href="#table">table</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#tgroup">tgroup</a> element contains <tt class="docutils literal">colspec</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">colspec</tt> is an empty element and has no children.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">colspec</tt> element contains the optional "colnum", "colname",
"colwidth", "colsep", "rowsep", "align", "char", and "charoff"
attributes defined in the <a class="reference internal" href="#exchange-table-model">exchange-table-model</a> plus the
<a class="reference internal" href="#common-attributes">common attributes</a> and <a class="reference internal" href="#stub">stub</a>.</p>
<p>Docutils uses only <a class="reference internal" href="#colwidth">colwidth</a> and <a class="reference internal" href="#stub">stub</a>.</p>
<div class="admonition attention last">
<p class="first admonition-title">Attention!</p>
<p>In contrast to the definition in the <a class="reference internal" href="#exchange-table-model">exchange-table-model</a>,
unitless values of the "colwidth" are interpreted as proportional
values, not fixed values with unit "pt".</p>
<!-- The reference implementation `html4css2` converts column
widths values to percentages. -->
<p class="last">Future versions of Docutils may use the standard form
<tt class="docutils literal">number*</tt>, e.g., “5*” for 5 times the proportion.</p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-10">
<h3>Examples</h3>
<p>See <a class="reference internal" href="#table">table</a>.</p>
</div>
</div>
<div class="section" id="comment">
<h2><a class="toc-backref" href="#toc-entry-31"><tt class="docutils literal">comment</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="compound">
<h2><a class="toc-backref" href="#toc-entry-32"><tt class="docutils literal">compound</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="contact">
<h2><a class="toc-backref" href="#toc-entry-33"><tt class="docutils literal">contact</tt></a></h2>
<p>The <tt class="docutils literal">contact</tt> element holds contact information for the author
(individual or group) of the document, or a third-party contact. It
is typically used for an email or web address.</p>
<div class="section" id="details-11">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">contact</tt> is analogous to the DocBook "email" element. The HTML
"address" element serves a similar purpose.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">contact</tt>: <a class="reference internal" href="#docinfo">docinfo</a>, <a class="reference internal" href="#authors">authors</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">contact</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<blockquote>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">contact</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">contact</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-11">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Contact: jrh@example.com
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="container">
<h2><a class="toc-backref" href="#toc-entry-34"><tt class="docutils literal">container</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="copyright">
<h2><a class="toc-backref" href="#toc-entry-35"><tt class="docutils literal">copyright</tt></a></h2>
<p>The <tt class="docutils literal">copyright</tt> element contains the document's copyright statement.</p>
<div class="section" id="details-12">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">copyright</tt> is analogous to the DocBook "copyright" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">copyright</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">copyright</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<blockquote>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">copyright</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">copyright</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-12">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Copyright: This document has been placed in the public domain.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<copyright>
This document has been placed in the public domain.
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="danger">
<h2><a class="toc-backref" href="#toc-entry-36"><tt class="docutils literal">danger</tt></a></h2>
<p>The <tt class="docutils literal">danger</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>, <a class="reference internal" href="#error">error</a>,
<a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic <a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-13">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">danger</tt> has no direct analogues in common DTDs. It can be
emulated with primitives and type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "!DANGER!" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">danger</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">danger</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<blockquote>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">danger</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">danger</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">danger</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-13">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. DANGER:: Mad scientist at work!
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<danger>
<paragraph>
Mad scientist at work!
</pre>
</div>
</div>
<div class="section" id="date">
<h2><a class="toc-backref" href="#toc-entry-37"><tt class="docutils literal">date</tt></a></h2>
<p>The <tt class="docutils literal">date</tt> element contains the date of publication, release, or
last modification of the document.</p>
<div class="section" id="details-14">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">date</tt> is analogous to the DocBook "date" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Often used with the RCS/CVS keyword "Date". See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">date</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">date</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<blockquote>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">date</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">date</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-14">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Date: 2002-08-20
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<date>
2002-08-20
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="decoration">
<h2><a class="toc-backref" href="#toc-entry-38"><tt class="docutils literal">decoration</tt></a></h2>
<p>The <tt class="docutils literal">decoration</tt> element is a container for <a class="reference internal" href="#header">header</a> and <a class="reference internal" href="#footer">footer</a>
elements and potential future extensions. These elements are used for
notes, time/datestamp, processing information, etc.</p>
<div class="section" id="details-15">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-subelements">Structural Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first">There are no direct analogies to <tt class="docutils literal">decoration</tt> in HTML or in
DocBook. Equivalents are typically constructed from primitives
and/or generated by the processing system.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See the individual <a class="reference internal" href="#decorative-elements">decorative elements</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#document">document</a> element contains <tt class="docutils literal">decoration</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">decoration</tt> elements may contain <a class="reference internal" href="#decorative-elements">decorative elements</a>.</p>
<blockquote class="last">
<pre class="literal-block">
(<a class="reference internal" href="#header">header</a>?, <a class="reference internal" href="#footer">footer</a>?)
</pre>
</blockquote>
</td>
</tr>
</tbody>
</table>
<p>Although the content model doesn't specifically require contents, no
empty <tt class="docutils literal">decoration</tt> elements are ever created.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body">The <tt class="docutils literal">decoration</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-15">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
A paragraph.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms,
assuming that the datestamp command-line option or configuration
setting has been supplied:</p>
<pre class="literal-block">
<document>
<decoration>
<footer>
<paragraph>
Generated on: 2002-08-20.
<paragraph>
A paragraph.
</pre>
</div>
</div>
<div class="section" id="definition">
<h2><a class="toc-backref" href="#toc-entry-39"><tt class="docutils literal">definition</tt></a></h2>
<p>The <tt class="docutils literal">definition</tt> element is a container for the body elements used
to define a <a class="reference internal" href="#term">term</a> in a <a class="reference internal" href="#definition-list">definition_list</a>.</p>
<div class="section" id="details-16">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (compound)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">definition</tt> is analogous to the HTML "dd" element and to the
DocBook "listitem" element (inside a "variablelistentry" element).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#definition-list-item">definition_list_item</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only <a class="reference internal" href="#definition-list-item">definition_list_item</a> elements contain <tt class="docutils literal">definition</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">definition</tt> elements contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<blockquote>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">definition</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-16">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#definition-list">definition_list</a>, <a class="reference internal" href="#definition-list-item">definition_list_item</a>, and
<a class="reference internal" href="#classifier">classifier</a> elements.</p>
</div>
</div>
<div class="section" id="definition-list">
<h2><a class="toc-backref" href="#toc-entry-40"><tt class="docutils literal">definition_list</tt></a></h2>
<p>The <tt class="docutils literal">definition_list</tt> element contains a list of terms and their
definitions. It can be used for glossaries or dictionaries, to
describe or classify things, for dialogues, or to itemize subtopics
(such as in this reference).</p>
<div class="section" id="details-17">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">definition_list</tt>.</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><tt class="docutils literal">definition_list</tt> elements contain one or more
<a class="reference internal" href="#definition-list-item">definition_list_item</a> elements.</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><tt class="docutils literal">definition_list</tt> is analogous to the HTML "dl" element and to
the DocBook "variablelist" element.</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body">See <a class="reference internal" href="#definition-list-item">definition_list_item</a>.</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body">The <tt class="docutils literal">definition_list</tt> element contains only the <a class="reference internal" href="#common-attributes">common
attributes</a>.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">definition_list</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">definition_list</tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-17">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Term
Definition.
Term : classifier
The ' : ' indicates a classifier in
definition list item terms only.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<definition_list>
<definition_list_item>
<term>
Term
<definition>
<paragraph>
Definition.
<definition_list_item>
<term>
Term
<classifier>
classifier
<definition>
<paragraph>
The ' : ' indicates a classifier in
definition list item terms only.
</pre>
<p>See <a class="reference internal" href="#definition-list-item">definition_list_item</a> and <a class="reference internal" href="#classifier">classifier</a> for further examples.</p>
</div>
</div>
<div class="section" id="definition-list-item">
<h2><a class="toc-backref" href="#toc-entry-41"><tt class="docutils literal">definition_list_item</tt></a></h2>
<p>The <tt class="docutils literal">definition_list_item</tt> element contains a single
<a class="reference internal" href="#term">term</a>/<a class="reference internal" href="#definition">definition</a> pair (with optional <a class="reference internal" href="#classifier">classifier</a>).</p>
<div class="section" id="details-18">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (compound)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">definition_list_item</tt> is analogous to the DocBook
"variablelistentry" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">The optional <a class="reference internal" href="#classifier">classifier</a> can be rendered differently from the
<a class="reference internal" href="#term">term</a>. They should be separated visually, typically by spaces
plus a colon or dash.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#definition-list">definition_list</a> element contains
<tt class="docutils literal">definition_list_item</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">definition_list_item</tt> elements each contain a single <a class="reference internal" href="#term">term</a>,
an optional <a class="reference internal" href="#classifier">classifier</a>, and a <a class="reference internal" href="#definition">definition</a>:</p>
<pre class="literal-block">
(term, classifier?, definition)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">definition_list_item</tt> element contains only the <a class="reference internal" href="#common-attributes">common
attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-18">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Tyrannosaurus Rex : carnivore
Big and scary; the "Tyrant King".
Brontosaurus : herbivore
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
-- Anne Elk (Miss)
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<definition_list>
<definition_list_item>
<term>
Tyrannosaurus Rex
<classifier>
carnivore
<definition>
<paragraph>
Big and scary; the "Tyrant King".
<definition_list_item>
<term>
Brontosaurus
<classifier>
herbivore
<definition>
<paragraph>
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
<paragraph>
-- Anne Elk (Miss)
</pre>
<p>See <a class="reference internal" href="#definition-list">definition_list</a> and <a class="reference internal" href="#classifier">classifier</a> for further examples.</p>
</div>
</div>
<div class="section" id="description">
<h2><a class="toc-backref" href="#toc-entry-42"><tt class="docutils literal">description</tt></a></h2>
<p>The <tt class="docutils literal">description</tt> element contains body elements, describing the
purpose or effect of a command-line option or group of options.</p>
<div class="section" id="details-19">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">description</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#option-list">option_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#option-list-item">option_list_item</a> element contains <tt class="docutils literal">description</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">description</tt> elements may contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">description</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-19">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#option-list">option_list</a> element.</p>
</div>
</div>
<div class="section" id="docinfo">
<h2><a class="toc-backref" href="#toc-entry-43"><tt class="docutils literal">docinfo</tt></a></h2>
<p>The <tt class="docutils literal">docinfo</tt> element is a container for displayed document bibliographic
data, or meta-data (data about the document). It corresponds to the
front matter of a book, such as the title page and copyright page.</p>
<p>See also the <a class="reference internal" href="#meta">meta</a> element (for "hidden" meta-data).</p>
<div class="section" id="details-20">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-subelements">Structural Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">docinfo</tt> is analogous to DocBook "info" elements ("bookinfo"
etc.). There are no directly analogous HTML elements; the "meta"
element carries some of the same information, albeit invisibly.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">The <tt class="docutils literal">docinfo</tt> element may be rendered as a two-column table or
in other styles. It may even be invisible or omitted from the
processed output. Meta-data may be extracted from <tt class="docutils literal">docinfo</tt>
children; for example, HTML <tt class="docutils literal"><meta></tt> tags may be constructed.</p>
<p>When <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a> transforms a <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> <a class="reference internal" href="#field-list">field_list</a> into a
<tt class="docutils literal">docinfo</tt> element (see the examples below), RCS/CVS keywords are
normally stripped from simple (one paragraph) field bodies. For
complete details, please see <a class="reference external" href="rst/restructuredtext.html#rcs-keywords">RCS Keywords</a> in the
<a class="reference external" href="rst/restructuredtext.html">reStructuredText Markup Specification</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#document">document</a> element contains <tt class="docutils literal">docinfo</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">docinfo</tt> elements contain <a class="reference internal" href="#bibliographic-elements">bibliographic elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">docinfo</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-20">
<h3>Examples</h3>
<p>Docinfo is represented in <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> by a <a class="reference internal" href="#field-list">field_list</a> in a
bibliographic context: the first non-comment element of a <a class="reference internal" href="#document">document</a>,
after any document <a class="reference internal" href="#title">title</a>/<a class="reference internal" href="#subtitle">subtitle</a>. The field list is transformed
into a <tt class="docutils literal">docinfo</tt> element and its children by a transform. Source:</p>
<pre class="literal-block">
Docinfo Example
===============
:Author: J. Random Hacker
:Contact: jrh@example.com
:Date: 2002-08-18
:Status: Work In Progress
:Version: 1
:Filename: $RCSfile$
:Copyright: This document has been placed in the public domain.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="docinfo-example" names="docinfo example">
<title>
Docinfo Example
<docinfo>
<author>
J. Random Hacker
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
<date>
2002-08-18
<status>
Work In Progress
<version>
1
<field>
<field_name>
Filename
<field_body>
<paragraph>
doctree.txt
<copyright>
This document has been placed in the public domain.
</pre>
<p>Note that "Filename" is a non-standard <tt class="docutils literal">docinfo</tt> field, so becomes a
generic <tt class="docutils literal">field</tt> element. Also note that the "RCSfile" keyword
syntax has been stripped from the "Filename" data.</p>
<p>See <a class="reference internal" href="#field-list">field_list</a> for an example in a non-bibliographic context. Also
see the individual examples for the various <a class="reference internal" href="#bibliographic-elements">bibliographic elements</a>.</p>
</div>
</div>
<div class="section" id="doctest-block">
<h2><a class="toc-backref" href="#toc-entry-44"><tt class="docutils literal">doctest_block</tt></a></h2>
<p>The <tt class="docutils literal">doctest_block</tt> element is a Python-specific variant of
<a class="reference internal" href="#literal-block">literal_block</a>. It is a block of text where line breaks and
whitespace are significant and must be preserved. <tt class="docutils literal">doctest_block</tt>
elements are used for interactive Python interpreter sessions, which
are distinguished by their input prompt: <tt class="docutils literal">>>></tt>. They are meant to
illustrate usage by example, and provide an elegant and powerful
testing environment via the <a class="reference external" href="https://docs.python.org/3/library/doctest.html">doctest module</a> in the Python standard
library.</p>
<div class="section" id="details-21">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#simple-body-elements">Simple Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">doctest_block</tt> is analogous to the HTML "pre" element and to
the DocBook "programlisting" and "screen" elements.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">As with <a class="reference internal" href="#literal-block">literal_block</a>, <tt class="docutils literal">doctest_block</tt> elements are typically
rendered in a monospaced typeface. It is crucial that all
whitespace and line breaks are preserved in the rendered form.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">doctest_block</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">doctest_block</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">doctest_block</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#xml-space">xml:space</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">doctest_block</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">doctest_block</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-21">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
This is an ordinary paragraph.
>>> print 'this is a Doctest block'
this is a Doctest block
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
This is an ordinary paragraph.
<doctest_block xml:space="preserve">
>>> print 'this is a Doctest block'
this is a Doctest block
</pre>
</div>
</div>
<div class="section" id="document">
<h2><a class="toc-backref" href="#toc-entry-45"><tt class="docutils literal">document</tt></a></h2>
<p>The <tt class="docutils literal">document</tt> element is the root (topmost) element of the Docutils
document tree. <tt class="docutils literal">document</tt> is the direct or indirect ancestor of
every other element in the tree. It encloses the entire document
tree. It is the starting point for a document.</p>
<div class="section" id="details-22">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-elements">Structural Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">document</tt> is analogous to the HTML "html" element and to
several DocBook elements such as "book".</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The <tt class="docutils literal">document</tt> element has no parents.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">document</tt> elements may contain <a class="reference internal" href="#structural-subelements">structural subelements</a>,
<a class="reference internal" href="#structural-elements">structural elements</a>, and <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="last literal-block">
( (<a class="reference internal" href="#title">title</a>, <a class="reference internal" href="#subtitle">subtitle</a>?)?,
<a class="reference internal" href="#decoration">decoration</a>?,
(<a class="reference internal" href="#docinfo">docinfo</a>, <a class="reference internal" href="#transition">transition</a>?)?,
<a class="reference internal" href="#structure-model">%structure.model;</a> )
</pre>
</td>
</tr>
</tbody>
</table>
<p>Depending on the source of the data and the stage of processing, the
"document" may not initially contain a "title". A document title is
not directly representable in <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>. Instead, a lone
top-level section may have its title promoted to become the document
<a class="reference internal" href="#title">title</a>, and similarly for a lone second-level (sub)section's title to
become the document <a class="reference internal" href="#subtitle">subtitle</a>.</p>
<p>The contents of "<a class="reference internal" href="#decoration">decoration</a>" may be specified in a document,
constructed programmatically, or both. The "<a class="reference internal" href="#docinfo">docinfo</a>" may be
transformed from an initial <a class="reference internal" href="#field-list">field_list</a>.</p>
<p>See the <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity for details of the body
of a <tt class="docutils literal">document</tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body">The <tt class="docutils literal">document</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a> (<a class="reference internal" href="#ids">ids</a>,
<a class="reference internal" href="#names">names</a>, <a class="reference internal" href="#dupnames">dupnames</a>, <a class="reference internal" href="#source">source</a>, and <a class="reference internal" href="#classes">classes</a>), plus an optional
<a class="reference internal" href="#title-attribute">title attribute</a> which stores the document title metadata.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-22">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
A Title
=======
A paragraph.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result from simple parsing:</p>
<pre class="literal-block">
<document>
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
</pre>
<p>After applying transforms, the section title is promoted to become the
document title:</p>
<pre class="literal-block">
<document ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
</pre>
</div>
</div>
<div class="section" id="emphasis">
<h2><a class="toc-backref" href="#toc-entry-46"><tt class="docutils literal">emphasis</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="entry">
<h2><a class="toc-backref" href="#toc-entry-47"><tt class="docutils literal">entry</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="enumerated-list">
<h2><a class="toc-backref" href="#toc-entry-48"><tt class="docutils literal">enumerated_list</tt></a></h2>
<p>The <tt class="docutils literal">enumerated_list</tt> element contains <a class="reference internal" href="#list-item">list_item</a> elements which are
uniformly marked with enumerator labels.</p>
<div class="section" id="details-23">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">enumerated_list</tt> is analogous to the HTML "ol" element and to
the DocBook "orderedlist" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Each list item should begin a new vertical block, prefaced by a
enumeration marker (such as "1.").</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">enumerated_list</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">enumerated_list</tt> elements contain one or more <a class="reference internal" href="#list-item">list_item</a>
elements:</p>
<pre class="literal-block">
(list_item+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">enumerated_list</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#enumtype">enumtype</a>,
<a class="reference internal" href="#prefix">prefix</a>, <a class="reference internal" href="#suffix">suffix</a>, and <a class="reference internal" href="#start">start</a>.</p>
<p><tt class="docutils literal">enumtype</tt> is used to record the intended enumeration sequence,
one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
"upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
MMMMCMXCIX [4999]).</p>
<p><tt class="docutils literal">prefix</tt> stores the formatting characters used before the
enumerator. In documents originating from <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> data,
it will contain either "" (empty string) or "(" (left
parenthesis). It may or may not affect processing.</p>
<p><tt class="docutils literal">suffix</tt> stores the formatting characters used after the
enumerator. In documents originating from <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> data,
it will contain either "." (period) or ")" (right parenthesis).
Depending on the capabilities of the output format, this attribute
may or may not affect processing.</p>
<p><tt class="docutils literal">start</tt> contains the ordinal value of the first item in the
list, in decimal. For lists beginning at value 1 ("1", "a", "A",
"i", or "I"), this attribute may be omitted.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">enumerated_list</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">enumerated_list</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-23">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
1. Item 1.
(A) Item A.
(B) Item B.
(C) Item C.
2. Item 2.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Item 1.
<enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
<list_item>
<paragraph>
Item A.
<list_item>
<paragraph>
Item B.
<list_item>
<paragraph>
Item C.
<list_item>
<paragraph>
Item 2.
</pre>
<p>See <a class="reference internal" href="#list-item">list_item</a> for another example.</p>
</div>
</div>
<div class="section" id="error">
<h2><a class="toc-backref" href="#toc-entry-49"><tt class="docutils literal">error</tt></a></h2>
<p>The <tt class="docutils literal">error</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>,
<a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic
<a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-24">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">error</tt> has no direct analogues in common DTDs. It can be
emulated with primitives and type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Error" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">error</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">error</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">error</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">error</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly
includes <tt class="docutils literal">error</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-24">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Error:: Does not compute.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<error>
<paragraph>
Does not compute.
</pre>
</div>
</div>
<div class="section" id="field">
<h2><a class="toc-backref" href="#toc-entry-50"><tt class="docutils literal">field</tt></a></h2>
<p>The <tt class="docutils literal">field</tt> element contains a pair of <a class="reference internal" href="#field-name">field_name</a> and <a class="reference internal" href="#field-body">field_body</a>
elements.</p>
<div class="section" id="details-25">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">field</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#field-list">field_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">field</tt>: <a class="reference internal" href="#docinfo">docinfo</a>,
<a class="reference internal" href="#field-list">field_list</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first">Each <tt class="docutils literal">field</tt> element contains one <a class="reference internal" href="#field-name">field_name</a> and one
<a class="reference internal" href="#field-body">field_body</a> element:</p>
<pre class="literal-block">
(field_name, field_body)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">field</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">field</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-25">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#field-list">field_list</a> and <a class="reference internal" href="#docinfo">docinfo</a> elements.</p>
</div>
</div>
<div class="section" id="field-body">
<h2><a class="toc-backref" href="#toc-entry-51"><tt class="docutils literal">field_body</tt></a></h2>
<p>The <tt class="docutils literal">field_body</tt> element contains body elements. It is analogous to
a database field's data.</p>
<div class="section" id="details-26">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">field_body</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#field-list">field_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#field">field</a> element contains <tt class="docutils literal">field_body</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">field_body</tt> elements may contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)*
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">field_body</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-26">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#field-list">field_list</a> and <a class="reference internal" href="#docinfo">docinfo</a> elements.</p>
</div>
</div>
<div class="section" id="field-list">
<h2><a class="toc-backref" href="#toc-entry-52"><tt class="docutils literal">field_list</tt></a></h2>
<p>The <tt class="docutils literal">field_list</tt> element contains two-column table-like structures
resembling database records (label & data pairs). Field lists are
often meant for further processing. In <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>, field lists
are used to represent bibliographic fields (contents of the <a class="reference internal" href="#docinfo">docinfo</a>
element) and <a class="reference external" href="rst/restructuredtext.html#directive-options">directive options</a>.</p>
<div class="section" id="details-27">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">field_list</tt> has no direct analogues in common DTDs. It can be
emulated with primitives such as tables.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">A <tt class="docutils literal">field_list</tt> is typically rendered as a two-column list, where
the first column contains "labels" (usually with a colon suffix).
However, field lists are often used for extension syntax or
special processing. Such structures do not survive as field lists
to be rendered.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">field_list</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">field_list</tt> elements contain one or more <a class="reference internal" href="#field">field</a> elements.</p>
<pre class="literal-block">
(field+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">field_list</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">field_list</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">field_list</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-27">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
:Author: Me
:Version: 1
:Date: 2001-08-11
:Parameter i: integer
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<field_list>
<field>
<field_name>
Author
<field_body>
<paragraph>
Me
<field>
<field_name>
Version
<field_body>
<paragraph>
1
<field>
<field_name>
Date
<field_body>
<paragraph>
2001-08-11
<field>
<field_name>
Parameter i
<field_body>
<paragraph>
integer
</pre>
</div>
</div>
<div class="section" id="field-name">
<h2><a class="toc-backref" href="#toc-entry-53"><tt class="docutils literal">field_name</tt></a></h2>
<p>The <tt class="docutils literal">field_name</tt> element contains text; it is analogous to a
database field's name.</p>
<div class="section" id="details-28">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (simple)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">field_name</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#field-list">field_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#field">field</a> element contains <tt class="docutils literal">field_name</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">field_name</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">field_name</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-28">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#field-list">field_list</a> and <a class="reference internal" href="#docinfo">docinfo</a> elements.</p>
</div>
</div>
<div class="section" id="figure">
<h2><a class="toc-backref" href="#toc-entry-54"><tt class="docutils literal">figure</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="footer">
<h2><a class="toc-backref" href="#toc-entry-55"><tt class="docutils literal">footer</tt></a></h2>
<p>The <tt class="docutils literal">footer</tt> element is a container element whose contents are meant
to appear at the bottom of a web page, or repeated at the bottom of
every printed page. The <tt class="docutils literal">footer</tt> element may contain processing
information (datestamp, a link to <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a>, etc.) as well as custom
content.</p>
<div class="section" id="details-29">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#decorative-elements">Decorative Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">footer</tt> is analogous to the HTML5 "footer" element.
There are no direct analogies to <tt class="docutils literal">footer</tt> in HTML4 or DocBook.
Equivalents are typically constructed from primitives and/or
generated by the processing system.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#decoration">decoration</a> element contains <tt class="docutils literal">footer</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">footer</tt> elements may contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">footer</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-29">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
A paragraph.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms,
assuming that the datestamp command-line option or configuration
setting has been supplied:</p>
<pre class="literal-block">
<document>
<decoration>
<footer>
<paragraph>
Generated on: 2002-08-20.
<paragraph>
A paragraph.
</pre>
</div>
</div>
<div class="section" id="footnote">
<h2><a class="toc-backref" href="#toc-entry-56"><tt class="docutils literal">footnote</tt></a></h2>
<p>The <tt class="docutils literal">footnote</tt> element is used for labeled <a class="reference external" href="https://en.wikipedia.org/wiki/Note_(typography)">notes</a> that provide
additional context to a passage of text (<em>footnotes</em> or <em>endnotes</em>).
The corresponding footnote mark in running text is set by the
<a class="reference internal" href="#footnote-reference">footnote_reference</a> element.</p>
<div class="section" id="details-30">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">footnote</tt> has no direct analogues in DocBook or HTML.</p>
<p>The <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/footnote.html">DocBook "footnote"</a> element combines features of <tt class="docutils literal">footnote</tt>
and <a class="reference internal" href="#footnote-reference">footnote_reference</a>.</p>
<p>The DPub ARIA role <a class="reference external" href="https://www.w3.org/TR/dpub-aria-1.0/#doc-footnote">"doc-footnote"</a> may be used to mark a (<a class="reference external" href="https://www.w3.org/TR/html-aria/#docconformance">conforming</a>)
<a class="reference external" href="https://www.w3.org/TR/html51/common-idioms-without-dedicated-elements.html#footnotes">HTML emulation</a> as "ancillary information, such as a citation or
commentary, that provides additional context to a referenced passage
of text".</p>
<p>For collections of notes that occur at the end of a section, the
the DPub ARIA role <a class="reference external" href="https://www.w3.org/TR/dpub-aria-1.0/#doc-endnotes">"doc-endnotes"</a> is more appropriate.</p>
<p>The corresponding types in the <a class="reference external" href="https://www.w3.org/TR/epub-ssv-11/#notes">EPUB 3 Structural Semantics
Vocabulary</a> are "footnote" and "endnote".</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">A <tt class="docutils literal">footnote</tt> element should be set off from the rest of the
document, e.g. with a border or using a smaller font size.</p>
<p>Footnotes may "float" to the bottom or margin of a page or a
dedicated section.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">footnote</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">footnote</tt> elements begin with an optional <a class="reference internal" href="#label">label</a>
and contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(label?, (<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">footnote</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#auto">auto</a> and <a class="reference internal" href="#backrefs">backrefs</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">footnote</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly
includes <tt class="docutils literal">footnote</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-30">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> uses <a class="reference external" href="rst/restructuredtext.html#explicit-markup-blocks">explicit markup blocks</a> for footnotes:</p>
<pre class="literal-block">
.. [1] This is a footnote.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<footnote ids="id1" names="1">
<label>
1
<paragraph>
This is a footnote.
</pre>
</div>
</div>
<div class="section" id="footnote-reference">
<h2><a class="toc-backref" href="#toc-entry-57"><tt class="docutils literal">footnote_reference</tt></a></h2>
<p>The <tt class="docutils literal">footnote_reference</tt> element is an inline element representing a
cross reference to a <a class="reference internal" href="#footnote">footnote</a> (a footnote mark).</p>
<div class="section" id="details-31">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#inline-elements">Inline Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first">The <tt class="docutils literal">footnote_reference</tt> element resembles the <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/footnoteref.html">DocBook
"footnoteref"</a> element or the LaTeX <tt class="docutils literal">\footnotemark</tt> command.</p>
<p>There is no equivalent in HTML. The <tt class="docutils literal"><a></tt> element can be used
to provide a link to the corresponding footnote.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">A <tt class="docutils literal">footnote_reference</tt> should generate a mark matching the <a class="reference internal" href="#label">label</a>
of the referenced footnote. The mark is typically formatted as
superscript or enclosed i square brackets.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#inline-elements-1">%inline.elements;</a> parameter entities in
their content models may contain <tt class="docutils literal"><span class="pre">footnote-reference</span></tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">footnote_reference</tt> elements may contain text data.</p>
<pre class="literal-block">
(#PCDATA)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">footnote_reference</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#auto">auto</a>, <a class="reference internal" href="#refid">refid</a>, and <a class="reference internal" href="#refname">refname</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-31">
<h3>Examples</h3>
<p>reStructuredText source fragment:</p>
<pre class="literal-block">
[#]_ is an auto-numbered footnote reference.
.. [#] Auto-numbered footnote 1.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
<footnote_reference auto="1" ids="id1">
is an auto-numbered footnote reference.
<footnote auto="1" ids="id3">
<paragraph>
Auto-numbered footnote 1.
</pre>
<p>The <tt class="docutils literal">references.Footnotes</tt> Docutils <a class="reference external" href="api/.html">transform</a> resolves this to:</p>
<pre class="literal-block">
<paragraph>
<footnote_reference auto="1" ids="id1" refid="id2">
1
is an auto-numbered footnote reference.
<footnote auto="1" backrefs="id1" ids="id2" names="1">
<label>
1
<paragraph>
Auto-numbered footnote 1.
</pre>
</div>
</div>
<div class="section" id="generated">
<h2><a class="toc-backref" href="#toc-entry-58"><tt class="docutils literal">generated</tt></a></h2>
<p>Docutils wraps <tt class="docutils literal">generated</tt> elements around text that is inserted
(generated) by Docutils; i.e., text that was not in the document, like
section numbers inserted by the "sectnum" directive.</p>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="header">
<h2><a class="toc-backref" href="#toc-entry-59"><tt class="docutils literal">header</tt></a></h2>
<p>The <tt class="docutils literal">header</tt> element is a container element whose contents are meant
to appear at the top of a web page, or at the top of every printed
page.</p>
<div class="section" id="details-32">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#decorative-elements">Decorative Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">header</tt> is analogous to the HTML5 "header" element.
There are no direct analogies to <tt class="docutils literal">header</tt> in HTML4 or DocBook.
Equivalents are typically constructed from primitives and/or
generated by the processing system.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#decoration">decoration</a> element contains <tt class="docutils literal">header</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">header</tt> elements may contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">header</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-32">
<h3>Examples</h3>
<p>reStructuredText source fragment:</p>
<pre class="literal-block">
.. header:: This space for rent.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<document>
<decoration>
<header>
<paragraph>
This space for rent.
</pre>
</div>
</div>
<div class="section" id="hint">
<h2><a class="toc-backref" href="#toc-entry-60"><tt class="docutils literal">hint</tt></a></h2>
<p>The <tt class="docutils literal">hint</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>,
<a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic
<a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-33">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">hint</tt> has no direct analogues in common DTDs. It can be
emulated with primitives and type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Hint" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">hint</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">hint</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">hint</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">hint</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly
includes <tt class="docutils literal">hint</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-33">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Hint:: It's bigger than a bread box.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<hint>
<paragraph>
It's bigger than a bread box.
</pre>
</div>
</div>
<div class="section" id="image">
<h2><a class="toc-backref" href="#toc-entry-61"><tt class="docutils literal">image</tt></a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body">The <tt class="docutils literal">image</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus uri, <a class="reference internal" href="#align">align</a>, alt, <a class="reference internal" href="#height">height</a>, <a class="reference internal" href="#width">width</a>, and <a class="reference internal" href="#scale">scale</a>.</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="important">
<h2><a class="toc-backref" href="#toc-entry-62"><tt class="docutils literal">important</tt></a></h2>
<p>The <tt class="docutils literal">important</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>,
<a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic
<a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-34">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><tt class="docutils literal">important</tt> is analogous to the <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/important.html">DocBook "important"</a> element.</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Important" (or similar).</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">important</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">important</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">important</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">important</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">important</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-34">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Important::
* Wash behind your ears.
* Clean up your room.
* Back up your data.
* Call your mother.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<important>
<bullet_list>
<list_item>
<paragraph>
Wash behind your ears.
<list_item>
<paragraph>
Clean up your room.
<list_item>
<paragraph>
Back up your data.
<list_item>
<paragraph>
Call your mother.
</pre>
</div>
</div>
<div class="section" id="inline">
<h2><a class="toc-backref" href="#toc-entry-63"><tt class="docutils literal">inline</tt></a></h2>
<p>The <tt class="docutils literal">inline</tt> element is a generic inline container.</p>
<div class="section" id="details-35">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#inline-elements">Inline Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">inline</tt> is analogous to the HTML "span" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Writers typically pass the <a class="reference internal" href="#classes">classes</a> attribute to the output document
and leave styling to the backend or a custom <a class="reference external" href="../user/config.html#stylesheet">stylesheet</a>. They may
also process the <a class="reference internal" href="#classes">classes</a> attribute and convert the <tt class="docutils literal">inline</tt>
element to a specific element or render the content distinctly
for specific class values. Moreover, writers may ignore the classes
attribute and render the content as ordinary text.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#inline-elements-1">%inline.elements;</a> parameter entities in
their content models may contain <tt class="docutils literal">inline</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">inline</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">inline</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-35">
<h3>Examples</h3>
<p><a class="reference external" href="rst/directives.html#custom-interpreted-text-roles">Custom interpreted text roles</a> create <tt class="docutils literal">inline</tt> elements (unless they
are based on a <a class="reference external" href="rst/roles.html">standard role</a>).</p>
<p>reStructuredText source fragment:</p>
<pre class="literal-block">
.. role:: custom
An example of using :custom:`interpreted text`
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
An example of using
<inline classes="custom">
interpreted text
</pre>
</div>
</div>
<div class="section" id="label">
<h2><a class="toc-backref" href="#toc-entry-64"><tt class="docutils literal">label</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="legend">
<h2><a class="toc-backref" href="#toc-entry-65"><tt class="docutils literal">legend</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="line">
<h2><a class="toc-backref" href="#toc-entry-66"><tt class="docutils literal">line</tt></a></h2>
<p>The <tt class="docutils literal">line</tt> element contains a single line of text, part of a
<a class="reference internal" href="#line-block">line_block</a>.</p>
<div class="section" id="details-36">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (simple)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#line-block">line_block</a> element contains <tt class="docutils literal">line</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">line</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">line</tt> has no direct analogues in common DTDs. It can be
emulated with primitives or type effects.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#line-block">line_block</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#inline-elements-1">%inline.elements;</a> parameter entities in
their content models may contain <tt class="docutils literal">inline</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">inline</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">line</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-36">
<h3>Examples</h3>
<p>See <a class="reference internal" href="#line-block">line_block</a>.</p>
</div>
</div>
<div class="section" id="line-block">
<h2><a class="toc-backref" href="#toc-entry-67"><tt class="docutils literal">line_block</tt></a></h2>
<p>The <tt class="docutils literal">line_block</tt> element contains a sequence of lines and nested
line blocks. Line breaks (implied between elements) and leading
whitespace (indicated by nesting) is significant and must be
preserved. <tt class="docutils literal">line_block</tt> elements are commonly used for verse and
addresses. See <a class="reference internal" href="#literal-block">literal_block</a> for an alternative useful for program
listings and interactive computer sessions.</p>
<div class="section" id="details-37">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">line_block</tt> is analogous to the DocBook "literallayout" element
and to the HTML "pre" element (with modifications to typeface
styles).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Unlike <tt class="docutils literal">literal_block</tt>, <tt class="docutils literal">line_block</tt> elements are typically
rendered in an ordinary text typeface. It is crucial that leading
whitespace and line breaks are preserved in the rendered form.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">line_block</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">line_block</tt> elements may contain <a class="reference internal" href="#line">line</a> elements and nested
<a class="reference internal" href="#line-block">line_block</a> elements.</p>
<pre class="literal-block">
(line | line_block)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">line_block</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">line_block</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">line_block</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-37">
<h3>Examples</h3>
<p>Example source:</p>
<pre class="literal-block">
Take it away, Eric the Orchestra Leader!
| A one, two, a one two three four
|
| Half a bee, philosophically,
| must, *ipso facto*, half not be.
| But half the bee has got to be,
| *vis a vis* its entity. D'you see?
|
| But can a bee be said to be
| or not to be an entire bee,
| when half the bee is not a bee,
| due to some ancient injury?
|
| Singing...
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
Take it away, Eric the Orchestra Leader!
<line_block>
<line>
A one, two, a one two three four
<line>
<line>
Half a bee, philosophically,
<line_block>
<line>
must,
<emphasis>
ipso facto
, half not be.
<line>
But half the bee has got to be,
<line_block>
<line>
<emphasis>
vis a vis
its entity. D'you see?
<line>
<line>
But can a bee be said to be
<line_block>
<line>
or not to be an entire bee,
<line_block>
<line>
when half the bee is not a bee,
<line_block>
<line>
due to some ancient injury?
<line>
<line>
Singing...
</pre>
</div>
</div>
<div class="section" id="list-item">
<h2><a class="toc-backref" href="#toc-entry-68"><tt class="docutils literal">list_item</tt></a></h2>
<p>The <tt class="docutils literal">list_item</tt> element is a container for the elements of a list
item.</p>
<div class="section" id="details-38">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (compound)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">list_item</tt> is analogous to the HTML "li" element and to the
DocBook "listitem" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#bullet-list">bullet_list</a> or <a class="reference internal" href="#enumerated-list">enumerated_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The <a class="reference internal" href="#bullet-list">bullet_list</a> and <a class="reference internal" href="#enumerated-list">enumerated_list</a> elements contain
<tt class="docutils literal">list_item</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">list_item</tt> elements may contain <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)*
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">list_item</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-38">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
1. Outer list, item 1.
* Inner list, item 1.
* Inner list, item 2.
2. Outer list, item 2.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Outer list, item 1.
<bullet_list bullet="*">
<list_item>
<paragraph>
Inner list, item 1.
<list_item>
<paragraph>
Inner list, item 2.
<list_item>
<paragraph>
Outer list, item 2.
</pre>
<p>See <a class="reference internal" href="#bullet-list">bullet_list</a> or <a class="reference internal" href="#enumerated-list">enumerated_list</a> for further examples.</p>
</div>
</div>
<div class="section" id="literal">
<h2><a class="toc-backref" href="#toc-entry-69"><tt class="docutils literal">literal</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="literal-block">
<h2><a class="toc-backref" href="#toc-entry-70"><tt class="docutils literal">literal_block</tt></a></h2>
<p>The <tt class="docutils literal">literal_block</tt> element contains a block of text where line
breaks and whitespace are significant and must be preserved.
<tt class="docutils literal">literal_block</tt> elements are commonly used for program listings and
interactive computer sessions. See <a class="reference internal" href="#line-block">line_block</a> for an alternative
useful for verse and addresses.</p>
<div class="section" id="details-39">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#simple-body-elements">Simple Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">literal_block</tt> is analogous to the HTML "pre" element and to
the DocBook "programlisting" and "screen" elements.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first"><tt class="docutils literal">literal_block</tt> elements are typically rendered in a monospaced
typeface. It is crucial that all whitespace and line breaks are
preserved in the rendered form.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">literal_block</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">literal_block</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">literal_block</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#xml-space">xml:space</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">literal_block</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">literal_block</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-39">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
Here is a literal block::
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
Here is a literal block:
<literal_block xml:space="preserve">
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
</pre>
</div>
</div>
<div class="section" id="math">
<h2><a class="toc-backref" href="#toc-entry-71"><tt class="docutils literal">math</tt></a></h2>
<p>The <tt class="docutils literal">math</tt> element contains text in <cite>LaTeX math format</cite> <a class="footnote-reference" href="#latex-math" id="footnote-reference-1">[1]</a>
that is typeset as mathematical notation (inline formula).</p>
<p>If the output format does not support math typesetting, the content is
inserted verbatim.</p>
<div class="section" id="details-40">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#inline-elements">Inline Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">math</tt> is analogous to a MathML "math" element or
the LaTeX (<tt class="docutils literal">$ math $</tt>) mode.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered as mathematical notation.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#inline-elements-1">%inline.elements;</a> parameter entities in
their content models may contain <tt class="docutils literal">math</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">math</tt> elements may contain text data.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">math</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="latex-math" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#footnote-reference-1">1</a>, <a class="fn-backref" href="#footnote-reference-2">2</a>)</em> For details of the supported mathematical language, see
the <a class="reference external" href="rst/directives.html#math">"math" directive</a></td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="math-block">
<h2><a class="toc-backref" href="#toc-entry-72"><tt class="docutils literal">math_block</tt></a></h2>
<p>The <tt class="docutils literal">math_block</tt> element contains a block of text in <cite>LaTeX math
format</cite> <a class="footnote-reference" href="#latex-math" id="footnote-reference-2">[1]</a> that is typeset as mathematical notation
(display formula). The <tt class="docutils literal">math_block</tt> element is generated during
the initial parse from a <a class="reference external" href="rst/directives.html#math">"math" directive</a>.</p>
<p>If the output format does not support math typesetting, the content is
inserted verbatim.</p>
<div class="section" id="details-41">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#simple-body-elements">Simple Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">math_block</tt> is analogous to a LaTeX "equation*" environment or
a MathML "math" element displayed as block-level element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered in a block as mathematical notation, typically centered or with
indentation</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">math_block</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">math_block</tt> elements may contain text data.</p>
<pre class="literal-block">
(#PCDATA)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">math</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="meta">
<h2><a class="toc-backref" href="#toc-entry-73"><tt class="docutils literal">meta</tt></a></h2>
<p>The <tt class="docutils literal">meta</tt> element is a container for "hidden" document
bibliographic data, or meta-data (data about the document).
It corresponds to HTML META tags.</p>
<p>See also the <a class="reference internal" href="#docinfo">docinfo</a> element for displayed meta-data.
The document's <a class="reference internal" href="#title-attribute">title attribute</a> stores the metadate document title.</p>
<div class="section" id="details-42">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-subelements">Structural Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">meta</tt> is analogous to the HTML "meta" element
or the file properties in ODT or PDF documents.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">The <tt class="docutils literal">meta</tt> element is stored as metadata if the export format
supports this. It is typically invisible and may be omitted from
the processed output.</p>
<p>Meta-data may also be extracted from <a class="reference internal" href="#docinfo">docinfo</a> children
or the <a class="reference internal" href="#document">document</a> attributes (title).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#document">document</a> element contains <tt class="docutils literal">meta</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first last">None.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="example">
<h3>Example</h3>
<p>The <a class="reference external" href="rst/directives.html#meta">"meta" directive</a> is used to create a <tt class="docutils literal">meta</tt> element.
<a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
.. meta::
:description lang=en: An amusing story
:description lang=fr: Un histoire amusant
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<meta content="An amusing story" lang="en" name="description">
<meta content="Un histoire amusant" lang="fr" name="description">
</pre>
</div>
</div>
<div class="section" id="note">
<h2><a class="toc-backref" href="#toc-entry-74"><tt class="docutils literal">note</tt></a></h2>
<p>The <tt class="docutils literal">note</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>,
<a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#warning">warning</a>, and the generic
<a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-43">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">note</tt> is analogous to the <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/note.html">DocBook "note"</a> element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Note" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">note</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">note</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">note</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">note</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly
includes <tt class="docutils literal">note</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-40">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Note:: Admonitions can be handy to break up a
long boring technical document.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<note>
<paragraph>
Admonitions can be handy to break up a
long boring technical document.
</pre>
</div>
</div>
<div class="section" id="option">
<h2><a class="toc-backref" href="#toc-entry-75"><tt class="docutils literal">option</tt></a></h2>
<p>The <tt class="docutils literal">option</tt> element groups an option string together with zero or
more option argument placeholders. Note that <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>
currently supports only one argument per option.</p>
<div class="section" id="details-44">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">option</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#option-list">option_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#option-group">option_group</a> element contains <tt class="docutils literal">option</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first">Each <tt class="docutils literal">option</tt> element contains one <a class="reference internal" href="#option-string">option_string</a> and zero or
more <a class="reference internal" href="#option-argument">option_argument</a> elements.</p>
<pre class="literal-block">
(option_string, option_argument*)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">option</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-41">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#option-list">option_list</a> element.</p>
</div>
</div>
<div class="section" id="option-argument">
<h2><a class="toc-backref" href="#toc-entry-76"><tt class="docutils literal">option_argument</tt></a></h2>
<p>The <tt class="docutils literal">option_argument</tt> element contains placeholder text for option
arguments.</p>
<div class="section" id="details-45">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_argument</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">The value of the "delimiter" attribute is prefixed to the
<tt class="docutils literal">option_argument</tt>, separating it from its <a class="reference internal" href="#option-string">option_string</a> or a
preceding <tt class="docutils literal">option_argument</tt>. The <tt class="docutils literal">option_argument</tt> text is
typically rendered in a monospaced typeface, possibly italicized
or otherwise altered to indicate its placeholder nature.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#option">option</a> element contains <tt class="docutils literal">option_argument</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_argument</tt> elements contain text data only.</p>
<pre class="literal-block">
(#PCDATA)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">option_argument</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#delimiter">delimiter</a>.</p>
<p class="last"><tt class="docutils literal">delimiter</tt> contains the text preceding the <tt class="docutils literal">option_argument</tt>:
either the text separating it from the <a class="reference internal" href="#option-string">option_string</a> (typically
either "=" or " ") or the text between option arguments (typically
either "," or " ").</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-42">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#option-list">option_list</a> element.</p>
</div>
</div>
<div class="section" id="option-group">
<h2><a class="toc-backref" href="#toc-entry-77"><tt class="docutils literal">option_group</tt></a></h2>
<p>The <tt class="docutils literal">option_group</tt> element groups together one or more <a class="reference internal" href="#option">option</a>
elements, all synonyms.</p>
<div class="section" id="details-46">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_group</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Typically <a class="reference internal" href="#option">option</a> elements within an <tt class="docutils literal">option_group</tt> are joined
together in a comma-separated list.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#option-list-item">option_list_item</a> element contains <tt class="docutils literal">option_group</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_group</tt> elements contain one or more <a class="reference internal" href="#option">option</a> elements.</p>
<pre class="literal-block">
(option+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">option_group</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-43">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#option-list">option_list</a> element.</p>
</div>
</div>
<div class="section" id="option-list">
<h2><a class="toc-backref" href="#toc-entry-78"><tt class="docutils literal">option_list</tt></a></h2>
<p>Each <tt class="docutils literal">option_list</tt> element contains a two-column list of
command-line options and descriptions, documenting a program's
options.</p>
<div class="section" id="details-47">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_list</tt> has no direct analogues in common DTDs. It can be
emulated with primitives such as tables.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">An <tt class="docutils literal">option_list</tt> is typically rendered as a two-column list,
where the first column contains option strings and arguments, and
the second column contains descriptions.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">option_list</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_list</tt> elements contain one or more <a class="reference internal" href="#option-list-item">option_list_item</a>
elements.</p>
<pre class="literal-block">
(option_list_item+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">option_list</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">option_list</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">option_list</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-44">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
-a command-line option "a"
-1 file, --one=file, --two file
Multiple options with arguments.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<option_list>
<option_list_item>
<option_group>
<option>
<option_string>
-a
<description>
<paragraph>
command-line option "a"
<option_list_item>
<option_group>
<option>
<option_string>
-1
<option_argument delimiter=" ">
file
<option>
<option_string>
--one
<option_argument delimiter="=">
file
<option>
<option_string>
--two
<option_argument delimiter=" ">
file
<description>
<paragraph>
Multiple options with arguments.
</pre>
</div>
</div>
<div class="section" id="option-list-item">
<h2><a class="toc-backref" href="#toc-entry-79"><tt class="docutils literal">option_list_item</tt></a></h2>
<p>The <tt class="docutils literal">option_list_item</tt> element is a container for a pair of
<a class="reference internal" href="#option-group">option_group</a> and <a class="reference internal" href="#description">description</a> elements.</p>
<div class="section" id="details-48">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_list_item</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#option-list">option_list</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#option-list">option_list</a> element contains <tt class="docutils literal">option_list_item</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first">Each <tt class="docutils literal">option_list_item</tt> element contains one <a class="reference internal" href="#option-group">option_group</a> and
one <a class="reference internal" href="#description">description</a> element.</p>
<pre class="literal-block">
(option_group, description)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">option_list_item</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-45">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#option-list">option_list</a> element.</p>
</div>
</div>
<div class="section" id="option-string">
<h2><a class="toc-backref" href="#toc-entry-80"><tt class="docutils literal">option_string</tt></a></h2>
<p>The <tt class="docutils literal">option_string</tt> element contains the text of a command-line
option.</p>
<div class="section" id="details-49">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_string</tt> has no direct analogues in common DTDs.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">The <tt class="docutils literal">option_string</tt> text is typically rendered in a monospaced
typeface.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#option">option</a> element contains <tt class="docutils literal">option_string</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">option_string</tt> elements contain text data only.</p>
<pre class="literal-block">
(#PCDATA)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">option_string</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-46">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#option-list">option_list</a> element.</p>
</div>
</div>
<div class="section" id="organization">
<h2><a class="toc-backref" href="#toc-entry-81"><tt class="docutils literal">organization</tt></a></h2>
<p>The <tt class="docutils literal">organization</tt> element contains the name of document author's
organization, or the organization responsible for the document.</p>
<div class="section" id="details-50">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">organization</tt> is analogous to the DocBook "orgname",
"corpname", or "publishername" elements.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">organization</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">organization</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">organization</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">organization</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-47">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Organization: Humankind
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<organization>
Humankind
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="paragraph">
<h2><a class="toc-backref" href="#toc-entry-82"><tt class="docutils literal">paragraph</tt></a></h2>
<p>The <tt class="docutils literal">paragraph</tt> element contains the text and inline elements of a
single paragraph, a fundamental building block of documents.</p>
<div class="section" id="details-51">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#simple-body-elements">Simple Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">paragraph</tt> is analogous to the HTML "p" element and to the
DocBook "para" elements.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">paragraph</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">paragraph</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">paragraph</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">paragraph</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">paragraph</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-48">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
A paragraph.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<paragraph>
A paragraph.
</pre>
</div>
</div>
<div class="section" id="pending">
<h2><a class="toc-backref" href="#toc-entry-83"><tt class="docutils literal">pending</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="problematic">
<h2><a class="toc-backref" href="#toc-entry-84"><tt class="docutils literal">problematic</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="raw">
<h2><a class="toc-backref" href="#toc-entry-85"><tt class="docutils literal">raw</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="reference">
<h2><a class="toc-backref" href="#toc-entry-86"><tt class="docutils literal">reference</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="revision">
<h2><a class="toc-backref" href="#toc-entry-87"><tt class="docutils literal">revision</tt></a></h2>
<p>The <tt class="docutils literal">revision</tt> element contains the revision number of the document.
It can be used alone or in conjunction with <a class="reference internal" href="#version">version</a>.</p>
<div class="section" id="details-52">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">revision</tt> is analogous to but simpler than the DocBook
"revision" element. It closely matches the DocBook "revnumber"
element, but in a simpler context.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Often used with the RCS/CVS keyword "Revision". See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">revision</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">revision</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">revision</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">revision</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-49">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Version: 1
:Revision: b
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1
<revision>
b
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="row">
<h2><a class="toc-backref" href="#toc-entry-88"><tt class="docutils literal">row</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="rubric">
<h2><a class="toc-backref" href="#toc-entry-89"><tt class="docutils literal">rubric</tt></a></h2>
<blockquote>
<p>rubric n. 1. a title, heading, or the like, in a manuscript,
book, statute, etc., written or printed in red or otherwise
distinguished from the rest of the text. ...</p>
<p class="attribution">—Random House Webster's College Dictionary, 1991</p>
</blockquote>
<p>A rubric is like an informal heading that doesn't correspond to the
document's structure.</p>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="section">
<h2><a class="toc-backref" href="#toc-entry-90"><tt class="docutils literal">section</tt></a></h2>
<p>The <tt class="docutils literal">section</tt> element is the main unit of hierarchy for Docutils
documents. Docutils <tt class="docutils literal">section</tt> elements are a recursive structure; a
<tt class="docutils literal">section</tt> may contain other <tt class="docutils literal">section</tt> elements, without limit.
Paragraphs and other body elements may occur before a <tt class="docutils literal">section</tt>, but
not after it.</p>
<div class="section" id="details-53">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-elements">Structural Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">section</tt> is analogous to the recursive "section" elements in
DocBook and HTML5.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">section</tt>: <a class="reference internal" href="#document">document</a>,
<a class="reference internal" href="#section">section</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">section</tt> elements begin with a <a class="reference internal" href="#title">title</a>, and may contain <a class="reference internal" href="#body-elements">body
elements</a> as well as <a class="reference internal" href="#transition">transition</a>, <a class="reference internal" href="#topic">topic</a>, and <a class="reference internal" href="#sidebar">sidebar</a> elements.</p>
<pre class="literal-block">
(<a class="reference internal" href="#title">title</a>, <a class="reference internal" href="#structure-model">%structure.model;</a>)
</pre>
<p>See the <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity for details of the body
of a <tt class="docutils literal">section</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">section</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#section-elements">%section.elements;</a> parameter entity directly includes
<tt class="docutils literal">section</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly
includes <tt class="docutils literal">section</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-50">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Title 1
=======
Paragraph 1.
Title 2
-------
Paragraph 2.
Title 3
=======
Paragraph 3.
Title 4
-------
Paragraph 4.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing:</p>
<pre class="literal-block">
<document>
<section ids="title-1" names="title 1">
<title>
Title 1
<paragraph>
Paragraph 1.
<section ids="title-2" names="title 2">
<title>
Title 2
<paragraph>
Paragraph 2.
<section ids="title-3" names="title 3">
<title>
Title 3
<paragraph>
Paragraph 3.
<section ids="title-4" names="title 4">
<title>
Title 4
<paragraph>
Paragraph 4.
</pre>
</div>
</div>
<div class="section" id="sidebar">
<h2><a class="toc-backref" href="#toc-entry-91"><tt class="docutils literal">sidebar</tt></a></h2>
<p>Sidebars are like miniature, parallel documents that occur inside
other documents, providing related or reference material. A
<tt class="docutils literal">sidebar</tt> is typically offset by a border and "floats" to the side
of the page; the document's main text may flow around it. Sidebars
can also be likened to super-footnotes; their content is outside of
the flow of the document's main text.</p>
<p>The <tt class="docutils literal">sidebar</tt> element is a nonrecursive <a class="reference internal" href="#section">section</a>-like construct
which may occur at the top level of a <a class="reference internal" href="#section">section</a> wherever a body element
(list, table, etc.) is allowed. In other words, <tt class="docutils literal">sidebar</tt> elements
cannot nest inside body elements, so you can't have a <tt class="docutils literal">sidebar</tt>
inside a <tt class="docutils literal">table</tt> or a <tt class="docutils literal">list</tt>, or inside another <tt class="docutils literal">sidebar</tt> (or
<a class="reference internal" href="#topic">topic</a>).</p>
<div class="section" id="details-54">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-elements">Structural Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">sidebar</tt> is analogous to the DocBook "sidebar" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">A <tt class="docutils literal">sidebar</tt> element should be set off from the rest of the
document somehow, typically with a border. Sidebars typically
"float" to the side of the page and the document's main text flows
around them.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">sidebar</tt>: <a class="reference internal" href="#document">document</a>,
<a class="reference internal" href="#section">section</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">sidebar</tt> elements begin with optional <a class="reference internal" href="#title">title</a> and <a class="reference internal" href="#subtitle">subtitle</a>
and contain <a class="reference internal" href="#body-elements">body elements</a> and <a class="reference internal" href="#topic">topic</a> elements.</p>
<pre class="literal-block">
(title, subtitle?,
(<a class="reference internal" href="#body-elements-1">%body.elements;</a> | topic)+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">sidebar</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity directly includes
<tt class="docutils literal">sidebar</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-51">
<h3>Examples</h3>
<p>The <a class="reference external" href="rst/directives.html#sidebar">"sidebar" directive</a> is used to create a <tt class="docutils literal">sidebar</tt> element.
<a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
.. sidebar:: Optional Title
:subtitle: If Desired
Body.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<sidebar>
<title>
Optional Title
<subtitle>
If Desired
<paragraph>
Body.
</pre>
</div>
</div>
<div class="section" id="status">
<h2><a class="toc-backref" href="#toc-entry-92"><tt class="docutils literal">status</tt></a></h2>
<p>The <tt class="docutils literal">status</tt> element contains a status statement for the document,
such as "Draft", "Final", "Work In Progress", etc.</p>
<div class="section" id="details-55">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">status</tt> is analogous to the DocBook "status" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#docinfo">docinfo</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">status</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">status</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">status</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">status</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-52">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Status: Work In Progress
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<status>
Work In Progress
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="strong">
<h2><a class="toc-backref" href="#toc-entry-93"><tt class="docutils literal">strong</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="subscript">
<h2><a class="toc-backref" href="#toc-entry-94"><tt class="docutils literal">subscript</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="substitution-definition">
<h2><a class="toc-backref" href="#toc-entry-95"><tt class="docutils literal">substitution_definition</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="substitution-reference">
<h2><a class="toc-backref" href="#toc-entry-96"><tt class="docutils literal">substitution_reference</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="subtitle">
<h2><a class="toc-backref" href="#toc-entry-97"><tt class="docutils literal">subtitle</tt></a></h2>
<p>The <tt class="docutils literal">subtitle</tt> element stores the subtitle of a <a class="reference internal" href="#document">document</a>.</p>
<div class="section" id="details-56">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-subelements">Structural Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">subtitle</tt> is analogous to HTML header elements ("h2" etc.) and
to the DocBook "subtitle" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">A document's subtitle is usually rendered smaller than its <a class="reference internal" href="#title">title</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The <a class="reference internal" href="#document">document</a> and <a class="reference internal" href="#sidebar">sidebar</a> elements may contain <tt class="docutils literal">subtitle</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">subtitle</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">subtitle</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-53">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
=======
Title
=======
----------
Subtitle
----------
A paragraph.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="title" names="title">
<title>
Title
<subtitle ids="subtitle" names="subtitle">
Subtitle
<paragraph>
A paragraph.
</pre>
<p>Note how two section levels have collapsed, promoting their titles to
become the document's title and subtitle. Since there is only one
structural element (document), the subsection's <tt class="docutils literal">ids</tt> and <tt class="docutils literal">names</tt>
attributes are stored in the <tt class="docutils literal">subtitle</tt> element.</p>
</div>
</div>
<div class="section" id="superscript">
<h2><a class="toc-backref" href="#toc-entry-98"><tt class="docutils literal">superscript</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="system-message">
<h2><a class="toc-backref" href="#toc-entry-99"><tt class="docutils literal">system_message</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="table">
<h2><a class="toc-backref" href="#toc-entry-100"><tt class="docutils literal">table</tt></a></h2>
<p>The <tt class="docutils literal">table</tt> element identifies a data arrangement with rows and columns.</p>
<p>Docutils tables are based on the <cite>Exchange subset of the CALS-table
model</cite> <a class="citation-reference" href="#exchange-table-model" id="citation-reference-2">[exchange-table-model]</a>. <a class="footnote-reference" href="#footnote-1" id="footnote-reference-3">[2]</a></p>
<table class="docutils footnote" frame="void" id="footnote-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-3">[2]</a></td><td>The interpretation of column widths in <a class="reference internal" href="#colspec">colspec</a> differs from the
specification.</td></tr>
</tbody>
</table>
<div class="section" id="details-57">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">table</tt> is analogous to the HTML "table" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Content is rendered in rows and columns.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">table</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">table</tt> elements begin with an optional <a class="reference internal" href="#title">title</a> (caption) and may
contain one or more <a class="reference internal" href="#tgroup">tgroup</a> elements.</p>
<pre class="literal-block">
(title?, tgroup+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">table</tt> element contains the attributes frame, colsep, rowsep,
and pgwide defined in the <a class="reference internal" href="#exchange-table-model">exchange-table-model</a>, the
<a class="reference internal" href="#common-attributes">common attributes</a>, <a class="reference internal" href="#align">align</a>, and <a class="reference internal" href="#width">width</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">table</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity
indirectly includes <tt class="docutils literal">table</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-54">
<h3>Examples</h3>
<p>In reStructuredText, tables can specified via the
<a class="reference external" href="rst/directives.html#table">table</a>, <a class="reference external" href="rst/directives.html#csv-table">csv-table</a>, or <a class="reference external" href="rst/directives.html#list-table">list-table</a> directives or directly as
<a class="reference external" href="rst/restructuredtext.html#grid-tables">grid table</a> or <a class="reference external" href="rst/restructuredtext.html#simple-tables">simple table</a>, e.g.</p>
<pre class="literal-block">
======== ====
bread £2
butter £30
======== ====
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<table>
<tgroup cols="2">
<colspec colwidth="8">
<colspec colwidth="4">
<tbody>
<row>
<entry>
<paragraph>
bread
<entry>
<paragraph>
£2
<row>
<entry>
<paragraph>
butter
<entry>
<paragraph>
£30
</pre>
<table class="docutils citation" frame="void" id="exchange-table-model" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[exchange-table-model]</td><td><em>(<a class="fn-backref" href="#citation-reference-1">1</a>, <a class="fn-backref" href="#citation-reference-2">2</a>, <a class="fn-backref" href="#citation-reference-3">3</a>)</em> <cite>XML Exchange Table Model DTD</cite>, OASIS Technical
Memorandum 9901:1999, <a class="reference external" href="http://www.oasis-open.org/html/tm9901.html">http://www.oasis-open.org/html/tm9901.html</a>.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="target">
<h2><a class="toc-backref" href="#toc-entry-101"><tt class="docutils literal">target</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="tbody">
<h2><a class="toc-backref" href="#toc-entry-102"><tt class="docutils literal">tbody</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="term">
<h2><a class="toc-backref" href="#toc-entry-103"><tt class="docutils literal">term</tt></a></h2>
<p>The <tt class="docutils literal">term</tt> element contains a word or phrase being defined in a
<a class="reference internal" href="#definition-list">definition_list</a>.</p>
<div class="section" id="details-58">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#body-subelements">Body Subelements</a> (simple)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">term</tt> is analogous to the HTML "dt" element and to the DocBook
"term" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">See <a class="reference internal" href="#definition-list-item">definition_list_item</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#definition-list-item">definition_list_item</a> element contains <tt class="docutils literal">term</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">term</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first last">The <tt class="docutils literal">term</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-55">
<h3>Examples</h3>
<p>See the examples for the <a class="reference internal" href="#definition-list">definition_list</a>, <a class="reference internal" href="#definition-list-item">definition_list_item</a>, and
<a class="reference internal" href="#classifier">classifier</a> elements.</p>
</div>
</div>
<div class="section" id="tgroup">
<h2><a class="toc-backref" href="#toc-entry-104"><tt class="docutils literal">tgroup</tt></a></h2>
<p>See <a class="citation-reference" href="#exchange-table-model" id="citation-reference-3">[exchange-table-model]</a>.
.. parsed-literal:</p>
<pre class="literal-block">
(colspec_\*, thead_\?, tbody_)
</pre>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="thead">
<h2><a class="toc-backref" href="#toc-entry-105"><tt class="docutils literal">thead</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="tip">
<h2><a class="toc-backref" href="#toc-entry-106"><tt class="docutils literal">tip</tt></a></h2>
<p>The <tt class="docutils literal">tip</tt> element is an admonition, a distinctive and self-contained
notice. Also see the other admonition elements Docutils offers (in
alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>, <a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#hint">hint</a>,
<a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#warning">warning</a>, and the generic <a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-59">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><blockquote class="first">
<p><tt class="docutils literal">tip</tt> is analogous to the <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/tip.html">DocBook "tip"</a> element.</p>
</blockquote>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Tip" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">tip</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">tip</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">tip</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes <tt class="docutils literal">tip</tt>.
The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly includes
<tt class="docutils literal">tip</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-56">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. Tip:: 15% if the service is good.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<tip>
<paragraph>
15% if the service is good.
</pre>
</div>
</div>
<div class="section" id="title-1">
<span id="title"></span><h2><a class="toc-backref" href="#toc-entry-107"><tt class="docutils literal">title</tt></a></h2>
<p>The <tt class="docutils literal">title</tt> element stores the title of a <a class="reference internal" href="#document">document</a>, <a class="reference internal" href="#section">section</a>,
<a class="reference internal" href="#sidebar">sidebar</a>, <a class="reference internal" href="#table">table</a>, <a class="reference internal" href="#topic">topic</a>, or generic <a class="reference internal" href="#admonition">admonition</a>.</p>
<div class="section" id="details-60">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-subelements">Structural Subelements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">title</tt> is analogous to HTML "title" and header ("h1" etc.)
elements, and to the DocBook "title" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">title</tt>: <a class="reference internal" href="#admonition">admonition</a>, <a class="reference internal" href="#document">document</a>,
<a class="reference internal" href="#section">section</a>, <a class="reference internal" href="#sidebar">sidebar</a>, <a class="reference internal" href="#table">table</a>, <a class="reference internal" href="#topic">topic</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">title</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">title</tt> element contains the <a class="reference internal" href="#common-attributes">common attributes</a>
plus <a class="reference internal" href="#refid">refid</a> and <a class="reference internal" href="#auto">auto</a>.</p>
<p><tt class="docutils literal">refid</tt> is used as a backlink to a table of contents entry.</p>
<p class="last"><tt class="docutils literal">auto</tt> is used to indicate (with value "1") that the <tt class="docutils literal">title</tt>
has been numbered automatically.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-57">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
A Title
=======
A paragraph.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
</pre>
</div>
</div>
<div class="section" id="title-reference">
<h2><a class="toc-backref" href="#toc-entry-108"><tt class="docutils literal">title_reference</tt></a></h2>
<p><a class="reference internal" href="#to-be-completed">To be completed</a>.</p>
</div>
<div class="section" id="topic">
<h2><a class="toc-backref" href="#toc-entry-109"><tt class="docutils literal">topic</tt></a></h2>
<p>The <tt class="docutils literal">topic</tt> element is a nonrecursive <a class="reference internal" href="#section">section</a>-like construct which
may occur at the top level of a <a class="reference internal" href="#section">section</a> wherever a body element
(list, table, etc.) is allowed. In other words, <tt class="docutils literal">topic</tt> elements
cannot nest inside body elements, so you can't have a <tt class="docutils literal">topic</tt> inside
a <tt class="docutils literal">table</tt> or a <tt class="docutils literal">list</tt>, or inside another <tt class="docutils literal">topic</tt>.</p>
<div class="section" id="details-61">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#structural-elements">Structural Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">topic</tt> is analogous to the DocBook "simplesect" element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">A <tt class="docutils literal">topic</tt> element should be set off from the rest of the
document somehow, such as with indentation or a border.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">The following elements may contain <tt class="docutils literal">topic</tt>: <a class="reference internal" href="#document">document</a>, <a class="reference internal" href="#section">section</a>,
<a class="reference internal" href="#sidebar">sidebar</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">topic</tt> elements begin with a <a class="reference internal" href="#title">title</a> and may contain <a class="reference internal" href="#body-elements">body
elements</a>.</p>
<pre class="literal-block">
(title?, (<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+)
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">topic</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity directly includes
<tt class="docutils literal">topic</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-58">
<h3>Examples</h3>
<p>The <a class="reference external" href="rst/directives.html#topic">"topic" directive</a> is used to create a <tt class="docutils literal">topic</tt> element.
<a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
.. topic:: Title
Body.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<topic>
<title>
Title
<paragraph>
Body.
</pre>
</div>
</div>
<div class="section" id="transition">
<h2><a class="toc-backref" href="#toc-entry-110"><tt class="docutils literal">transition</tt></a></h2>
<p>The <tt class="docutils literal">transition</tt> element is commonly seen in novels and short
fiction, as a gap spanning one or more lines, with or without a type
ornament such as a row of asterisks. Transitions separate body
elements and sections, dividing a section into untitled divisions. A
transition may not begin or end a section <a class="footnote-reference" href="#footnote-2" id="footnote-reference-4">[3]</a> or document, nor may
two transitions be immediately adjacent.</p>
<p>See <a class="reference external" href="../dev/rst/alternatives.html#doctree-representation-of-transitions">Doctree Representation of Transitions</a> in <a class="reference external" href="../dev/rst/alternatives.html">A Record of
reStructuredText Syntax Alternatives</a>.</p>
<table class="docutils footnote" frame="void" id="footnote-2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-4">[3]</a></td><td>In reStructuredText markup, a transition may appear to fall at
the end of a section immediately before another section. A
transform recognizes this case and moves the transition so it
separates the sections.</td></tr>
</tbody>
</table>
<div class="section" id="details-62">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><a class="reference internal" href="#structural-subelements">Structural Subelements</a></td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><tt class="docutils literal">transition</tt> is analogous to the HTML "hr" element.</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body">The <tt class="docutils literal">transition</tt> element is typically rendered as vertical
whitespace (more than that separating paragraphs), with or without
a horizontal line or row of asterisks. In novels, transitions are
often represented as a row of three well-spaced asterisks with
vertical space above and below.</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body">The following elements may contain <tt class="docutils literal">transition</tt>: <a class="reference internal" href="#document">document</a>,
<a class="reference internal" href="#section">section</a></td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body">The <tt class="docutils literal">transition</tt> element has no content.</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body">The <tt class="docutils literal">transition</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body">The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity directly includes
<tt class="docutils literal">transition</tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-59">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Paragraph 1.
--------
Paragraph 2.
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing:</p>
<pre class="literal-block">
<document>
<paragraph>
Paragraph 1.
<transition>
<paragraph>
Paragraph 2.
</pre>
</div>
</div>
<div class="section" id="version">
<h2><a class="toc-backref" href="#toc-entry-111"><tt class="docutils literal">version</tt></a></h2>
<p>The <tt class="docutils literal">version</tt> element contains the version number of the document.
It can be used alone or in conjunction with <a class="reference internal" href="#revision">revision</a>.</p>
<div class="section" id="details-63">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#bibliographic-elements">Bibliographic Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">version</tt> may be considered analogous to the DocBook "revision",
"revnumber", or "biblioid" elements.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Sometimes used with the RCS/CVS keyword "Revision". See <a class="reference internal" href="#docinfo">docinfo</a>
and <a class="reference internal" href="#revision">revision</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">Only the <a class="reference internal" href="#docinfo">docinfo</a> element contains <tt class="docutils literal">version</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">version</tt> elements may contain text data plus <a class="reference internal" href="#inline-elements">inline
elements</a>.</p>
<pre class="literal-block">
<a class="reference internal" href="#text-model">%text.model;</a>
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">version</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#bibliographic-elements-1">%bibliographic.elements;</a> parameter entity directly includes
<tt class="docutils literal">version</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-60">
<h3>Examples</h3>
<p><a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source:</p>
<pre class="literal-block">
Document Title
==============
:Version: 1.1
</pre>
<p>Complete <a class="reference internal" href="#pseudo-xml">pseudo-XML</a> result after parsing and applying transforms:</p>
<pre class="literal-block">
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1.1
</pre>
<p>See <a class="reference internal" href="#docinfo">docinfo</a> for a more complete example, including processing
context.</p>
</div>
</div>
<div class="section" id="warning">
<h2><a class="toc-backref" href="#toc-entry-112"><tt class="docutils literal">warning</tt></a></h2>
<p>The <tt class="docutils literal">warning</tt> element is an admonition, a distinctive and
self-contained notice. Also see the other admonition elements
Docutils offers (in alphabetical order): <a class="reference internal" href="#attention">attention</a>, <a class="reference internal" href="#caution">caution</a>,
<a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#tip">tip</a>.</p>
<div class="section" id="details-64">
<h3>Details</h3>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Category:</th><td class="field-body"><p class="first"><a class="reference internal" href="#compound-body-elements">Compound Body Elements</a></p>
</td>
</tr>
<tr class="field"><th class="field-name">Analogues:</th><td class="field-body"><p class="first"><tt class="docutils literal">warning</tt> is analogous to the <a class="reference external" href="https://tdg.docbook.org/tdg/5.1/warning.html">DocBook "warning"</a> element.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Processing:</th><td class="field-body"><p class="first">Rendered distinctly (inset and/or in a box, etc.), with the
generated title "Warning" (or similar).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Parents:</th><td class="field-body"><p class="first">All elements employing the <a class="reference internal" href="#body-elements-1">%body.elements;</a> or
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entities in their content models
may contain <tt class="docutils literal">warning</tt>.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Children:</th><td class="field-body"><p class="first"><tt class="docutils literal">warning</tt> elements contain one or more <a class="reference internal" href="#body-elements">body elements</a>.</p>
<pre class="literal-block">
(<a class="reference internal" href="#body-elements-1">%body.elements;</a>)+
</pre>
</td>
</tr>
<tr class="field"><th class="field-name">Attributes:</th><td class="field-body"><p class="first">The <tt class="docutils literal">warning</tt> element contains only the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Parameter Entities:</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">The <a class="reference internal" href="#body-elements-1">%body.elements;</a> parameter entity directly includes
<tt class="docutils literal">warning</tt>. The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity indirectly
includes <tt class="docutils literal">warning</tt>.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="examples-61">
<h3>Examples</h3>
<p>reStructuredText source:</p>
<pre class="literal-block">
.. WARNING:: Reader discretion is strongly advised.
</pre>
<p><a class="reference internal" href="#pseudo-xml">Pseudo-XML</a> fragment from simple parsing:</p>
<pre class="literal-block">
<warning>
<paragraph>
Reader discretion is strongly advised.
</pre>
</div>
</div>
</div>
<div class="section" id="attribute-types">
<span id="attribute-type"></span><h1><a class="toc-backref" href="#toc-entry-3">Attribute types</a></h1>
<div class="contents local topic" id="topic-3">
<ul class="simple">
<li><a class="reference internal" href="#standard-attribute-types" id="toc-entry-113">Standard attribute types</a></li>
<li><a class="reference internal" href="#custom-attribute-types" id="toc-entry-114">Custom attribute types</a></li>
</ul>
</div>
<div class="section" id="standard-attribute-types">
<h2><a class="toc-backref" href="#toc-entry-113">Standard attribute types</a></h2>
<p>Attribute types defined in the <a class="reference external" href="https://www.w3.org/TR/REC-xml/#sec-attribute-types">attribute types</a> section of the
<a class="reference external" href="https://www.w3.org/TR/REC-xml">XML 1.0 specification</a>:</p>
<dl class="docutils">
<dt><span class="target" id="cdata">CDATA</span></dt>
<dd>Character data. CDATA attributes may contain arbitrary text.</dd>
<dt><span class="target" id="nmtoken">NMTOKEN</span></dt>
<dd>A "name token". One or more of letters, digits, ".", "-", and
"_".</dd>
<dt><span class="target" id="nmtokens">NMTOKENS</span></dt>
<dd>One or more space-separated NMTOKEN values.</dd>
<dt><span class="target" id="enumeratedtype">EnumeratedType</span></dt>
<dd>The attribute value may be one of a specified list of values.</dd>
</dl>
<p>Docutils uses <a class="reference internal" href="#custom-attribute-types">custom attribute types</a> instead of the ID, IDREF, and IDREFS
standard types, because it does not adhere to the <a class="reference external" href="https://www.w3.org/TR/REC-xml/#one-id-per-el">One ID per Element Type</a>
validity constraint.</p>
</div>
<div class="section" id="custom-attribute-types">
<h2><a class="toc-backref" href="#toc-entry-114">Custom attribute types</a></h2>
<p>The Docutils DTD defines <a class="reference external" href="https://www.w3.org/TR/REC-xml/#dt-PE">parameter entities</a> that resolve to standard
attribute types to highlight specific attribute value constraints.</p>
<dl class="docutils">
<dt><span class="target" id="yesorno">yesorno</span></dt>
<dd><p class="first">Boolean: no if zero ("0"), yes if any other value.
Resolves to <tt class="docutils literal">NMTOKEN</tt>.</p>
<p class="last">Used in the <a class="reference internal" href="#anonymous">anonymous</a> and <a class="reference internal" href="#stub">stub</a> attributes.</p>
</dd>
<dt><span class="target" id="number">number</span></dt>
<dd><p class="first">The attribute value must be a number. Resolves to <tt class="docutils literal">NMTOKEN</tt>.</p>
<p class="last">Used in the <a class="reference internal" href="#level">level</a>, <a class="reference internal" href="#morecols">morecols</a>, <a class="reference internal" href="#scale">scale</a>, and <a class="reference internal" href="#start">start</a> attributes.</p>
</dd>
<dt><span class="target" id="measure">measure</span></dt>
<dd><p class="first">A number which may be immediately followed by a unit or percent sign.
Resolves to CDATA.</p>
<p class="last">Used in the <a class="reference internal" href="#height">height</a> and <a class="reference internal" href="#width">width</a> attributes.</p>
</dd>
<dt><span class="target" id="classnames-type">classnames.type</span></dt>
<dd><p class="first">A space-separated list of <cite>class names</cite> <a class="footnote-reference" href="#classname" id="footnote-reference-5">[4]</a>. Resolves to NMTOKEN.</p>
<p class="last">Used in the <a class="reference internal" href="#classes">classes</a> attribute.</p>
</dd>
<dt><span class="target" id="refname-type">refname.type</span></dt>
<dd><p class="first">A <a class="reference external" href="rst/restructuredtext.html#normalized-reference-names">normalized</a> <a class="reference external" href="rst/restructuredtext.html#reference-names">reference name</a>. Resolves to CDATA (in contrast to
NMTOKENS, <a class="reference external" href="rst/restructuredtext.html#reference-names">reference names</a> may consist of any text).</p>
<p class="last">Used in the <a class="reference internal" href="#refname">refname</a> attribute.</p>
</dd>
<dt><span class="target" id="refnames-type">refnames.type</span></dt>
<dd><p class="first">A space-separated list of <a class="reference external" href="rst/restructuredtext.html#reference-names">reference names</a>. Resolves to CDATA.</p>
<p><a class="reference external" href="rst/restructuredtext.html#escaping-mechanism">Backslash escaping</a> is used for space characters inside a <cite>reference
name</cite>.</p>
<p class="last">Used in the <a class="reference internal" href="#names">names</a> and <a class="reference internal" href="#dupnames">dupnames</a> attributes.</p>
</dd>
<dt><span class="target" id="ids-type">ids.type</span></dt>
<dd><p class="first">A space-separated list of unique <cite>identifier keys</cite> <a class="footnote-reference" href="#identifier" id="footnote-reference-6">[5]</a>.
Resolves to NMTOKENS (the XML <a class="reference internal" href="#standard-attribute-types">standard attribute types</a> do not provide
for a list of IDs).</p>
<p class="last">Used in the <a class="reference internal" href="#ids">ids</a> attribute.</p>
</dd>
<dt><span class="target" id="idref-type">idref.type</span></dt>
<dd><p class="first">A reference to an <a class="reference internal" href="#identifier-key">identifier key</a>.
Resolves to NMTOKEN (Docutils identifier keys do not use the ID standard
type as required by the <a class="reference external" href="https://www.w3.org/TR/REC-xml/#idref">IDREF Validity constraint</a>).</p>
<p class="last">Used in the <a class="reference internal" href="#refid">refid</a> attribute.</p>
</dd>
<dt><span class="target" id="idrefs-type">idrefs.type</span></dt>
<dd><p class="first">A list of references to element identifiers.
Resolves to NMTOKENS.</p>
<p class="last">Used in the <a class="reference internal" href="#backrefs">backrefs</a> attribute.</p>
</dd>
</dl>
<span class="target" id="class-names"></span><table class="docutils footnote" frame="void" id="classname" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-5">[4]</a></td><td><p class="first"><cite>Class names</cite> define sub-classes of existing elements.</p>
<p class="last">In reStructuredText, custom <cite>class names</cite> can be specified using
the <a class="reference external" href="rst/directives.html#class">"class" directive</a>, a directive's <a class="reference external" href="rst/directives.html#class-option">:class: option</a>, or
<a class="reference external" href="rst/directives.html#custom-interpreted-text-roles">custom interpreted text roles</a>.
Docutils normalizes them to conform to both, HTML4.1 and CSS1.0 <cite>name</cite>
requirements (the regular expression <tt class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></tt>) via the
<a class="reference external" href="rst/directives.html#identifier-normalization">identifier normalization</a>.</p>
</td></tr>
</tbody>
</table>
<span class="target" id="identifier-keys"><span id="identifier-key"></span><span id="identifiers"></span></span><table class="docutils footnote" frame="void" id="identifier" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#footnote-reference-6">[5]</a></td><td><p class="first"><cite>Identifier keys</cite> are used for cross references in
generated documents. Therefore, they must comply with restrictions in the
respective output formats (<a class="reference external" href="https://www.w3.org/TR/html401/types.html#type-name">HTML4.1</a>, <a class="reference external" href="https://www.w3.org/TR/html50/dom.html#the-id-attribute">HTML5</a>, <a class="reference external" href="https://www.w3.org/TR/html-polyglot/#id-attribute">polyglot HTML</a>,
<a class="reference external" href="https://tex.stackexchange.com/questions/18311/what-are-the-valid-names-as-labels">LaTeX</a>, <a class="reference external" href="https://help.libreoffice.org/6.3/en-US/text/swriter/01/04040000.html?DbPAR=WRITER#bm_id4974211">ODT</a>, troff (manpage), <a class="reference external" href="https://www.w3.org/TR/REC-xml/#id">XML</a>).</p>
<p>Identifier keys cannot be specified directly in reStructuredText.
Docutils generates them by applying the <a class="reference external" href="rst/directives.html#identifier-normalization">identifier normalization</a> to
<a class="reference external" href="rst/restructuredtext.html#reference-names">reference names</a> or from the <a class="reference external" href="../user/config.html#auto-id-prefix">auto_id_prefix</a>, prepending the <a class="reference external" href="../user/config.html#id-prefix">id_prefix</a>
and potentially appending numbers for disambiguation.</p>
</td></tr>
</tbody>
</table>
<!-- .. _ID attribute type: https://www.w3.org/TR/REC-xml/#id -->
</div>
</div>
<div class="section" id="attribute-reference">
<h1><a class="toc-backref" href="#toc-entry-4">Attribute Reference</a></h1>
<div class="contents local topic" id="topic-4">
<ul class="simple">
<li><a class="reference internal" href="#align" id="toc-entry-115"><tt class="docutils literal">align</tt></a></li>
<li><a class="reference internal" href="#anonymous" id="toc-entry-116"><tt class="docutils literal">anonymous</tt></a></li>
<li><a class="reference internal" href="#auto" id="toc-entry-117"><tt class="docutils literal">auto</tt></a></li>
<li><a class="reference internal" href="#backrefs" id="toc-entry-118"><tt class="docutils literal">backrefs</tt></a></li>
<li><a class="reference internal" href="#bullet" id="toc-entry-119"><tt class="docutils literal">bullet</tt></a></li>
<li><a class="reference internal" href="#classes" id="toc-entry-120"><tt class="docutils literal">classes</tt></a></li>
<li><a class="reference internal" href="#colwidth" id="toc-entry-121"><tt class="docutils literal">colwidth</tt></a></li>
<li><a class="reference internal" href="#delimiter" id="toc-entry-122"><tt class="docutils literal">delimiter</tt></a></li>
<li><a class="reference internal" href="#dupnames" id="toc-entry-123"><tt class="docutils literal">dupnames</tt></a></li>
<li><a class="reference internal" href="#enumtype" id="toc-entry-124"><tt class="docutils literal">enumtype</tt></a></li>
<li><a class="reference internal" href="#height" id="toc-entry-125"><tt class="docutils literal">height</tt></a></li>
<li><a class="reference internal" href="#ids" id="toc-entry-126"><tt class="docutils literal">ids</tt></a></li>
<li><a class="reference internal" href="#level" id="toc-entry-127"><tt class="docutils literal">level</tt></a></li>
<li><a class="reference internal" href="#morecols" id="toc-entry-128"><tt class="docutils literal">morecols</tt></a></li>
<li><a class="reference internal" href="#names" id="toc-entry-129"><tt class="docutils literal">names</tt></a></li>
<li><a class="reference internal" href="#prefix" id="toc-entry-130"><tt class="docutils literal">prefix</tt></a></li>
<li><a class="reference internal" href="#refid" id="toc-entry-131"><tt class="docutils literal">refid</tt></a></li>
<li><a class="reference internal" href="#refname" id="toc-entry-132"><tt class="docutils literal">refname</tt></a></li>
<li><a class="reference internal" href="#refuri" id="toc-entry-133"><tt class="docutils literal">refuri</tt></a></li>
<li><a class="reference internal" href="#scale" id="toc-entry-134"><tt class="docutils literal">scale</tt></a></li>
<li><a class="reference internal" href="#source" id="toc-entry-135"><tt class="docutils literal">source</tt></a></li>
<li><a class="reference internal" href="#start" id="toc-entry-136"><tt class="docutils literal">start</tt></a></li>
<li><a class="reference internal" href="#stub" id="toc-entry-137"><tt class="docutils literal">stub</tt></a></li>
<li><a class="reference internal" href="#suffix" id="toc-entry-138"><tt class="docutils literal">suffix</tt></a></li>
<li><a class="reference internal" href="#title-2" id="toc-entry-139"><tt class="docutils literal">title</tt></a></li>
<li><a class="reference internal" href="#width" id="toc-entry-140"><tt class="docutils literal">width</tt></a></li>
<li><a class="reference internal" href="#xml-space" id="toc-entry-141"><tt class="docutils literal">xml:space</tt></a></li>
</ul>
</div>
<dl class="docutils">
<dt><span class="target" id="common-attributes">Common Attributes</span>:</dt>
<dd>Through the <a class="reference internal" href="#basic-atts">%basic.atts;</a> parameter entity, all elements support
the following attributes: <a class="reference internal" href="#ids">ids</a>, <a class="reference internal" href="#names">names</a> or <a class="reference internal" href="#dupnames">dupnames</a>, <a class="reference internal" href="#source">source</a>, and
<a class="reference internal" href="#classes">classes</a>.</dd>
</dl>
<div class="section" id="align">
<h2><a class="toc-backref" href="#toc-entry-115"><tt class="docutils literal">align</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none (inherit).</p>
<p>The <tt class="docutils literal">align</tt> attribute is used in the <a class="reference internal" href="#figure">figure</a>, <a class="reference internal" href="#image">image</a>, and <a class="reference internal" href="#table">table</a> elements
(via the <a class="reference internal" href="#align-h-att">%align-h.att;</a> and <a class="reference internal" href="#align-hv-att">%align-hv.att;</a> parameter entities).</p>
</div>
<div class="section" id="anonymous">
<h2><a class="toc-backref" href="#toc-entry-116"><tt class="docutils literal">anonymous</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#yesorno">yesorno</a>. Default value: none (implies no).</p>
<p>The <tt class="docutils literal">anonymous</tt> attribute is used for unnamed hyperlinks in the
<a class="reference internal" href="#target">target</a> and <a class="reference internal" href="#reference">reference</a> elements (via the <a class="reference internal" href="#anonymous-att">%anonymous.att;</a> parameter
entity).</p>
</div>
<div class="section" id="auto">
<h2><a class="toc-backref" href="#toc-entry-117"><tt class="docutils literal">auto</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">auto</tt> attribute is used to indicate automatically-numbered
<a class="reference internal" href="#footnote">footnote</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a> and <a class="reference internal" href="#title">title</a> elements (via the
<a class="reference internal" href="#auto-att">%auto.att;</a> parameter entity).</p>
</div>
<div class="section" id="backrefs">
<h2><a class="toc-backref" href="#toc-entry-118"><tt class="docutils literal">backrefs</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#idrefs-type">idrefs.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">backrefs</tt> attribute contains a space-separated list of <a class="reference internal" href="#identifier">identifier</a>
references, used for backlinks from <a class="reference internal" href="#footnote">footnote</a>, <a class="reference internal" href="#citation">citation</a>, and
<a class="reference internal" href="#system-message">system_message</a> elements (via the <a class="reference internal" href="#backrefs-att">%backrefs.att;</a> parameter entity).</p>
</div>
<div class="section" id="bullet">
<h2><a class="toc-backref" href="#toc-entry-119"><tt class="docutils literal">bullet</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">bullet</tt> attribute is used in the <a class="reference internal" href="#bullet-list">bullet_list</a> element.</p>
</div>
<div class="section" id="classes">
<h2><a class="toc-backref" href="#toc-entry-120"><tt class="docutils literal">classes</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#classnames-type">classnames.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">classes</tt> attribute is a space separated list containing zero or more
<a class="reference internal" href="#class-names">class names</a>.</p>
<p>The purpose of the attribute is to indicate an "is-a" variant relationship,
to allow an extensible way of defining sub-classes of existing elements. It
can be used to carry context forward between a Docutils Reader and Writer,
when a custom structure is reduced to a standardized document tree. One
common use is in conjunction with stylesheets, to add selection criteria.
It should not be used to carry formatting instructions or arbitrary content.</p>
<p>The <tt class="docutils literal">classes</tt> attribute's contents should be ignorable. Writers that
are not familiar with the variant expressed should be able to ignore
the attribute.</p>
<p><tt class="docutils literal">classes</tt> is one of the <a class="reference internal" href="#common-attributes">common attributes</a>, shared by all Docutils
elements.</p>
</div>
<div class="section" id="colwidth">
<h2><a class="toc-backref" href="#toc-entry-121"><tt class="docutils literal">colwidth</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: "1*"</p>
<p>Column width specification used in the <a class="reference internal" href="#colspec">colspec</a> element.
Defined in the <a class="reference internal" href="#exchange-table-model">exchange-table-model</a>.</p>
<p>Either proportional measure of the form number*, e.g., “5*” for 5 times
the proportion, or “*” (which is equivalent to “1*”); fixed measure,
e.g., 2pt for 2 point, 3pi for 3 pica.</p>
<p>The fixed unit values are case insensitive. The standard list of allowed
unit values is “pt” (points), “cm” (centimeters), “mm” (millimeters),
“pi” (picas), and “in” (inches). The default fixed unit should be
interpreted as “pt” if neither a proportion nor a fixed unit is
specified.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">Currently, Docutils interprets unitless numbers as
proportions.</p>
</div>
</div>
<div class="section" id="delimiter">
<h2><a class="toc-backref" href="#toc-entry-122"><tt class="docutils literal">delimiter</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">delimiter</tt> attribute is used in the <a class="reference internal" href="#option-argument">option_argument</a> element.</p>
</div>
<div class="section" id="dupnames">
<h2><a class="toc-backref" href="#toc-entry-123"><tt class="docutils literal">dupnames</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#refnames-type">refnames.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">dupnames</tt> attribute replaces the <a class="reference internal" href="#names">names</a> attribute
when there has been a naming conflict.
<tt class="docutils literal">dupnames</tt> is one of the <a class="reference internal" href="#common-attributes">common attributes</a>, shared by all
Docutils elements.</p>
</div>
<div class="section" id="enumtype">
<h2><a class="toc-backref" href="#toc-entry-124"><tt class="docutils literal">enumtype</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#enumeratedtype">EnumeratedType</a>, one of "arabic", "loweralpha",
"upperalpha", "lowerroman", or "upperroman". Default value: none.</p>
<p>The <tt class="docutils literal">enumtype</tt> attribute is used in the <a class="reference internal" href="#enumerated-list">enumerated_list</a> element.</p>
</div>
<div class="section" id="height">
<h2><a class="toc-backref" href="#toc-entry-125"><tt class="docutils literal">height</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#measure">measure</a>. Default value: none.</p>
<p>The <tt class="docutils literal">height</tt> attribute is used in the <a class="reference internal" href="#image">image</a> element.</p>
</div>
<div class="section" id="ids">
<h2><a class="toc-backref" href="#toc-entry-126"><tt class="docutils literal">ids</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#ids-type">ids.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">ids</tt> attribute is a space separated list containing one or more
unique <a class="reference internal" href="#identifier-keys">identifier keys</a>, typically assigned by the system.</p>
<p><tt class="docutils literal">ids</tt> is one of the <a class="reference internal" href="#common-attributes">common attributes</a>, shared by all Docutils
elements.</p>
<!-- TODO:
* Use 'id' for primary identifier key?
* Keep additional keys in `ids`
or in the preceding target elements? -->
</div>
<div class="section" id="level">
<h2><a class="toc-backref" href="#toc-entry-127"><tt class="docutils literal">level</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#number">number</a>. Default value: none.</p>
<p>The <tt class="docutils literal">level</tt> attribute is used in the <a class="reference internal" href="#system-message">system_message</a> element.</p>
</div>
<div class="section" id="morecols">
<h2><a class="toc-backref" href="#toc-entry-128"><tt class="docutils literal">morecols</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#number">number</a>. Default value: none.</p>
<p>The <tt class="docutils literal">morecols</tt> attribute is used in the <a class="reference internal" href="#table">table</a> element.</p>
</div>
<div class="section" id="names">
<h2><a class="toc-backref" href="#toc-entry-129"><tt class="docutils literal">names</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#refnames-type">refnames.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">names</tt> attribute is a space-separated list containing
<a class="reference external" href="rst/restructuredtext.html#normalized-reference-names">normalized</a> <a class="reference external" href="rst/restructuredtext.html#reference-names">reference names</a> of an element. Whitespace inside a
name is backslash escaped.
Each name in the list must be unique; if there are name conflicts
(two or more elements want to the same name), the contents will be
transferred to the <a class="reference internal" href="#dupnames">dupnames</a> attribute on the duplicate elements.
An element may have at most one of the <tt class="docutils literal">names</tt> or <tt class="docutils literal">dupnames</tt>
attributes, but not both.</p>
<p><a class="reference external" href="rst/restructuredtext.html#reference-names">Reference names</a> are identifiers assigned in the markup. They
originate from <a class="reference external" href="rst/restructuredtext.html#internal-hyperlink-targets">internal hyperlink targets</a>, a directive's <a class="reference external" href="rst/directives.html#name">name
option</a>, or the element's title or content and are used for
internal cross-references (cf. <a class="reference internal" href="#refname">refname</a>).</p>
<p><tt class="docutils literal">names</tt> is one of the <a class="reference internal" href="#common-attributes">common attributes</a>, shared by all
Docutils elements.</p>
</div>
<div class="section" id="prefix">
<h2><a class="toc-backref" href="#toc-entry-130"><tt class="docutils literal">prefix</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">prefix</tt> attribute is used in the <a class="reference internal" href="#enumerated-list">enumerated_list</a> element.</p>
</div>
<div class="section" id="refid">
<h2><a class="toc-backref" href="#toc-entry-131"><tt class="docutils literal">refid</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#idref-type">idref.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">refid</tt> attribute contains a reference to an <a class="reference internal" href="#identifier-key">identifier key</a></p>
<p><tt class="docutils literal">refid</tt> is used by the <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#reference">reference</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a>,
<a class="reference internal" href="#citation-reference">citation_reference</a>, <a class="reference internal" href="#title">title</a> and <a class="reference internal" href="#problematic">problematic</a> elements (via the
<a class="reference internal" href="#refid-att">%refid.att;</a> and <a class="reference internal" href="#reference-atts">%reference.atts;</a> parameter entities).</p>
</div>
<div class="section" id="refname">
<h2><a class="toc-backref" href="#toc-entry-132"><tt class="docutils literal">refname</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#refname-type">refname.type</a>. Default value: none.</p>
<p>The <tt class="docutils literal">refname</tt> attribute contains a reference to one of the
<a class="reference external" href="rst/restructuredtext.html#reference-names">reference names</a> in the <a class="reference internal" href="#names">names</a> attribute of another element. On
a <a class="reference internal" href="#target">target</a> element, <tt class="docutils literal">refname</tt> indicates an <a class="reference external" href="rst/restructuredtext.html#indirect-hyperlink-targets">indirect target</a> which
may resolve to either an internal or external reference. Docutils
"<a class="reference external" href="api/.html">transforms</a>" replace the <tt class="docutils literal">refname</tt> attribute with a <a class="reference internal" href="#refid">refid</a> pointing
to the same element.</p>
<p><tt class="docutils literal">refname</tt> is used by the <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#reference">reference</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a>,
<a class="reference internal" href="#citation-reference">citation_reference</a>, and <a class="reference internal" href="#substitution-reference">substitution_reference</a> elements (via the
<a class="reference internal" href="#refname-att">%refname.att;</a> and <a class="reference internal" href="#reference-atts">%reference.atts;</a> parameter entities).</p>
</div>
<div class="section" id="refuri">
<h2><a class="toc-backref" href="#toc-entry-133"><tt class="docutils literal">refuri</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">refuri</tt> attribute contains an external reference to a URI/URL.
It is used by the <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#reference">reference</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a>, and
<a class="reference internal" href="#citation-reference">citation_reference</a> elements (via the <a class="reference internal" href="#reference-atts">%reference.atts;</a> parameter
entity).</p>
</div>
<div class="section" id="scale">
<h2><a class="toc-backref" href="#toc-entry-134"><tt class="docutils literal">scale</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#number">number</a>. Default value: none.</p>
<p>The <tt class="docutils literal">scale</tt> attribute is used in the <a class="reference internal" href="#image">image</a> element.</p>
</div>
<div class="section" id="source">
<h2><a class="toc-backref" href="#toc-entry-135"><tt class="docutils literal">source</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">source</tt> attribute is used to store the path or URL to the
source text that was used to produce the document tree. It is one of
the <a class="reference internal" href="#common-attributes">common attributes</a>, declared for all Docutils elements.</p>
</div>
<div class="section" id="start">
<h2><a class="toc-backref" href="#toc-entry-136"><tt class="docutils literal">start</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#number">number</a>. Default value: none.</p>
<p>The <tt class="docutils literal">start</tt> attribute is used in the <a class="reference internal" href="#enumerated-list">enumerated_list</a> element.</p>
</div>
<div class="section" id="stub">
<h2><a class="toc-backref" href="#toc-entry-137"><tt class="docutils literal">stub</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#yesorno">yesorno</a>. Default value: none.</p>
<p>The <tt class="docutils literal">stub</tt> attribute is used in the <a class="reference internal" href="#colspec">colspec</a> element.
It marks a table column containing "stubs" (row titles, on the left).
See also the <a class="reference external" href="rst/directives.html#csv-table">csv-table</a> and <a class="reference external" href="rst/directives.html#list-table">list-table</a> directives.</p>
</div>
<div class="section" id="suffix">
<h2><a class="toc-backref" href="#toc-entry-138"><tt class="docutils literal">suffix</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">suffix</tt> attribute is used in the <a class="reference internal" href="#enumerated-list">enumerated_list</a> element.</p>
</div>
<div class="section" id="title-2">
<span id="title-attribute"></span><h2><a class="toc-backref" href="#toc-entry-139"><tt class="docutils literal">title</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#cdata">CDATA</a>. Default value: none.</p>
<p>The <tt class="docutils literal">title</tt> attribute stores the title metadata of a <a class="reference internal" href="#document">document</a>. This
title is typically not part of the rendered document. It may for
example be used in HTML's <tt class="docutils literal">title</tt> element.</p>
</div>
<div class="section" id="width">
<h2><a class="toc-backref" href="#toc-entry-140"><tt class="docutils literal">width</tt></a></h2>
<p>Attribute type: <a class="reference internal" href="#measure">measure</a>. Default value: none.</p>
<p>The <tt class="docutils literal">width</tt> attribute is used in the <a class="reference internal" href="#figure">figure</a>, <a class="reference internal" href="#image">image</a>, and <a class="reference internal" href="#table">table</a> element.</p>
</div>
<div class="section" id="xml-space">
<h2><a class="toc-backref" href="#toc-entry-141"><tt class="docutils literal">xml:space</tt></a></h2>
<p><cite>Attribute type</cite>: <a class="reference internal" href="#enumeratedtype">EnumeratedType</a>, one of "default" or "preserve".
Default value: "preserve" (fixed).</p>
<p>The <tt class="docutils literal">xml:space</tt> attribute is a standard XML attribute for
whitespace-preserving elements. It is used by the <a class="reference internal" href="#literal-block">literal_block</a>,
<a class="reference internal" href="#line-block">line_block</a>, <a class="reference internal" href="#doctest-block">doctest_block</a>, <a class="reference internal" href="#comment">comment</a>, and <a class="reference internal" href="#raw">raw</a> elements (via the
<a class="reference internal" href="#fixedspace-att">%fixedspace.att;</a> parameter entity). It is a fixed attribute, meant
to communicate to an XML parser that the element contains significant
whitespace. The attribute value should not be set in a document
instance.</p>
</div>
</div>
<div class="section" id="parameter-entity-reference">
<h1><a class="toc-backref" href="#toc-entry-5">Parameter Entity Reference</a></h1>
<div class="contents local topic" id="topic-5">
<ul class="simple">
<li><a class="reference internal" href="#align-h-att" id="toc-entry-142"><tt class="docutils literal"><span class="pre">%align-h.att;</span></tt></a></li>
<li><a class="reference internal" href="#align-hv-att" id="toc-entry-143"><tt class="docutils literal"><span class="pre">%align-hv.att;</span></tt></a></li>
<li><a class="reference internal" href="#anonymous-att" id="toc-entry-144"><tt class="docutils literal">%anonymous.att;</tt></a></li>
<li><a class="reference internal" href="#auto-att" id="toc-entry-145"><tt class="docutils literal">%auto.att;</tt></a></li>
<li><a class="reference internal" href="#backrefs-att" id="toc-entry-146"><tt class="docutils literal">%backrefs.att;</tt></a></li>
<li><a class="reference internal" href="#basic-atts" id="toc-entry-147"><tt class="docutils literal">%basic.atts;</tt></a></li>
<li><a class="reference internal" href="#bibliographic-elements-1" id="toc-entry-148"><tt class="docutils literal">%bibliographic.elements;</tt></a></li>
<li><a class="reference internal" href="#body-elements-1" id="toc-entry-149"><tt class="docutils literal">%body.elements;</tt></a></li>
<li><a class="reference internal" href="#fixedspace-att" id="toc-entry-150"><tt class="docutils literal">%fixedspace.att;</tt></a></li>
<li><a class="reference internal" href="#inline-elements-1" id="toc-entry-151"><tt class="docutils literal">%inline.elements;</tt></a></li>
<li><a class="reference internal" href="#reference-atts" id="toc-entry-152"><tt class="docutils literal">%reference.atts;</tt></a></li>
<li><a class="reference internal" href="#refid-att" id="toc-entry-153"><tt class="docutils literal">%refid.att;</tt></a></li>
<li><a class="reference internal" href="#refname-att" id="toc-entry-154"><tt class="docutils literal">%refname.att;</tt></a></li>
<li><a class="reference internal" href="#refuri-att" id="toc-entry-155"><tt class="docutils literal">%refuri.att;</tt></a></li>
<li><a class="reference internal" href="#section-elements" id="toc-entry-156"><tt class="docutils literal">%section.elements;</tt></a></li>
<li><a class="reference internal" href="#structure-model" id="toc-entry-157"><tt class="docutils literal">%structure.model;</tt></a></li>
<li><a class="reference internal" href="#text-model" id="toc-entry-158"><tt class="docutils literal">%text.model;</tt></a></li>
</ul>
</div>
<p>Parameter entities are used to simplify the DTD (to share definitions
and reduce duplication) and to allow the DTD to be customized by
wrapper DTDs (external client DTDs that use or import the Docutils
DTD). Parameter entities may be overridden by wrapper DTDs, replacing
the definitions below with custom definitions. Parameter entities
whose names begin with "additional" are meant to allow easy extension
by wrapper DTDs.</p>
<div class="section" id="align-h-att">
<h2><a class="toc-backref" href="#toc-entry-142"><tt class="docutils literal"><span class="pre">%align-h.att;</span></tt></a></h2>
<p>The <tt class="docutils literal"><span class="pre">%align-h.att;</span></tt> parameter entity contains the <a class="reference internal" href="#align">align</a>
attribute for horizontal alignment.</p>
<p>Entity definition:</p>
<pre class="literal-block">
align (left | center | right) #IMPLIED
</pre>
<p>The <a class="reference internal" href="#figure">figure</a> and <a class="reference internal" href="#table">table</a> elements directly employ the
<tt class="docutils literal"><span class="pre">%align-h.att;</span></tt> parameter entity in their attribute lists.</p>
</div>
<div class="section" id="align-hv-att">
<h2><a class="toc-backref" href="#toc-entry-143"><tt class="docutils literal"><span class="pre">%align-hv.att;</span></tt></a></h2>
<p>The <tt class="docutils literal"><span class="pre">%align-hv.att;</span></tt> parameter entity contains the <a class="reference internal" href="#align">align</a>
attribute for horizontal and vertical alignment.</p>
<p>Entity definition:</p>
<pre class="literal-block">
align (top | middle | bottom | left | center | right) #IMPLIED
</pre>
<p>The <a class="reference internal" href="#image">image</a> element directly employs the <tt class="docutils literal"><span class="pre">%align-hv.att;</span></tt> parameter
entity in its attribute list.</p>
</div>
<div class="section" id="anonymous-att">
<h2><a class="toc-backref" href="#toc-entry-144"><tt class="docutils literal">%anonymous.att;</tt></a></h2>
<p>The <tt class="docutils literal">%anonymous.att;</tt> parameter entity contains the <a class="reference internal" href="#anonymous">anonymous</a>
attribute, used for unnamed hyperlinks.</p>
<p>Entity definition:</p>
<pre class="literal-block">
anonymous %yesorno; #IMPLIED
</pre>
<p>The <a class="reference internal" href="#reference">reference</a> and <a class="reference internal" href="#target">target</a> elements directly employ the
<tt class="docutils literal">%anonymous.att;</tt> parameter entity in their attribute lists.</p>
</div>
<div class="section" id="auto-att">
<h2><a class="toc-backref" href="#toc-entry-145"><tt class="docutils literal">%auto.att;</tt></a></h2>
<p>The <tt class="docutils literal">%auto.att;</tt> parameter entity contains the <a class="reference internal" href="#auto">auto</a> attribute, used
to indicate an automatically-numbered footnote or title.</p>
<p>Entity definition:</p>
<pre class="literal-block">
auto CDATA #IMPLIED
</pre>
<p>The <a class="reference internal" href="#footnote">footnote</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a>, and <a class="reference internal" href="#title">title</a> elements directly
employ the <tt class="docutils literal">%auto.att;</tt> parameter entity in their attribute lists.</p>
</div>
<div class="section" id="backrefs-att">
<h2><a class="toc-backref" href="#toc-entry-146"><tt class="docutils literal">%backrefs.att;</tt></a></h2>
<p>The <tt class="docutils literal">%backrefs.att;</tt> parameter entity contains the <a class="reference internal" href="#backrefs">backrefs</a>
attribute, a space-separated list of id references, for backlinks.</p>
<p>Entity definition:</p>
<pre class="literal-block">
backrefs_ %idrefs.type; #IMPLIED
</pre>
<p>The <a class="reference internal" href="#citation">citation</a>, <a class="reference internal" href="#footnote">footnote</a>, and <a class="reference internal" href="#system-message">system_message</a> elements directly employ
the <tt class="docutils literal">%backrefs.att;</tt> parameter entity in their attribute lists.</p>
</div>
<div class="section" id="basic-atts">
<h2><a class="toc-backref" href="#toc-entry-147"><tt class="docutils literal">%basic.atts;</tt></a></h2>
<p>The <tt class="docutils literal">%basic.atts;</tt> parameter entity lists the <a class="reference internal" href="#common-attributes">common attributes</a>.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#ids">ids</a> NMTOKENS #IMPLIED
<a class="reference internal" href="#names">names</a> CDATA #IMPLIED
<a class="reference internal" href="#dupnames">dupnames</a> CDATA #IMPLIED
<a class="reference internal" href="#source">source</a> CDATA #IMPLIED
<a class="reference internal" href="#classes">classes</a> NMTOKENS #IMPLIED
%additional.basic.atts;
</pre>
<p>The <tt class="docutils literal">%additional.basic.atts;</tt> parameter entity can be used by
wrapper DTDs to extend <tt class="docutils literal">%basic.atts;</tt>.</p>
</div>
<div class="section" id="bibliographic-elements-1">
<h2><a class="toc-backref" href="#toc-entry-148"><tt class="docutils literal">%bibliographic.elements;</tt></a></h2>
<p>The <tt class="docutils literal">%bibliographic.elements;</tt> parameter entity contains an OR-list of all
<a class="reference internal" href="#bibliographic-elements">bibliographic elements</a>.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#author">author</a> | <a class="reference internal" href="#authors">authors</a> | <a class="reference internal" href="#organization">organization</a> | <a class="reference internal" href="#contact">contact</a> | <a class="reference internal" href="#address">address</a>
| <a class="reference internal" href="#version">version</a> | <a class="reference internal" href="#revision">revision</a> | <a class="reference internal" href="#status">status</a> | <a class="reference internal" href="#date">date</a> | <a class="reference internal" href="#copyright">copyright</a>
| <a class="reference internal" href="#field">field</a>
%additional.bibliographic.elements;
</pre>
<p>The <tt class="docutils literal">%additional.bibliographic.elements;</tt> parameter entity can be used by
wrapper DTDs to extend <tt class="docutils literal">%bibliographic.elements;</tt>.</p>
<p>Only the <a class="reference internal" href="#docinfo">docinfo</a> element directly employs the
<tt class="docutils literal">%bibliographic.elements;</tt> parameter entity in its content model.</p>
</div>
<div class="section" id="body-elements-1">
<h2><a class="toc-backref" href="#toc-entry-149"><tt class="docutils literal">%body.elements;</tt></a></h2>
<p>The <tt class="docutils literal">%body.elements;</tt> parameter entity contains an OR-list of all
<a class="reference internal" href="#body-elements">body elements</a>. <tt class="docutils literal">%body.elements;</tt> is itself contained within the
<a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#admonition">admonition</a> | <a class="reference internal" href="#attention">attention</a> | <a class="reference internal" href="#block-quote">block_quote</a> | <a class="reference internal" href="#bullet-list">bullet_list</a> | <a class="reference internal" href="#caution">caution</a>
| <a class="reference internal" href="#citation">citation</a> | <a class="reference internal" href="#compound">compound</a> | <a class="reference internal" href="#comment">comment</a> | <a class="reference internal" href="#container">container</a> | <a class="reference internal" href="#danger">danger</a>
| <a class="reference internal" href="#definition-list">definition_list</a> | <a class="reference internal" href="#doctest-block">doctest_block</a> | <a class="reference internal" href="#enumerated-list">enumerated_list</a> | <a class="reference internal" href="#error">error</a>
| <a class="reference internal" href="#field-list">field_list</a> | <a class="reference internal" href="#figure">figure</a> | <a class="reference internal" href="#footnote">footnote</a> | <a class="reference internal" href="#hint">hint</a> | <a class="reference internal" href="#image">image</a> | <a class="reference internal" href="#important">important</a>
| <a class="reference internal" href="#line-block">line_block</a> | <a class="reference internal" href="#literal-block">literal_block</a> | <a class="reference internal" href="#note">note</a> | <a class="reference internal" href="#option-list">option_list</a>
| <a class="reference internal" href="#paragraph">paragraph</a> | <a class="reference internal" href="#pending">pending</a> | <a class="reference internal" href="#raw">raw</a> <a class="reference internal" href="#reference">reference</a> | <a class="reference internal" href="#rubric">rubric</a>
| <a class="reference internal" href="#substitution-definition">substitution_definition</a> | <a class="reference internal" href="#system-message">system_message</a> | <a class="reference internal" href="#table">table</a> | <a class="reference internal" href="#target">target</a>
| <a class="reference internal" href="#tip">tip</a> | <a class="reference internal" href="#warning">warning</a> %additional.body.elements;
</pre>
<p>The <tt class="docutils literal">%additional.body.elements;</tt> parameter entity can be used by
wrapper DTDs to extend <tt class="docutils literal">%body.elements;</tt>.</p>
<p>The <tt class="docutils literal">%body.elements;</tt> parameter entity is directly employed in the
content models of the following elements: <a class="reference internal" href="#admonition">admonition</a>, <a class="reference internal" href="#attention">attention</a>,
<a class="reference internal" href="#block-quote">block_quote</a>, <a class="reference internal" href="#caution">caution</a>, <a class="reference internal" href="#citation">citation</a>, <a class="reference internal" href="#compound">compound</a>, <a class="reference internal" href="#danger">danger</a>, <a class="reference internal" href="#definition">definition</a>,
<a class="reference internal" href="#description">description</a>, <a class="reference internal" href="#entry">entry</a>, <a class="reference internal" href="#error">error</a>, <a class="reference internal" href="#field-body">field_body</a>, <a class="reference internal" href="#footer">footer</a>, <a class="reference internal" href="#footnote">footnote</a>,
<a class="reference internal" href="#header">header</a>, <a class="reference internal" href="#hint">hint</a>, <a class="reference internal" href="#important">important</a>, <a class="reference internal" href="#legend">legend</a>, <a class="reference internal" href="#list-item">list_item</a>, <a class="reference internal" href="#note">note</a>, <a class="reference internal" href="#sidebar">sidebar</a>,
<a class="reference internal" href="#system-message">system_message</a>, <a class="reference internal" href="#tip">tip</a>, <a class="reference internal" href="#topic">topic</a>, <a class="reference internal" href="#warning">warning</a></p>
<p>Via <a class="reference internal" href="#structure-model">%structure.model;</a>, the <tt class="docutils literal">%body.elements;</tt> parameter entity is
indirectly employed in the content models of the <a class="reference internal" href="#document">document</a> and
<a class="reference internal" href="#section">section</a> elements.</p>
</div>
<div class="section" id="fixedspace-att">
<h2><a class="toc-backref" href="#toc-entry-150"><tt class="docutils literal">%fixedspace.att;</tt></a></h2>
<p>The <tt class="docutils literal">%fixedspace.att;</tt> parameter entity contains the <a class="reference internal" href="#xml-space">xml:space</a>
attribute, a standard XML attribute for whitespace-preserving
elements.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#xml-space">xml:space</a> (default | preserve) #FIXED 'preserve'
</pre>
<p>The <tt class="docutils literal">%fixedspace.att;</tt> parameter entity is directly employed in the
attribute lists of the following elements: <a class="reference internal" href="#address">address</a>, <a class="reference internal" href="#comment">comment</a>,
<a class="reference internal" href="#doctest-block">doctest_block</a>, <a class="reference internal" href="#line-block">line_block</a>, <a class="reference internal" href="#literal-block">literal_block</a>, <a class="reference internal" href="#raw">raw</a></p>
</div>
<div class="section" id="inline-elements-1">
<h2><a class="toc-backref" href="#toc-entry-151"><tt class="docutils literal">%inline.elements;</tt></a></h2>
<p>The <tt class="docutils literal">%inline.elements;</tt> parameter entity contains an OR-list of all
<a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#abbreviation">abbreviation</a> | <a class="reference internal" href="#acronym">acronym</a> | <a class="reference internal" href="#citation-reference">citation_reference</a> | <a class="reference internal" href="#emphasis">emphasis</a>
| <a class="reference internal" href="#footnote-reference">footnote_reference</a> | <a class="reference internal" href="#generated">generated</a> | <a class="reference internal" href="#image">image</a> | <a class="reference internal" href="#inline">inline</a> | <a class="reference internal" href="#literal">literal</a>
| <a class="reference internal" href="#problematic">problematic</a> | <a class="reference internal" href="#raw">raw</a> | <a class="reference internal" href="#reference">reference</a> | <a class="reference internal" href="#strong">strong</a> | <a class="reference internal" href="#substitution-reference">substitution_reference</a>
| <a class="reference internal" href="#subscript">subscript</a> | <a class="reference internal" href="#superscript">superscript</a> | <a class="reference internal" href="#target">target</a> | <a class="reference internal" href="#title-reference">title_reference</a>
%additional.inline.elements;
</pre>
<p>The <tt class="docutils literal">%additional.inline.elements;</tt> parameter entity can be used by
wrapper DTDs to extend <tt class="docutils literal">%inline.elements;</tt>.</p>
<p>Via <a class="reference internal" href="#text-model">%text.model;</a>, the <tt class="docutils literal">%inline.elements;</tt> parameter entity is
indirectly employed in the content models of the following elements:
<a class="reference internal" href="#abbreviation">abbreviation</a>, <a class="reference internal" href="#acronym">acronym</a>, <a class="reference internal" href="#address">address</a>, <a class="reference internal" href="#attribution">attribution</a>, <a class="reference internal" href="#author">author</a>, <a class="reference internal" href="#caption">caption</a>,
<a class="reference internal" href="#classifier">classifier</a>, <a class="reference internal" href="#contact">contact</a>, <a class="reference internal" href="#copyright">copyright</a>, <a class="reference internal" href="#date">date</a>, <a class="reference internal" href="#doctest-block">doctest_block</a>, <a class="reference internal" href="#emphasis">emphasis</a>,
<a class="reference internal" href="#generated">generated</a>, <a class="reference internal" href="#inline">inline</a>, <a class="reference internal" href="#line-block">line_block</a>, <a class="reference internal" href="#literal-block">literal_block</a>, <a class="reference internal" href="#math">math</a>, <a class="reference internal" href="#math-block">math_block</a>,
<a class="reference internal" href="#organization">organization</a>,
<a class="reference internal" href="#paragraph">paragraph</a>, <a class="reference internal" href="#problematic">problematic</a>, <a class="reference internal" href="#raw">raw</a>, <a class="reference internal" href="#reference">reference</a>, <a class="reference internal" href="#revision">revision</a>, <a class="reference internal" href="#rubric">rubric</a>,
<a class="reference internal" href="#status">status</a>, <a class="reference internal" href="#strong">strong</a>, <a class="reference internal" href="#subscript">subscript</a>, <a class="reference internal" href="#substitution-definition">substitution_definition</a>,
<a class="reference internal" href="#substitution-reference">substitution_reference</a>, <a class="reference internal" href="#subtitle">subtitle</a>, <a class="reference internal" href="#superscript">superscript</a>, <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#term">term</a>,
<a class="reference internal" href="#title">title</a>, <a class="reference internal" href="#title-reference">title_reference</a>, <a class="reference internal" href="#version">version</a></p>
</div>
<div class="section" id="reference-atts">
<h2><a class="toc-backref" href="#toc-entry-152"><tt class="docutils literal">%reference.atts;</tt></a></h2>
<p>The <tt class="docutils literal">%reference.atts;</tt> parameter entity groups together the <a class="reference internal" href="#refuri">refuri</a>,
<a class="reference internal" href="#refid">refid</a>, and <a class="reference internal" href="#refname">refname</a> attributes.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#refuri-att">%refuri.att;</a>
<a class="reference internal" href="#refid-att">%refid.att;</a>
<a class="reference internal" href="#refname-att">%refname.att;</a>
%additional.reference.atts;
</pre>
<p>The <tt class="docutils literal">%additional.reference.atts;</tt> parameter entity can be used by
wrapper DTDs to extend <tt class="docutils literal">%additional.reference.atts;</tt>.</p>
<p>The <a class="reference internal" href="#citation-reference">citation_reference</a>, <a class="reference internal" href="#footnote-reference">footnote_reference</a>, <a class="reference internal" href="#reference">reference</a>, and <a class="reference internal" href="#target">target</a>
elements directly employ the <tt class="docutils literal">%reference.att;</tt> parameter entity in
their attribute lists.</p>
</div>
<div class="section" id="refid-att">
<h2><a class="toc-backref" href="#toc-entry-153"><tt class="docutils literal">%refid.att;</tt></a></h2>
<p>The <tt class="docutils literal">%refid.att;</tt> parameter entity contains the <a class="reference internal" href="#refid">refid</a> attribute, an
internal reference to the <a class="reference internal" href="#ids">ids</a> attribute of another element.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#refid">refid</a> %idref.type; #IMPLIED
</pre>
<p>The <a class="reference internal" href="#title">title</a> and <a class="reference internal" href="#problematic">problematic</a> elements directly employ the
<tt class="docutils literal">%refid.att;</tt> parameter entity in their attribute lists.</p>
<p>Via <a class="reference internal" href="#reference-atts">%reference.atts;</a>, the <tt class="docutils literal">%refid.att;</tt> parameter entity is
indirectly employed in the attribute lists of the <a class="reference internal" href="#citation-reference">citation_reference</a>,
<a class="reference internal" href="#footnote-reference">footnote_reference</a>, <a class="reference internal" href="#reference">reference</a>, and <a class="reference internal" href="#target">target</a> elements.</p>
</div>
<div class="section" id="refname-att">
<h2><a class="toc-backref" href="#toc-entry-154"><tt class="docutils literal">%refname.att;</tt></a></h2>
<p>The <tt class="docutils literal">%refname.att;</tt> parameter entity contains the <a class="reference internal" href="#refname">refname</a>
attribute, an internal reference to the <a class="reference internal" href="#names">names</a> attribute of another
element. On a <a class="reference internal" href="#target">target</a> element, <tt class="docutils literal">refname</tt> indicates an indirect
target which may resolve to either an internal or external
reference.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#refname">refname</a> %refname.type; #IMPLIED
</pre>
<p>The <a class="reference internal" href="#substitution-reference">substitution_reference</a> element directly employs the
<tt class="docutils literal">%refname.att;</tt> parameter entity in its attribute list.</p>
<p>Via <a class="reference internal" href="#reference-atts">%reference.atts;</a>, the <tt class="docutils literal">%refname.att;</tt> parameter entity is
indirectly employed in the attribute lists of the <a class="reference internal" href="#citation-reference">citation_reference</a>,
<a class="reference internal" href="#footnote-reference">footnote_reference</a>, <a class="reference internal" href="#reference">reference</a>, and <a class="reference internal" href="#target">target</a> elements.</p>
</div>
<div class="section" id="refuri-att">
<h2><a class="toc-backref" href="#toc-entry-155"><tt class="docutils literal">%refuri.att;</tt></a></h2>
<p>The <tt class="docutils literal">%refuri.att;</tt> parameter entity contains the <a class="reference internal" href="#refuri">refuri</a> attribute,
an external reference to a URI/URL.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#refuri">refuri</a> CDATA #IMPLIED
</pre>
<p>Via <a class="reference internal" href="#reference-atts">%reference.atts;</a>, the <tt class="docutils literal">%refuri.att;</tt> parameter entity is
indirectly employed in the attribute lists of the <a class="reference internal" href="#citation-reference">citation_reference</a>,
<a class="reference internal" href="#footnote-reference">footnote_reference</a>, <a class="reference internal" href="#reference">reference</a>, and <a class="reference internal" href="#target">target</a> elements.</p>
</div>
<div class="section" id="section-elements">
<h2><a class="toc-backref" href="#toc-entry-156"><tt class="docutils literal">%section.elements;</tt></a></h2>
<p>The <tt class="docutils literal">%section.elements;</tt> parameter entity contains an OR-list of all
<a class="reference internal" href="#section">section</a>-equivalent elements. <tt class="docutils literal">%section.elements;</tt> is itself
contained within the <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity.</p>
<p>Entity definition:</p>
<pre class="literal-block">
<a class="reference internal" href="#section">section</a>
%additional.section.elements;
</pre>
<p>The <tt class="docutils literal">%additional.section.elements;</tt> parameter entity can be used
by wrapper DTDs to extend <tt class="docutils literal">%section.elements;</tt>.</p>
<p>Via <a class="reference internal" href="#structure-model">%structure.model;</a>, the <tt class="docutils literal">%section.elements;</tt> parameter entity
is indirectly employed in the content models of the <a class="reference internal" href="#document">document</a> and
<a class="reference internal" href="#section">section</a> elements.</p>
</div>
<div class="section" id="structure-model">
<h2><a class="toc-backref" href="#toc-entry-157"><tt class="docutils literal">%structure.model;</tt></a></h2>
<p>The <tt class="docutils literal">%structure.model;</tt> parameter entity encapsulates the
hierarchical structure of a document and of its constituent parts.
See the discussion of the <a class="reference internal" href="#element-hierarchy">element hierarchy</a> above.</p>
<p>Entity definition:</p>
<pre class="literal-block">
( ( (<a class="reference internal" href="#body-elements-1">%body.elements;</a> | <a class="reference internal" href="#topic">topic</a> | <a class="reference internal" href="#sidebar">sidebar</a>)+, <a class="reference internal" href="#transition">transition</a>? )*,
( (<a class="reference internal" href="#section-elements">%section.elements;</a>), (<a class="reference internal" href="#transition">transition</a>?, (<a class="reference internal" href="#section-elements">%section.elements;</a>) )* )? )
</pre>
<p>Each <a class="reference internal" href="#document">document</a> or <a class="reference internal" href="#section">section</a> contains zero or more body elements,
topics, and/or sidebars, optionally interspersed with single
transitions, followed by zero or more sections (whose contents are
recursively the same as this model) optionally interspersed with
transitions.</p>
<p>The following restrictions are imposed by this model:</p>
<ul class="simple">
<li>Transitions must be separated by other elements (body elements,
sections, etc.). In other words, a transition may not be
immediately adjacent to another transition.</li>
<li>A transition may not occur at the beginning of a document or
section.</li>
</ul>
<!-- The following is not the case with Docutils (since at least 2004)
(cf. test/functional/input/data/standard.txt)
An additional restriction, which cannot be expressed in the language
of DTDs, is imposed by software:
* A transition may not occur at the end of a document or section. -->
<p>The <a class="reference internal" href="#structure-model">%structure.model;</a> parameter entity is directly employed in the
content models of the <a class="reference internal" href="#document">document</a> and <a class="reference internal" href="#section">section</a> elements.</p>
</div>
<div class="section" id="text-model">
<h2><a class="toc-backref" href="#toc-entry-158"><tt class="docutils literal">%text.model;</tt></a></h2>
<p>The <tt class="docutils literal">%text.model;</tt> parameter entity is used by many elements to
represent text data mixed with <a class="reference internal" href="#inline-elements">inline elements</a>.</p>
<p>Entity definition:</p>
<pre class="literal-block">
(#PCDATA | <a class="reference internal" href="#inline-elements-1">%inline.elements;</a>)*
</pre>
<p>The <tt class="docutils literal">%text.model;</tt> parameter entity is directly employed in the
content models of the following elements: <a class="reference internal" href="#abbreviation">abbreviation</a>, <a class="reference internal" href="#acronym">acronym</a>,
<a class="reference internal" href="#address">address</a>, <a class="reference internal" href="#author">author</a>, <a class="reference internal" href="#caption">caption</a>, <a class="reference internal" href="#classifier">classifier</a>, <a class="reference internal" href="#contact">contact</a>, <a class="reference internal" href="#copyright">copyright</a>, <a class="reference internal" href="#date">date</a>,
<a class="reference internal" href="#doctest-block">doctest_block</a>, <a class="reference internal" href="#emphasis">emphasis</a>, <a class="reference internal" href="#field-name">field_name</a>, <a class="reference internal" href="#generated">generated</a>, <a class="reference internal" href="#line-block">line_block</a>,
<a class="reference internal" href="#literal-block">literal_block</a>, <a class="reference internal" href="#organization">organization</a>, <a class="reference internal" href="#paragraph">paragraph</a>, <a class="reference internal" href="#problematic">problematic</a>, <a class="reference internal" href="#raw">raw</a>,
<a class="reference internal" href="#reference">reference</a>, <a class="reference internal" href="#revision">revision</a>, <a class="reference internal" href="#status">status</a>, <a class="reference internal" href="#strong">strong</a>, <a class="reference internal" href="#substitution-definition">substitution_definition</a>,
<a class="reference internal" href="#substitution-reference">substitution_reference</a>, <a class="reference internal" href="#subtitle">subtitle</a>, <a class="reference internal" href="#target">target</a>, <a class="reference internal" href="#term">term</a>, <a class="reference internal" href="#title">title</a>, <a class="reference internal" href="#version">version</a></p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</div>
</body>
</html>