File: specification_expected.html

package info (click to toggle)
python-rich-rst 1.3.1%2Bdfsg-2
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 1,756 kB
sloc: python: 697; makefile: 17
file content (2196 lines) | stat: -rw-r--r-- 422,837 bytes
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<style>
.r1 {font-weight: bold}
.r2 {color: #ffffff; text-decoration-color: #ffffff; font-weight: bold}
.r3 {color: #bd93f9; text-decoration-color: #bd93f9; background-color: #282a36; text-decoration: underline}
.r4 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #282a36}
.r5 {color: #f1fa8c; text-decoration-color: #f1fa8c; font-weight: bold}
.r6 {color: #949494; text-decoration-color: #949494}
.r7 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #272822}
.r8 {color: #ff4689; text-decoration-color: #ff4689; background-color: #272822}
.r9 {background-color: #272822}
.r10 {color: #ae81ff; text-decoration-color: #ae81ff; background-color: #272822}
.r11 {color: #e6db74; text-decoration-color: #e6db74; background-color: #272822}
.r12 {color: #66d9ef; text-decoration-color: #66d9ef; background-color: #272822}
.r13 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #282a36; font-style: italic}
.r14 {color: #c6c6c6; text-decoration-color: #c6c6c6; background-color: #121212}
.r15 {color: #ed007e; text-decoration-color: #ed007e; background-color: #1e0010}
.r16 {color: #c6c6c6; text-decoration-color: #c6c6c6; background-color: #121212; text-decoration: underline}
.r17 {color: #ff79c6; text-decoration-color: #ff79c6}
.r18 {color: #ffffff; text-decoration-color: #ffffff}
.r19 {color: #e4e4e4; text-decoration-color: #e4e4e4}
.r20 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #282a36; font-weight: bold}
.r21 {color: #a6e22e; text-decoration-color: #a6e22e; background-color: #272822}
.r22 {color: #959077; text-decoration-color: #959077; background-color: #272822}
.r23 {color: #50fa7b; text-decoration-color: #50fa7b; font-weight: bold}
.r24 {color: #8be9fd; text-decoration-color: #8be9fd}
.r25 {color: #ff5555; text-decoration-color: #ff5555}
.r26 {color: #8be9fd; text-decoration-color: #8be9fd; font-weight: bold}
.r27 {color: #ff79c6; text-decoration-color: #ff79c6; font-weight: bold}
.r28 {color: #50fa7b; text-decoration-color: #50fa7b}
.r29 {color: #bcbcbc; text-decoration-color: #bcbcbc}
body {
    color: #f8f8f2;
    background-color: #282a36;
}
</style>
</head>
<body>
    <pre style="font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace"><code style="font-family:inherit"><span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                        reStructuredText Markup Specification                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name </span>┃<span class="r1"> Field Value                                            </span>┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Author    </span> │ David Goodger                                          │
├────────────┼────────────────────────────────────────────────────────┤
│ <span class="r1">Contact   </span> │ docutils-develop@lists.sourceforge.net                 │
├────────────┼────────────────────────────────────────────────────────┤
│ <span class="r1">Revision  </span> │ $Revision: 8959 $                                      │
├────────────┼────────────────────────────────────────────────────────┤
│ <span class="r1">Date      </span> │ $Date: 2022-01-21 14:45:42 +0100 (Fr, 21. JÃ¤n 2022) $ │
├────────────┼────────────────────────────────────────────────────────┤
│ <span class="r1">Copyright </span> │ This document has been placed in the public domain.    │
└────────────┴────────────────────────────────────────────────────────┘
<span class="r2">╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮</span>
<span class="r2">│ This document is a detailed technical specification; it is not a tutorial or a primer.  If this is your first        │</span>
<span class="r2">│ exposure to reStructuredText, please read A ReStructuredText Primer and the Quick reStructuredText user reference    │</span>
<span class="r2">│ first.                                                                                                               │</span>
<span class="r2">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<a class="r3" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a><span class="r4"> is plaintext that uses simple and intuitive constructs to indicate the structure of a document.  These </span>
<span class="r4">constructs are equally easy to read in raw and processed forms.  This document is itself an example of reStructuredText </span>
<span class="r4">(raw, if you are reading the text file, or processed, if you are reading an HTML document, for example).  The </span>
<span class="r4">reStructuredText parser is a component of </span><span class="r3">Docutils</span><span class="r4">.</span>

<span class="r4">Simple, implicit markup is used to indicate special constructs, such as section headings, bullet lists, and emphasis.  </span>
<span class="r4">The markup used is as minimal and unobtrusive as possible.  Less often-used constructs and extensions to the basic </span>
<span class="r4">reStructuredText syntax may have more elaborate or explicit markup.</span>

<span class="r4">reStructuredText is applicable to documents of any length, from the very small (such as inline program documentation </span>
<span class="r4">fragments, e.g. Python docstrings) to the quite large (this document).</span>

<span class="r4">The first section gives a quick overview of the syntax of the reStructuredText markup by example.  A complete </span>
<span class="r4">specification is given in the </span><span class="r3">Syntax Details</span><span class="r4"> section.</span>

<span class="r3">Literal blocks</span><span class="r4"> (in which no markup processing is done) are used for examples throughout this document, to illustrate the</span>
<span class="r4">plaintext markup.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Contents                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                Quick Syntax Overview                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">A reStructuredText document is made up of body or block-level elements, and may be structured into sections.  </span><span class="r3">Sections</span><span class="r4"> </span>
<span class="r4">are indicated through title style (underlines &amp; optional overlines). Sections contain body elements and/or subsections. </span>
<span class="r4">Some body elements contain further elements, such as lists containing list items, which in turn may contain paragraphs </span>
<span class="r4">and other body elements.  Others, such as paragraphs, contain text and </span><span class="r3">inline markup</span><span class="r4"> elements.</span>

<span class="r4">Here are examples of </span><span class="r3">body elements</span><span class="r4">:</span>

<span class="r5"> • </span>Paragraphs (and inline markup):  Paragraphs contain text and may contain inline markup: *emphasis*, **strong emphasis
`interpreted text`, ``inline literals``, standalone hyperlinks (https://www.python.org), external hyperlinks (Python_), 
internal cross-references (example_), footnote references ([1]_), citation references ([CIT2002]_), substitution 
references (|example|), and _`inline internal targets`.  Paragraphs are separated by blank lines and are left-aligned.
<span class="r5"> • </span>Five types of lists:  Bullet lists:  - This is a bullet list.  - Bullets can be &quot;*&quot;, &quot;+&quot;, or &quot;-&quot;.  Enumerated lists: 
This is an enumerated list.  2. Enumerators may be arabic numbers, letters, or roman    numerals.  Definition lists:  
what     Definition lists associate a term with a definition.  how     The term is a one-line phrase, and the definition
is one     or more paragraphs or body elements, indented relative to     the term.  Field lists:  :what: Field lists map
field names to field bodies, like        database records.  They are often part of an extension        syntax.  :how: 
The field marker is a colon, the field name, and a       colon.        The field body may contain one or more body 
elements,       indented relative to the field marker.  Option lists, for listing command-line options:  -a            
command-line option &quot;a&quot; -b file       options can have arguments               and long descriptions --long        
options can be long also --input=file  long options can also have               arguments /V            DOS/VMS-style 
options too  There must be at least two spaces between the option and the description.
<span class="r5"> • </span>Literal blocks:  Literal blocks are either indented or line-prefix-quoted blocks, and indicated with a double-colon 
(&quot;::&quot;) at the end of the preceding paragraph (right here --&gt;)::      if literal_block:         text = &#x27;is left as-is&#x27;   
spaces_and_linebreaks = &#x27;are preserved&#x27;         markup_processing = None
<span class="r5"> • </span>Block quotes:  Block quotes consist of indented body elements:      This theory, that is mine, is mine.      -- Anne 
(Miss)
<span class="r5"> • </span>Doctest blocks:  &gt;&gt;&gt; print &#x27;Python-specific usage examples; begun with &quot;&gt;&gt;&gt;&quot;&#x27; Python-specific usage examples; begun w
&quot;&gt;&gt;&gt;&quot; &gt;&gt;&gt; print &#x27;(cut and pasted from interactive Python sessions)&#x27; (cut and pasted from interactive Python sessions)
<span class="r5"> • </span>Two syntaxes for tables:  Grid tables; complete, but complex and verbose:  
+------------------------+------------+----------+ | Header row, column 1   | Header 2   | Header 3 | 
+========================+============+==========+ | body row 1, column 1   | column 2   | column 3 | 
+------------------------+------------+----------+ | body row 2             | Cells may span        | 
+------------------------+-----------------------+  Simple tables; easy and compact, but limited:  ==================== 
==========  ========== Header row, column 1  Header 2    Header 3 ====================  ==========  ========== body row 
1, column 1  column 2    column 3 body row 2            Cells may span columns ====================  
======================
  <span class="r5"> ∘ </span>Explicit markup blocks all begin with an explicit block marker, two periods and a space:
  <span class="r5"> ∘ </span>Footnotes:  .. [1] A footnote contains body elements, consistently    indented by at least 3 spaces.  Citations:  .
[CIT2002] Just like a footnote, except the label is    textual.  Hyperlink targets:  .. _Python: https://www.python.org 
.. _example:  The &quot;_example&quot; target above points to this paragraph.  Directives:  .. image:: mylogo.png  Substitution 
definitions:  .. |symbol here| image:: symbol.png  Comments:  .. Comments begin with two dots and a space.  Anything may
follow, except for the syntax of footnotes/citations,    hyperlink targets, directives, or substitution definitions.
    <span class="r5"> ▪ </span>Footnotes:  .. [1] A footnote contains body elements, consistently    indented by at least 3 spaces.
    <span class="r5"> ▪ </span>Citations:  .. [CIT2002] Just like a footnote, except the label is    textual.
    <span class="r5"> ▪ </span>Hyperlink targets:  .. _Python: https://www.python.org  .. _example:  The &quot;_example&quot; target above points to this 
paragraph.
    <span class="r5"> ▪ </span>Directives:  .. image:: mylogo.png
    <span class="r5"> ▪ </span>Substitution definitions:  .. |symbol here| image:: symbol.png
    <span class="r5"> ▪ </span>Comments:  .. Comments begin with two dots and a space.  Anything may    follow, except for the syntax of 
footnotes/citations,    hyperlink targets, directives, or substitution definitions.
<span class="r5"> • </span>Comments:  .. Comments begin with two dots and a space.  Anything may    follow, except for the syntax of 
footnotes/citations,    hyperlink targets, directives, or substitution definitions.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Syntax Details                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Descriptions below list &quot;doctree elements&quot; (document tree element names; XML DTD generic identifiers) corresponding to </span>
<span class="r4">syntax constructs.  For details on the hierarchy of elements, please see </span><a class="r3" href="../doctree.html">The Docutils Document Tree</a><span class="r4"> and the </span><a class="r3" href="../docutils.dtd">Docutils </a>
<a class="r3" href="../docutils.dtd">Generic DTD</a><span class="r4"> XML document type definition.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Whitespace                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Spaces are recommended for </span><span class="r3">indentation</span><span class="r4">, but tabs may also be used. Tabs will be converted to spaces.  Tab stops are at </span>
<span class="r4">every 8th column (processing systems may make this value configurable).</span>

<span class="r4">Other whitespace characters (form feeds [chr(12)] and vertical tabs [chr(11)]) are converted to single spaces before </span>
<span class="r4">processing.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Blank Lines                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Blank lines are used to separate paragraphs and other elements. Multiple successive blank lines are equivalent to a </span>
<span class="r4">single blank line, except within literal blocks (where all whitespace is preserved). Blank lines may be omitted when the</span>
<span class="r4">markup makes element separation unambiguous, in conjunction with indentation.  The first line of a document is treated </span>
<span class="r4">as if it is preceded by a blank line, and the last line of a document is treated as if it is followed by a blank line.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Indentation                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Indentation is used to indicate -- and is only significant in indicating -- block quotes, definitions (in </span><span class="r3">definition </span>
<span class="r3">lists</span><span class="r4">), and local nested content:</span>

<span class="r5"> • </span>list item content (multi-line contents of list items, and multiple body elements within a list item, including nested
lists),
<span class="r5"> • </span>the content of literal blocks, and
<span class="r5"> • </span>the content of explicit markup blocks (directives, footnotes, ...).

<span class="r4">Any text whose indentation is less than that of the current level (i.e., unindented text or &quot;dedents&quot;) ends the current </span>
<span class="r4">level of indentation.</span>

<span class="r4">Since all indentation is significant, the level of indentation must be consistent.  For example, indentation is the sole</span>
<span class="r4">markup indicator for </span><span class="r3">block quotes</span><span class="r4">:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> a top</span><span class="r8">-</span><span class="r7">level paragraph</span><span class="r8">.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    This paragraph belongs to a first</span><span class="r8">-</span><span class="r7">level block quote</span><span class="r8">.</span><span class="r9">                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Paragraph </span><span class="r10">2</span><span class="r7"> of the first</span><span class="r8">-</span><span class="r7">level block quote</span><span class="r8">.</span><span class="r9">                                                                     </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Multiple levels of indentation within a block quote will result in more complex structures:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> a top</span><span class="r8">-</span><span class="r7">level paragraph</span><span class="r8">.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    This paragraph belongs to a first</span><span class="r8">-</span><span class="r7">level block quote</span><span class="r8">.</span><span class="r9">                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        This paragraph belongs to a second</span><span class="r8">-</span><span class="r7">level block quote</span><span class="r8">.</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Another top</span><span class="r8">-</span><span class="r7">level paragraph</span><span class="r8">.</span><span class="r9">                                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        This paragraph belongs to a second</span><span class="r8">-</span><span class="r7">level block quote</span><span class="r8">.</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    This paragraph belongs to a first</span><span class="r8">-</span><span class="r7">level block quote</span><span class="r8">.</span><span class="r7">  The</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    second</span><span class="r8">-</span><span class="r7">level block quote above </span><span class="r8">is</span><span class="r7"> inside this first</span><span class="r8">-</span><span class="r7">level</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    block quote</span><span class="r8">.</span><span class="r9">                                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">When a paragraph or other construct consists of more than one line of text, the lines must be left-aligned:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> a paragraph</span><span class="r8">.</span><span class="r7">  The lines of</span><span class="r9">                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">this paragraph are aligned at the left</span><span class="r8">.</span><span class="r9">                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    This paragraph has problems</span><span class="r8">.</span><span class="r7">  The</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">lines are </span><span class="r8">not</span><span class="r7"> left</span><span class="r8">-</span><span class="r7">aligned</span><span class="r8">.</span><span class="r7">  In addition</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  to potential misinterpretation, warning</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">and/or</span><span class="r7"> error messages will be generated</span><span class="r9">                                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  by the parser</span><span class="r8">.</span><span class="r9">                                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Several constructs begin with a marker, and the body of the construct must be indented relative to the marker.  For </span>
<span class="r4">constructs using simple markers (</span><span class="r3">bullet lists</span><span class="r4">, </span><span class="r3">enumerated lists</span><span class="r4">), the level of indentation of the body is determined by </span>
<span class="r4">the position of the first line of text. For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> the first line of a bullet list</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  item</span><span class="r11">&#x27;s paragraph.  All lines must align</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  relative to the first line</span><span class="r8">.</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">      This indented paragraph </span><span class="r8">is</span><span class="r7"> interpreted</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">      </span><span class="r12">as</span><span class="r7"> a block quote</span><span class="r8">.</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  Another paragraph belonging to the first list item</span><span class="r8">.</span><span class="r9">                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7"> Because it </span><span class="r8">is</span><span class="r7"> </span><span class="r8">not</span><span class="r7"> sufficiently indented,</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7"> this paragraph does </span><span class="r8">not</span><span class="r7"> belong to the list</span><span class="r9">                                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7"> item (it</span><span class="r11">&#x27;s a block quote following the list).</span><span class="r9">                                                                      </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The body of </span><span class="r3">explicit markup blocks</span><span class="r4">, </span><span class="r3">field lists</span><span class="r4">, and </span><span class="r3">option lists</span><span class="r4"> ends above the first line with the same or less </span>
<span class="r4">indentation than the marker.  For example, field lists may have very long markers (containing the field names):</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">:Hello: This field has a short field name, so aligning the field</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        body </span><span class="r12">with</span><span class="r7"> the first line </span><span class="r8">is</span><span class="r7"> feasible</span><span class="r8">.</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:Number</span><span class="r8">-</span><span class="r7">of</span><span class="r8">-</span><span class="r7">African</span><span class="r8">-</span><span class="r7">swallows</span><span class="r8">-</span><span class="r7">required</span><span class="r8">-</span><span class="r7">to</span><span class="r8">-</span><span class="r7">carry</span><span class="r8">-</span><span class="r7">a</span><span class="r8">-</span><span class="r7">coconut: It would</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    be very difficult to align the field body </span><span class="r12">with</span><span class="r7"> the left edge</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    of the first line</span><span class="r8">.</span><span class="r7">  It may even be preferable </span><span class="r8">not</span><span class="r7"> to begin the</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    body on the same line </span><span class="r12">as</span><span class="r7"> the marker</span><span class="r8">.</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Escaping Mechanism                                                  ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">The character set universally available to plaintext documents, 7-bit ASCII, is limited.  No matter what characters are </span>
<span class="r4">used for markup, they will already have multiple meanings in written text.  Therefore markup characters will sometimes </span>
<span class="r4">appear in text without being intended as markup.  Any serious markup system requires an escaping mechanism to override </span>
<span class="r4">the default meaning of the characters used for the markup.  In reStructuredText we use the </span><span class="r13">backslash</span><span class="r4">, commonly used as </span>
<span class="r4">an escaping character in other domains.</span>

<span class="r4">A backslash (</span><span class="r14">\</span><span class="r4">) escapes the following character.</span>

<span class="r5"> • </span>&quot;Escaping&quot; backslash characters are represented by NULL characters in the Document Tree and removed from the output 
document by the Docutils writers.
<span class="r5"> • </span>Escaped non-white characters are prevented from playing a role in any markup interpretation. The escaped character 
represents the character itself. (A literal backslash can be specified by two backslashes in a row -- the first 
backslash escapes the second. )
<span class="r5"> • </span>Escaped whitespace characters are removed from the output document together with the escaping backslash. This allows 
character-level inline markup.  In URI context , backslash-escaped whitespace represents a single space.

<span class="r4">Backslashes have no special meaning in literal context . Here, a single backslash represents a literal backslash, </span>
<span class="r4">without having to double up. </span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Reference Names                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Reference names identify elements for cross-referencing.</span>

<span class="r2">╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮</span>
<span class="r2">│ References to a target position in external, generated documents must use the auto-generated identifier key which    │</span>
<span class="r2">│ may differ from the reference name due to restrictions on identifiers/labels in the output format.                   │</span>
<span class="r2">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r4">Simple reference names are single words consisting of alphanumerics plus isolated (no two adjacent) internal hyphens, </span>
<span class="r4">underscores, periods, colons and plus signs; no whitespace or other characters are allowed.  Footnote labels (</span><span class="r3">Footnotes</span><span class="r4"> </span>
<span class="r4">&amp; </span><span class="r3">Footnote References</span><span class="r4">), citation labels (</span><span class="r3">Citations</span><span class="r4"> &amp; </span><span class="r3">Citation References</span><span class="r4">), </span><span class="r3">interpreted text</span><span class="r4"> roles, and some </span><span class="r3">hyperlink </span>
<span class="r3">references</span><span class="r4"> use the simple reference name syntax.</span>

<span class="r4">Reference names using punctuation or whose names are phrases (two or more space-separated words) are called </span>
<span class="r4">&quot;phrase-references&quot;. Phrase-references are expressed by enclosing the phrase in backquotes and treating the backquoted </span>
<span class="r4">text as a reference name:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Want to learn about </span><span class="r15">`</span><span class="r7">my favorite programming language</span><span class="r15">`</span><span class="r7">_</span><span class="r15">?</span><span class="r9">                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> _my favorite programming language: https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org</span><span class="r9">                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Simple reference names may also optionally use backquotes.</span>

<span class="r4">Reference names are whitespace-neutral and case-insensitive.  When resolving reference names internally:</span>

<span class="r5"> • </span>whitespace is normalized (one or more spaces, horizontal or vertical tabs, newlines, carriage returns, or form feeds,
are interpreted as a single space), and
<span class="r5"> • </span>case is normalized (all alphabetic characters are converted to lowercase).

<span class="r4">For example, the following </span><span class="r3">hyperlink references</span><span class="r4"> are equivalent:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> </span><span class="r15">`</span><span class="r7">A HYPERLINK</span><span class="r15">`</span><span class="r7">_</span><span class="r9">                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> </span><span class="r15">`</span><span class="r7">a    hyperlink</span><span class="r15">`</span><span class="r7">_</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> </span><span class="r15">`</span><span class="r7">A</span><span class="r9">                                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  Hyperlink</span><span class="r15">`</span><span class="r7">_</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r3">Hyperlinks</span><span class="r4">, </span><span class="r3">footnotes</span><span class="r4">, and </span><span class="r3">citations</span><span class="r4"> all share the same namespace for reference names.  The labels of citations (simple </span>
<span class="r4">reference names) and manually-numbered footnotes (numbers) are entered into the same database as other hyperlink names. </span>
<span class="r4">This means that a </span><span class="r3">footnote</span><span class="r4"> (defined as &quot;</span><span class="r16">.. [#note]</span><span class="r4">&quot;) which can be referred to by a footnote reference (</span><span class="r16">[#note]_</span><span class="r4">), can </span>
<span class="r4">also be referred to by a plain hyperlink reference (</span><span class="r16">note_</span><span class="r4">).  Of course, each type of reference (hyperlink, footnote, </span>
<span class="r4">citation) may be processed and rendered differently.  Some care should be taken to avoid reference name conflicts.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Document Structure                                                  ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Document                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#document">document</a><span class="r4">.</span>

<span class="r4">The top-level element of a parsed reStructuredText document is the &quot;document&quot; element.  After initial parsing, the </span>
<span class="r4">document element is a simple container for a document fragment, consisting of </span><span class="r3">body elements</span><span class="r4">, </span><span class="r3">transitions</span><span class="r4">, and </span><span class="r3">sections</span><span class="r4">, </span>
<span class="r4">but lacking a document title or other bibliographic elements.  The code that calls the parser may choose to run one or </span>
<span class="r4">more optional post-parse </span><a class="r3" href="https://docutils.sourceforge.io/docutils/transforms/">transforms</a><span class="r4">, rearranging the document fragment into a complete document with a title and </span>
<span class="r4">possibly other metadata elements (author, date, etc.; see </span><span class="r3">Bibliographic Fields</span><span class="r4">).</span>

<span class="r4">Specifically, there is no way to indicate a document title and subtitle explicitly in reStructuredText.  Instead, a lone</span>
<span class="r4">top-level section title (see </span><span class="r3">Sections</span><span class="r4"> below) can be treated as the document title.  Similarly, a lone second-level </span>
<span class="r4">section title immediately after the &quot;document title&quot; can become the document subtitle.  The rest of the sections are </span>
<span class="r4">then lifted up a level or two.  See the </span><span class="r3">DocTitle transform</span><span class="r4"> for details.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Sections                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#section">section</a><span class="r4">, </span><a class="r3" href="../doctree.html#title">title</a><span class="r4">.</span>

<span class="r4">Sections are identified through their titles, which are marked up with adornment: &quot;underlines&quot; below the title text, or </span>
<span class="r4">underlines and matching &quot;overlines&quot; above the title.  An underline/overline is a single repeated punctuation character </span>
<span class="r4">that begins in column 1 and forms a line extending at least as far as the right edge of the title text.   Specifically, </span>
<span class="r4">an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character .  When an overline is used,</span>
<span class="r4">the length and character used must match the underline.  Underline-only adornment styles are distinct from </span>
<span class="r4">overline-and-underline styles that use the same character.  There may be any number of levels of section titles, </span>
<span class="r4">although some output formats may have limits (HTML has 6 levels).</span>

<span class="r4">Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as</span>
<span class="r4">encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle,</span>
<span class="r4">the third will be a subsubtitle, and so on.</span>

<span class="r4">Below are examples of section title styles:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">===============</span><span class="r9">                                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7"> Section Title</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">===============</span><span class="r9">                                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">---------------</span><span class="r9">                                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7"> Section Title</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">---------------</span><span class="r9">                                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=============</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-------------</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r15">`````````````</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r11">&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;&#x27;</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">.............</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">~~~~~~~~~~~~~</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">*************</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+++++++++++++</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Section Title</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">^^^^^^^^^^^^^</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">When a title has both an underline and an overline, the title text may be inset, as in the first two examples above.  </span>
<span class="r4">This is merely aesthetic and not significant.  Underline-only title text may </span><span class="r13">not</span><span class="r4"> be inset.</span>

<span class="r4">A blank line after a title is optional.  All text blocks up to the next title of the same or higher level are included </span>
<span class="r4">in a section (or subsection, etc.).</span>

<span class="r4">All section title styles need not be used, nor need any specific section title style be used.  However, a document must </span>
<span class="r4">be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that </span>
<span class="r4">hierarchy.</span>

<span class="r4">Each section title automatically generates a hyperlink target pointing to the section.  The text of the hyperlink target</span>
<span class="r4">(the &quot;reference name&quot;) is the same as that of the section title.  See </span><span class="r3">Implicit Hyperlink Targets</span><span class="r4"> for a complete </span>
<span class="r4">description.</span>

<span class="r4">Sections may contain </span><span class="r3">body elements</span><span class="r4">, </span><span class="r3">transitions</span><span class="r4">, and nested sections.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Transitions                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#transition">transition</a><span class="r4">.</span>

<span class="r17">▌ </span><span class="r18">Instead of subheads, extra space or a type ornament between</span>
<span class="r18">paragraphs may be used to mark text divisions or to signal</span>
<span class="r18">changes in subject or emphasis.</span>
<span class="r19">  - (The Chicago Manual of Style, 14th edition, section 1.80)</span><span class="r4">Transitions are commonly seen in novels and short fiction, </span>
<span class="r4">as a gap spanning one or more lines, with or without a type ornament such as a row of asterisks.  Transitions separate </span>
<span class="r4">other body elements.  A transition should not begin or end a section or document, nor should two transitions be </span>
<span class="r4">immediately adjacent.The syntax for a transition marker is a horizontal line of 4 or more repeated punctuation </span>
<span class="r4">characters.  The syntax is the same as section title underlines without title text.  Transition markers require blank </span>
<span class="r4">lines before and after:</span>

<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Para</span><span class="r8">.</span><span class="r9">                                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">----------</span><span class="r9">                                                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">Para</span><span class="r8">.</span><span class="r9">                                                                                                               </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Unlike section title underlines, no hierarchy of transition markers is enforced, nor do differences in transition </span>
<span class="r4">markers accomplish anything.  It is recommended that a single consistent style be used.</span>

<span class="r4">The processing system is free to render transitions in output in any way it likes.  For example, horizontal rules (</span><span class="r14">&lt;hr&gt;</span><span class="r4">)</span>
<span class="r4">in HTML output would be an obvious choice.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Body Elements                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Paragraphs                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#paragraph">paragraph</a><span class="r4">.</span>

<span class="r4">Paragraphs consist of blocks of left-aligned text with no markup indicating any other body element.  Blank lines </span>
<span class="r4">separate paragraphs from each other and from other body elements.  Paragraphs may contain </span><span class="r3">inline markup</span><span class="r4">.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> paragraph                    </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7">                              </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> paragraph                    </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7">                              </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Bullet Lists                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#bullet-list">bullet_list</a><span class="r4">, </span><span class="r3">list_item</span><span class="r4">.</span>

<span class="r4">A text block which begins with a &quot;*&quot;, &quot;+&quot;, &quot;-&quot;, &quot;â€¢&quot;, &quot;â€£&quot;, or &quot;âƒ&quot;, followed by whitespace, is a bullet list item </span>
<span class="r4">(a.k.a. &quot;unordered&quot; list item).  List item bodies must be left-aligned and indented relative to the bullet; the text </span>
<span class="r4">immediately after the bullet determines the indentation.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> the first bullet list item</span><span class="r8">.</span><span class="r7">  The blank line above the</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  first list item </span><span class="r8">is</span><span class="r7"> required; blank lines between list items</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  (such </span><span class="r12">as</span><span class="r7"> below this paragraph) are optional</span><span class="r8">.</span><span class="r9">                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> the first paragraph </span><span class="r8">in</span><span class="r7"> the second item </span><span class="r8">in</span><span class="r7"> the list</span><span class="r8">.</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  This </span><span class="r8">is</span><span class="r7"> the second paragraph </span><span class="r8">in</span><span class="r7"> the second item </span><span class="r8">in</span><span class="r7"> the list</span><span class="r8">.</span><span class="r9">                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  The blank line above this paragraph </span><span class="r8">is</span><span class="r7"> required</span><span class="r8">.</span><span class="r7">  The left edge</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  of this paragraph lines up </span><span class="r12">with</span><span class="r7"> the paragraph above, both</span><span class="r9">                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  indented relative to the bullet</span><span class="r8">.</span><span class="r9">                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  </span><span class="r8">-</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> a sublist</span><span class="r8">.</span><span class="r7">  The bullet lines up </span><span class="r12">with</span><span class="r7"> the left edge of</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    the text blocks above</span><span class="r8">.</span><span class="r7">  A sublist </span><span class="r8">is</span><span class="r7"> a new list so requires a</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    blank line above </span><span class="r8">and</span><span class="r7"> below</span><span class="r8">.</span><span class="r9">                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> the third item of the main list</span><span class="r8">.</span><span class="r9">                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">This paragraph </span><span class="r8">is</span><span class="r7"> </span><span class="r8">not</span><span class="r7"> part of the list</span><span class="r8">.</span><span class="r9">                                                                             </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Here are examples of </span><span class="r20">incorrectly</span><span class="r4"> formatted bullet lists:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> This first line </span><span class="r8">is</span><span class="r7"> fine</span><span class="r8">.</span><span class="r9">                                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">A blank line </span><span class="r8">is</span><span class="r7"> required between list items </span><span class="r8">and</span><span class="r7"> paragraphs</span><span class="r8">.</span><span class="r9">                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">(</span><span class="r21">Warning</span><span class="r7">)</span><span class="r9">                                                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7"> The following line appears to be a new sublist, but it </span><span class="r8">is</span><span class="r7"> </span><span class="r8">not</span><span class="r7">:</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  </span><span class="r8">-</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> a paragraph continuation, </span><span class="r8">not</span><span class="r7"> a sublist (since there</span><span class="r11">&#x27;s</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    no blank line)</span><span class="r8">.</span><span class="r7">  This line </span><span class="r8">is</span><span class="r7"> also incorrectly indented</span><span class="r8">.</span><span class="r9">                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  </span><span class="r8">-</span><span class="r7"> Warnings may be issued by the implementation</span><span class="r8">.</span><span class="r9">                                                                   </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------+-----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;- &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> list item             </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">      </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">       </span><span class="r8">+-----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Enumerated Lists                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#enumerated-list">enumerated_list</a><span class="r4">, </span><a class="r3" href="../doctree.html#list-item">list_item</a><span class="r4">.</span>

<span class="r4">Enumerated lists (a.k.a. &quot;ordered&quot; lists) are similar to bullet lists, but use enumerators instead of bullets.  An </span>
<span class="r4">enumerator consists of an enumeration sequence member and formatting, followed by whitespace. The following enumeration </span>
<span class="r4">sequences are recognized:</span>

<span class="r5"> • </span>arabic numerals: 1, 2, 3, ... (no upper limit).
<span class="r5"> • </span>uppercase alphabet characters: A, B, C, ..., Z.
<span class="r5"> • </span>lower-case alphabet characters: a, b, c, ..., z.
<span class="r5"> • </span>uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
<span class="r5"> • </span>lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).

<span class="r4">In addition, the auto-enumerator, &quot;#&quot;, may be used to automatically enumerate a list.  Auto-enumerated lists may begin </span>
<span class="r4">with explicit enumeration, which sets the sequence.  Fully auto-enumerated lists use arabic numerals and begin with 1.  </span>
<span class="r4">(Auto-enumerated lists are new in Docutils 0.3.8.)</span>

<span class="r4">The following formatting types are recognized:</span>

<span class="r5"> • </span>suffixed with a period: &quot;1.&quot;, &quot;A.&quot;, &quot;a.&quot;, &quot;I.&quot;, &quot;i.&quot;.
<span class="r5"> • </span>surrounded by parentheses: &quot;(1)&quot;, &quot;(A)&quot;, &quot;(a)&quot;, &quot;(I)&quot;, &quot;(i)&quot;.
<span class="r5"> • </span>suffixed with a right-parenthesis: &quot;1)&quot;, &quot;A)&quot;, &quot;a)&quot;, &quot;I)&quot;, &quot;i)&quot;.

<span class="r4">While parsing an enumerated list, a new list will be started whenever:</span>

<span class="r5"> • </span>An enumerator is encountered which does not have the same format and sequence type as the current list (e.g. &quot;1.&quot;, &quot;(
produces two separate lists).
<span class="r5"> • </span>The enumerators are not in sequence (e.g., &quot;1.&quot;, &quot;3.&quot; produces two separate lists).

<span class="r4">It is recommended that the enumerator of the first list item be ordinal-1 (&quot;1&quot;, &quot;A&quot;, &quot;a&quot;, &quot;I&quot;, or &quot;i&quot;).  Although other </span>
<span class="r4">start-values will be recognized, they may not be supported by the output format.  A level-1 [info] system message will </span>
<span class="r4">be generated for any list beginning with a non-ordinal-1 enumerator.</span>

<span class="r4">Lists using Roman numerals must begin with &quot;I&quot;/&quot;i&quot; or a multi-character value, such as &quot;II&quot; or &quot;XV&quot;.  Any other </span>
<span class="r4">single-character Roman numeral (&quot;V&quot;, &quot;X&quot;, &quot;L&quot;, &quot;C&quot;, &quot;D&quot;, &quot;M&quot;) will be interpreted as a letter of the alphabet, not as a </span>
<span class="r4">Roman numeral. Likewise, lists using letters of the alphabet may not begin with &quot;I&quot;/&quot;i&quot;, since these are recognized as </span>
<span class="r4">Roman numeral 1.</span>

<span class="r4">The second line of each enumerated list item is checked for validity. This is to prevent ordinary paragraphs from being </span>
<span class="r4">mistakenly interpreted as list items, when they happen to begin with text identical to enumerators.  For example, this </span>
<span class="r4">text is parsed as an ordinary paragraph:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">A</span><span class="r8">.</span><span class="r7"> Einstein was a really</span><span class="r9">                                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">smart dude</span><span class="r8">.</span><span class="r9">                                                                                                         </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">However, ambiguity cannot be avoided if the paragraph consists of only one line.  This text is parsed as an enumerated </span>
<span class="r4">list item:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">A</span><span class="r8">.</span><span class="r7"> Einstein was a really smart dude</span><span class="r8">.</span><span class="r9">                                                                                </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">If a single-line paragraph begins with text identical to an enumerator (&quot;A.&quot;, &quot;1.&quot;, &quot;(b)&quot;, &quot;I)&quot;, etc.), the first </span>
<span class="r4">character will have to be escaped in order to have the line parsed as an ordinary paragraph:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">\A</span><span class="r8">.</span><span class="r7"> Einstein was a really smart dude</span><span class="r8">.</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Examples of nested enumerated lists:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r10">1.</span><span class="r7"> Item </span><span class="r10">1</span><span class="r7"> initial text</span><span class="r8">.</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   a) Item </span><span class="r10">1</span><span class="r7">a</span><span class="r8">.</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   b) Item </span><span class="r10">1</span><span class="r7">b</span><span class="r8">.</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r10">2.</span><span class="r7"> a) Item </span><span class="r10">2</span><span class="r7">a</span><span class="r8">.</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   b) Item </span><span class="r10">2</span><span class="r7">b</span><span class="r8">.</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Example syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+-------+----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;1. &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> list item            </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">     </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Definition Lists                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#definition-list">definition_list</a><span class="r4">, </span><a class="r3" href="../doctree.html#definition-list-item">definition_list_item</a><span class="r4">, </span><a class="r3" href="../doctree.html#term">term</a><span class="r4">, </span><a class="r3" href="../doctree.html#classifier">classifier</a><span class="r4">, </span><a class="r3" href="../doctree.html#definition">definition</a><span class="r4">.</span>

<span class="r4">Each definition list item contains a term, optional classifiers, and a definition.</span>

<span class="r5"> • </span>A term is a simple one-line word or phrase.  Escape a leading hyphen to prevent recognition as an option list item.
<span class="r5"> • </span>Optional classifiers may follow the term on the same line, each after an inline &quot; : &quot; (space, colon, space).  Inline 
markup is parsed in the term line before the classifier delimiters are recognized.  A delimiter will only be recognized 
if it appears outside of any inline markup.
<span class="r5"> • </span>A definition is a block indented relative to the term, and may contain multiple paragraphs and other body elements.  
There may be no blank line between a term line and a definition block (this distinguishes definition lists from block 
quotes). Blank lines are required before the first and after the last definition list item, but are optional in-between.

<span class="r4">Example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">term </span><span class="r10">1</span><span class="r9">                                                                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Definition </span><span class="r10">1.</span><span class="r9">                                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">term </span><span class="r10">2</span><span class="r9">                                                                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Definition </span><span class="r10">2</span><span class="r7">, paragraph </span><span class="r10">1.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Definition </span><span class="r10">2</span><span class="r7">, paragraph </span><span class="r10">2.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">term </span><span class="r10">3</span><span class="r7"> : classifier</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Definition </span><span class="r10">3.</span><span class="r9">                                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">term </span><span class="r10">4</span><span class="r7"> : classifier one : classifier two</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Definition </span><span class="r10">4.</span><span class="r9">                                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">\</span><span class="r8">-</span><span class="r7">term </span><span class="r10">5</span><span class="r9">                                                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Without escaping, this would be an option list item</span><span class="r8">.</span><span class="r9">                                                            </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">A definition list may be used in various ways, including:</span>

<span class="r5"> • </span>As a dictionary or glossary.  The term is the word itself, a classifier may be used to indicate the usage of the term
(noun, verb, etc.), and the definition follows.
<span class="r5"> • </span>To describe program variables.  The term is the variable name, a classifier may be used to indicate the type of the 
variable (string, integer, etc.), and the definition describes the variable&#x27;s use in the program.  This usage of 
definition lists supports the classifier syntax of Grouch, a system for describing and enforcing a Python object schema.

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+----------------------------+</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> term [ </span><span class="r11">&quot; : &quot;</span><span class="r7"> classifier ]</span><span class="r8">*</span><span class="r7"> </span><span class="r8">|</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--+-------------------------+--+</span><span class="r9">                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7"> definition                 </span><span class="r8">|</span><span class="r9">                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">           </span><span class="r8">|</span><span class="r9">                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">+----------------------------+</span><span class="r9">                                                                                   </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Field Lists                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#field-list">field_list</a><span class="r4">, </span><a class="r3" href="../doctree.html#field">field</a><span class="r4">, </span><a class="r3" href="../doctree.html#field-name">field_name</a><span class="r4">, </span><a class="r3" href="../doctree.html#field-body">field_body</a><span class="r4">.</span>

<span class="r4">Field lists are used as part of an extension syntax, such as options for </span><span class="r3">directives</span><span class="r4">, or database-like records meant for </span>
<span class="r4">further processing.  They may also be used for two-column table-like structures resembling database records (label &amp; </span>
<span class="r4">data pairs). Applications of reStructuredText may recognize field names and transform fields or field bodies in certain </span>
<span class="r4">contexts.  For examples, see </span><span class="r3">Bibliographic Fields</span><span class="r4"> below, or the &quot;</span><span class="r3">image</span><span class="r4">&quot; and &quot;</span><a class="r3" href="directives.html#metadata">meta</a><span class="r4">&quot; directives in </span><span class="r3">reStructuredText </span>
<span class="r3">Directives</span><span class="r4">.</span>

<span class="r4">Field lists are mappings from </span><span class="r13">field names</span><span class="r4"> to </span><span class="r13">field bodies</span><span class="r4">, modeled on </span><span class="r3">RFC822</span><span class="r4"> headers.  A field name may consist of any </span>
<span class="r4">characters, but colons (&quot;:&quot;) inside of field names must be backslash-escaped when followed by whitespace. Inline markup </span>
<span class="r4">is parsed in field names, but care must be taken when using </span><span class="r3">interpreted text</span><span class="r4"> with explicit roles in field names: the </span>
<span class="r4">role must be a suffix to the interpreted text.  Field names are case-insensitive when further processed or transformed. </span>
<span class="r4">The field name, along with a single colon prefix and suffix, together form the field marker.  The field marker is </span>
<span class="r4">followed by whitespace and the field body.  The field body may contain multiple body elements, indented relative to the </span>
<span class="r4">field marker.  The first line after the field name marker determines the indentation of the field body.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">:Date: </span><span class="r10">2001</span><span class="r8">-</span><span class="r10">08</span><span class="r8">-</span><span class="r10">16</span><span class="r9">                                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:Version: </span><span class="r10">1</span><span class="r9">                                                                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:Authors: </span><span class="r8">-</span><span class="r7"> Me</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">          </span><span class="r8">-</span><span class="r7"> Myself</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">          </span><span class="r8">-</span><span class="r7"> I</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:Indentation: Since the field marker may be quite long, the second</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">and</span><span class="r7"> subsequent lines of the field body do </span><span class="r8">not</span><span class="r7"> have to line up</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r12">with</span><span class="r7"> the first line, but they must be indented relative to the</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   field name marker, </span><span class="r8">and</span><span class="r7"> they must line up </span><span class="r12">with</span><span class="r7"> each other</span><span class="r8">.</span><span class="r9">                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:Parameter i: integer</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The interpretation of individual words in a multi-word field name is up to the application.  The application may specify</span>
<span class="r4">a syntax for the field name.  For example, second and subsequent words may be treated as &quot;arguments&quot;, quoted phrases may</span>
<span class="r4">be treated as a single argument, and direct support for the &quot;name=value&quot; syntax may be added.</span>

<span class="r4">Standard </span><a class="r3" href="https://www.rfc-editor.org/rfc/rfc822.txt">RFC822</a><span class="r4"> headers cannot be used for this construct because they are ambiguous.  A word followed by a colon at the</span>
<span class="r4">beginning of a line is common in written text.  However, in well-defined contexts such as when a field list invariably </span>
<span class="r4">occurs at the beginning of a document (PEPs and email messages), standard RFC822 headers could be used.</span>

<span class="r4">Syntax diagram (simplified):</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+--------------------+----------------------+</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;:&quot;</span><span class="r7"> field name </span><span class="r11">&quot;:&quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> field body           </span><span class="r8">|</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+------------+</span><span class="r7">                      </span><span class="r8">|</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">                  </span><span class="r8">|</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+-----------------------------------+</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Bibliographic Fields                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><span class="r3">docinfo</span><span class="r4">, </span><a class="r3" href="../doctree.html#address">address</a><span class="r4">, </span><a class="r3" href="../doctree.html#author">author</a><span class="r4">, </span><a class="r3" href="../doctree.html#authors">authors</a><span class="r4">, </span><a class="r3" href="../doctree.html#contact">contact</a><span class="r4">, </span><a class="r3" href="../doctree.html#copyright">copyright</a><span class="r4">, </span><a class="r3" href="../doctree.html#date">date</a><span class="r4">, </span><a class="r3" href="../doctree.html#organization">organization</a><span class="r4">, </span><a class="r3" href="../doctree.html#revision">revision</a><span class="r4">, </span><a class="r3" href="../doctree.html#status">status</a><span class="r4">, </span><a class="r3" href="../doctree.html#topic">topic</a><span class="r4">, </span>
<a class="r3" href="../doctree.html#version">version</a><span class="r4">.</span>

<span class="r4">When a field list is the first element in a document (after the document title, if there is one) , it may have its </span>
<span class="r4">fields transformed to document bibliographic data.  This bibliographic data corresponds to the front matter of a book, </span>
<span class="r4">such as the title page and copyright page.</span>

<span class="r4">Certain registered field names (listed below) are recognized and transformed to the corresponding doctree elements, most</span>
<span class="r4">becoming child elements of the </span><a class="r3" href="../doctree.html#docinfo">docinfo</a><span class="r4"> element.  No ordering is required of these fields, although they may be </span>
<span class="r4">rearranged to fit the document structure, as noted.  Unless otherwise indicated below, each of the bibliographic </span>
<span class="r4">elements&#x27; field bodies may contain a single paragraph only.  Field bodies may be checked for </span><span class="r3">RCS keywords</span><span class="r4"> and cleaned </span>
<span class="r4">up.  Any unrecognized fields will remain as generic fields in the docinfo element.</span>

<span class="r4">The registered bibliographic field names and their corresponding doctree elements are as follows:</span>

    <span class="r18">    Field name  doctree element  Abstract  topic  Address  address  Author  author  Authors  authors  Contact  </span>
<span class="r18">contact  Copyright  copyright  Date  date  Dedication  topic  Organization  organization  Revision  revision  Status  </span>
<span class="r18">status  Version  version</span>

<span class="r4">The &quot;Authors&quot; field may contain either: a single paragraph consisting of a list of authors, separated by &quot;;&quot; or &quot;,&quot; (&quot;;&quot;</span>
<span class="r4">is checked first, so &quot;Doe, Jane; Doe, John&quot; will work.); multiple paragraphs (one per author); or a bullet list whose </span>
<span class="r4">elements each contain a single paragraph per author. In some languages (e.g. Swedish), there is no singular/plural </span>
<span class="r4">distinction between &quot;Author&quot; and &quot;Authors&quot;, so only an &quot;Authors&quot; field is provided, and a single name is interpreted as </span>
<span class="r4">an &quot;Author&quot;.  If a single name contains a comma, end it with a semicolon to disambiguate: &quot;:Authors: Doe, Jane;&quot;.The </span>
<span class="r4">&quot;Address&quot; field is for a multi-line surface mailing address. Newlines and whitespace will be preserved.The &quot;Dedication&quot; </span>
<span class="r4">and &quot;Abstract&quot; fields may contain arbitrary body elements.  Only one of each is allowed.  They become topic elements </span>
<span class="r4">with &quot;Dedication&quot; or &quot;Abstract&quot; titles (or language equivalents) immediately following the docinfo element.This </span>
<span class="r4">field-name-to-element mapping can be replaced for other languages.  See the </span><a class="r3" href="https://docutils.sourceforge.io/docutils/transforms/frontmatter.py">DocInfo transform</a><span class="r4"> implementation </span>
<span class="r4">documentation for details.Unregistered/generic fields may contain one or more paragraphs or arbitrary body elements. The</span>
<span class="r4">field name is also used as a </span><a class="r3" href="../doctree.html#classes">&quot;classes&quot; attribute</a><span class="r4"> value after being converted into a valid identifier form.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     RCS Keywords                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r3">Bibliographic fields</span><span class="r4"> recognized by the parser are normally checked for RCS  keywords and cleaned up .  RCS keywords may </span>
<span class="r4">be entered into source files as &quot;$keyword$&quot;, and once stored under RCS, CVS , or SVN , they are expanded to &quot;$keyword: </span>
<span class="r4">expansion text $&quot;. For example, a &quot;Status&quot; field will be transformed to a &quot;status&quot; element:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">:Status: </span><span class="r15">$</span><span class="r7">keyword: expansion text </span><span class="r15">$</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Processed, the &quot;status&quot; element&#x27;s text will become simply &quot;expansion text&quot;.  The dollar sign delimiters and leading RCS </span>
<span class="r4">keyword name are removed.</span>

<span class="r4">The RCS keyword processing only kicks in when the field list is in bibliographic context (first non-comment construct in</span>
<span class="r4">the document, after a document title if there is one).</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Option Lists                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#option-list">option_list</a><span class="r4">, </span><a class="r3" href="../doctree.html#option-list-item">option_list_item</a><span class="r4">, </span><a class="r3" href="../doctree.html#option-group">option_group</a><span class="r4">, </span><a class="r3" href="../doctree.html#option">option</a><span class="r4">, </span><a class="r3" href="../doctree.html#option-string">option_string</a><span class="r4">, </span><a class="r3" href="../doctree.html#option-argument">option_argument</a><span class="r4">, </span><a class="r3" href="../doctree.html#description">description</a><span class="r4">.</span>

<span class="r4">Option lists map a program&#x27;s command-line options to descriptions documenting them.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7">a         Output all</span><span class="r8">.</span><span class="r9">                                                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7">b         Output both (this description </span><span class="r8">is</span><span class="r9">                                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">           quite long)</span><span class="r8">.</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7">c arg     Output just arg</span><span class="r8">.</span><span class="r9">                                                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">--</span><span class="r7">long     Output all day long</span><span class="r8">.</span><span class="r9">                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7">p         This option has two paragraphs </span><span class="r8">in</span><span class="r7"> the description</span><span class="r8">.</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">           This </span><span class="r8">is</span><span class="r7"> the first</span><span class="r8">.</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">           This </span><span class="r8">is</span><span class="r7"> the second</span><span class="r8">.</span><span class="r7">  Blank lines may be omitted between</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">           options (</span><span class="r12">as</span><span class="r7"> above) </span><span class="r8">or</span><span class="r7"> left </span><span class="r8">in</span><span class="r7"> (</span><span class="r12">as</span><span class="r7"> here </span><span class="r8">and</span><span class="r7"> below)</span><span class="r8">.</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">--</span><span class="r7">very</span><span class="r8">-</span><span class="r7">long</span><span class="r8">-</span><span class="r7">option  A VMS</span><span class="r8">-</span><span class="r7">style option</span><span class="r8">.</span><span class="r7">  Note the adjustment </span><span class="r12">for</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">                    the required two spaces</span><span class="r8">.</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">--</span><span class="r7">an</span><span class="r8">-</span><span class="r7">even</span><span class="r8">-</span><span class="r7">longer</span><span class="r8">-</span><span class="r7">option</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">           The description can also start on the next line</span><span class="r8">.</span><span class="r9">                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r10">2</span><span class="r7">, </span><span class="r8">--</span><span class="r7">two  This option has two variants</span><span class="r8">.</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">-</span><span class="r7">f FILE, </span><span class="r8">--</span><span class="r7">file</span><span class="r8">=</span><span class="r7">FILE  These two options are synonyms; both have</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">                      arguments</span><span class="r8">.</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">/</span><span class="r7">V         A VMS</span><span class="r8">/</span><span class="r7">DOS</span><span class="r8">-</span><span class="r7">style option</span><span class="r8">.</span><span class="r9">                                                                                  </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">There are several types of options recognized by reStructuredText:</span>

<span class="r5"> • </span>Short POSIX options consist of one dash and an option letter.
<span class="r5"> • </span>Long POSIX options consist of two dashes and an option word; some systems use a single dash.
<span class="r5"> • </span>Old GNU-style &quot;plus&quot; options consist of one plus and an option letter (&quot;plus&quot; options are deprecated now, their use 
discouraged).
<span class="r5"> • </span>DOS/VMS options consist of a slash and an option letter or word.

<span class="r4">Please note that both POSIX-style and DOS/VMS-style options may be used by DOS or Windows software.  These and other </span>
<span class="r4">variations are sometimes used mixed together.  The names above have been chosen for convenience only.</span>

<span class="r4">The syntax for short and long POSIX options is based on the syntax supported by Python&#x27;s </span><a class="r3" href="https://docs.python.org/3/library/getopt.html">getopt.py</a><span class="r4"> module, which </span>
<span class="r4">implements an option parser similar to the </span><a class="r3" href="https://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html">GNU libc getopt_long()</a><span class="r4"> function but with some restrictions.  There are many </span>
<span class="r4">variant option systems, and reStructuredText option lists do not support all of them.</span>

<span class="r4">Although long POSIX and DOS/VMS option words may be allowed to be truncated by the operating system or the application </span>
<span class="r4">when used on the command line, reStructuredText option lists do not show or support this with any special syntax.  The </span>
<span class="r4">complete option word should be given, supported by notes about truncation if and when applicable.</span>

<span class="r4">Options may be followed by an argument placeholder, whose role and syntax should be explained in the description text. </span>
<span class="r4">Either a space or an equals sign may be used as a delimiter between long options and option argument placeholders; short</span>
<span class="r4">options (&quot;-&quot; or &quot;+&quot; prefix only) use a space or omit the delimiter. Option arguments may take one of two forms:</span>

<span class="r5"> • </span>Begins with a letter ([a-zA-Z]) and subsequently consists of letters, numbers, underscores and hyphens ([a-zA-Z0-9_-]
<span class="r5"> • </span>Begins with an open-angle-bracket (&lt;) and ends with a close-angle-bracket (&gt;); any characters except angle brackets a
allowed internally.

<span class="r4">Multiple option &quot;synonyms&quot; may be listed, sharing a single description.  They must be separated by comma-space.</span>

<span class="r4">There must be at least two spaces between the option(s) and the description (which can also start on the next line).  </span>
<span class="r4">The description may contain multiple body elements. The first line after the option marker determines the indentation of</span>
<span class="r4">the description.  As with other types of lists, blank lines are required before the first option list item and after the</span>
<span class="r4">last, but are optional between option entries.</span>

<span class="r4">Syntax diagram (simplified):</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+----------------------------+-------------+</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> option [</span><span class="r11">&quot; &quot;</span><span class="r7"> argument] </span><span class="r11">&quot;  &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> description </span><span class="r8">|</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+--------------------+</span><span class="r7">             </span><span class="r8">|</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">                 </span><span class="r8">|</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+----------------------------------+</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Literal Blocks                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#literal-block">literal_block</a><span class="r4">.</span>

<span class="r4">A paragraph consisting of two colons (&quot;::&quot;) signifies that the following text block(s) comprise a literal block.  The </span>
<span class="r4">literal block must either be indented or quoted (see below).  No markup processing is done within a literal block.  It </span>
<span class="r4">is left as-is, and is typically rendered in a monospaced typeface:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> a typical paragraph</span><span class="r8">.</span><span class="r7">  An indented literal block follows</span><span class="r8">.</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">::</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r12">for</span><span class="r7"> a </span><span class="r8">in</span><span class="r7"> [</span><span class="r10">5</span><span class="r7">,</span><span class="r10">4</span><span class="r7">,</span><span class="r10">3</span><span class="r7">,</span><span class="r10">2</span><span class="r7">,</span><span class="r10">1</span><span class="r7">]:   </span><span class="r22"># this is program code, shown as-is</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        print a</span><span class="r9">                                                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    print </span><span class="r11">&quot;it&#x27;s...&quot;</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r22"># a literal block continues until the indentation ends</span><span class="r9">                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">This text has returned to the indentation of the first paragraph,</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">is</span><span class="r7"> outside of the literal block, </span><span class="r8">and</span><span class="r7"> </span><span class="r8">is</span><span class="r7"> therefore treated </span><span class="r12">as</span><span class="r7"> an</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">ordinary paragraph</span><span class="r8">.</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The paragraph containing only &quot;::&quot; will be completely removed from the output; no empty paragraph will remain.</span>

<span class="r4">As a convenience, the &quot;::&quot; is recognized at the end of any paragraph. If immediately preceded by whitespace, both colons</span>
<span class="r4">will be removed from the output (this is the &quot;partially minimized&quot; form).  When text immediately precedes the &quot;::&quot;, </span><span class="r13">one</span><span class="r4"> </span>
<span class="r4">colon will be removed from the output, leaving only one colon visible (i.e., &quot;::&quot; will be replaced by &quot;:&quot;; this is the </span>
<span class="r4">&quot;fully minimized&quot; form).</span>

<span class="r4">In other words, these are all equivalent (please pay attention to the colons after &quot;Paragraph&quot;):</span>

<span class="r5"> 1</span> Expanded form:  Paragraph:  ::      Literal block
<span class="r5"> 2</span> Partially minimized form:  Paragraph: ::      Literal block
<span class="r5"> 3</span> Fully minimized form:  Paragraph::      Literal block

<span class="r4">All whitespace (including line breaks, but excluding minimum indentation for indented literal blocks) is preserved.  </span>
<span class="r4">Blank lines are required before and after a literal block, but these blank lines are not included as part of the literal</span>
<span class="r4">block.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Indented Literal Blocks                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Indented literal blocks are indicated by indentation relative to the surrounding text (leading whitespace on each line).</span>
<span class="r4">The minimum indentation will be removed from each line of an indented literal block.  The literal block need not be </span>
<span class="r4">contiguous; blank lines are allowed between sections of indented text.  The literal block ends with the end of the </span>
<span class="r4">indentation.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> paragraph                    </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> (ends </span><span class="r12">with</span><span class="r7"> </span><span class="r11">&quot;::&quot;</span><span class="r7">)             </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">+---------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7"> indented literal block    </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">+---------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                Quoted Literal Blocks                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Quoted literal blocks are unindented contiguous blocks of text where each line begins with the same non-alphanumeric </span>
<span class="r4">printable 7-bit ASCII character .  A blank line ends a quoted literal block.  The quoting characters are preserved in </span>
<span class="r4">the processed document.</span>

<span class="r4">Possible uses include literate programming in Haskell and email quoting:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">John Doe wrote::</span><span class="r9">                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">&gt;&gt;</span><span class="r7"> Great idea</span><span class="r15">!</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">&gt;</span><span class="r9">                                                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">&gt;</span><span class="r7"> Why didn</span><span class="r11">&#x27;t I think of that?</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">You just did</span><span class="r15">!</span><span class="r7">  ;</span><span class="r8">-</span><span class="r7">)</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> paragraph                    </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> (ends </span><span class="r12">with</span><span class="r7"> </span><span class="r11">&quot;::&quot;</span><span class="r7">)             </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;&gt;&quot;</span><span class="r7"> per</span><span class="r8">-</span><span class="r7">line</span><span class="r8">-</span><span class="r7">quoted          </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;&gt;&quot;</span><span class="r7"> contiguous literal block </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Line Blocks                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#line-block">line_block</a><span class="r4">, </span><a class="r3" href="../doctree.html#line">line</a><span class="r4">.  (New in Docutils 0.3.5.)</span>

<span class="r4">Line blocks are useful for address blocks, verse (poetry, song lyrics), and unadorned lists, where the structure of </span>
<span class="r4">lines is significant.  Line blocks are groups of lines beginning with vertical bar (&quot;|&quot;) prefixes.  Each vertical bar </span>
<span class="r4">prefix indicates a new line, so line breaks are preserved.  Initial indents are also significant, resulting in a nested </span>
<span class="r4">structure.  Inline markup is supported. Continuation lines are wrapped portions of long lines; they begin with a space </span>
<span class="r4">in place of the vertical bar.  The left edge of a continuation line must be indented, but need not be aligned with the </span>
<span class="r4">left edge of the text above it.  A line block ends with a blank line.</span>

<span class="r4">This example illustrates continuation lines:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> Lend us a couple of bob till Thursday</span><span class="r8">.</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> I</span><span class="r11">&#x27;m absolutely skint.</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> But I</span><span class="r11">&#x27;m expecting a postal order and I can pay you back</span><span class="r9">                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  </span><span class="r12">as</span><span class="r7"> soon </span><span class="r12">as</span><span class="r7"> it comes</span><span class="r8">.</span><span class="r9">                                                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> Love, Ewan</span><span class="r8">.</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">This example illustrates the nesting of line blocks, indicated by the initial indentation of new lines:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Take it away, Eric the Orchestra Leader</span><span class="r15">!</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7"> A one, two, a one two three four</span><span class="r9">                                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r9">                                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7"> Half a bee, philosophically,</span><span class="r9">                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7">     must, </span><span class="r8">*</span><span class="r7">ipso facto</span><span class="r8">*</span><span class="r7">, half </span><span class="r8">not</span><span class="r7"> be</span><span class="r8">.</span><span class="r9">                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7"> But half the bee has got to be,</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7">     </span><span class="r8">*</span><span class="r7">vis a vis</span><span class="r8">*</span><span class="r7"> its entity</span><span class="r8">.</span><span class="r7">  D</span><span class="r11">&#x27;you see?</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r9">                                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7"> But can a bee be said to be</span><span class="r9">                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7">     </span><span class="r8">or</span><span class="r7"> </span><span class="r8">not</span><span class="r7"> to be an entire bee,</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7">         when half the bee </span><span class="r8">is</span><span class="r7"> </span><span class="r8">not</span><span class="r7"> a bee,</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7">             due to some ancient injury</span><span class="r15">?</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r9">                                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">|</span><span class="r7"> Singing</span><span class="r8">...</span><span class="r9">                                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------+-----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;| &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> line                  </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------|</span><span class="r7"> continuation line     </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">       </span><span class="r8">+-----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Block Quotes                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#block-quote">block_quote</a><span class="r4">, </span><a class="r3" href="../doctree.html#attribution">attribution</a><span class="r4">.</span>

<span class="r4">A text block that is indented relative to the preceding text, without preceding markup indicating it to be a literal </span>
<span class="r4">block or other content, is a block quote.  All markup processing (for body elements and inline markup) continues within </span>
<span class="r4">the block quote:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> an ordinary paragraph, introducing a block quote</span><span class="r8">.</span><span class="r9">                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r11">&quot;It is my business to know things.  That is my trade.&quot;</span><span class="r9">                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">--</span><span class="r7"> Sherlock Holmes</span><span class="r9">                                                                                              </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">A block quote may end with an attribution: a text block beginning with </span><span class="r14">--</span><span class="r4">, </span><span class="r14">---</span><span class="r4">, or a true em-dash, flush left within the</span>
<span class="r4">block quote.  If the attribution consists of multiple lines, the left edges of the second and subsequent lines must </span>
<span class="r4">align.</span>

<span class="r4">Multiple block quotes may occur consecutively if terminated with attributions.</span>

    <span class="r18">Unindented paragraph.</span>

<span class="r3">Empty comments</span><span class="r4"> may be used to explicitly terminate preceding constructs that would otherwise consume a block quote:</span>

<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">*</span><span class="r7"> List item</span><span class="r8">.</span><span class="r9">                                                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Block quote </span><span class="r10">3.</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Empty comments may also be used to separate block quotes:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">    Block quote </span><span class="r10">4.</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    Block quote </span><span class="r10">5.</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Blank lines are required before and after a block quote, but these blank lines are not included as part of the block </span>
<span class="r4">quote.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> (current level of            </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> indentation)                 </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">+---------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7"> block quote               </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">          </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7">                           </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7"> </span><span class="r8">--</span><span class="r7"> attribution text       </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7">    (optional)             </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">+---------------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Doctest Blocks                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#doctest-block">doctest_block</a><span class="r4">.</span>

<span class="r4">Doctest blocks are interactive Python sessions cut-and-pasted into docstrings.  They are meant to illustrate usage by </span>
<span class="r4">example, and provide an elegant and powerful testing environment via the </span><a class="r3" href="https://docs.python.org/3/library/doctest.html">doctest module</a><span class="r4"> in the Python standard library.</span>

<span class="r4">Doctest blocks are text blocks which begin with </span><span class="r14">&quot;&gt;&gt;&gt; &quot;</span><span class="r4">, the Python interactive interpreter main prompt, and end with a </span>
<span class="r4">blank line. Doctest blocks are treated as a special case of literal blocks, without requiring the literal block syntax. </span>
<span class="r4">If both are present, the literal block syntax takes priority over Doctest block syntax:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> an ordinary paragraph</span><span class="r8">.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">&gt;&gt;&gt;</span><span class="r7"> print </span><span class="r11">&#x27;this is a Doctest block&#x27;</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">this </span><span class="r8">is</span><span class="r7"> a Doctest block</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">The following </span><span class="r8">is</span><span class="r7"> a literal block::</span><span class="r9">                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    </span><span class="r8">&gt;&gt;&gt;</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> </span><span class="r8">not</span><span class="r7"> recognized </span><span class="r12">as</span><span class="r7"> a doctest block by</span><span class="r9">                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    reStructuredText</span><span class="r8">.</span><span class="r7">  It </span><span class="r8">*</span><span class="r7">will</span><span class="r8">*</span><span class="r7"> be recognized by the doctest</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">    module, though</span><span class="r15">!</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Indentation is not required for doctest blocks.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Tables                                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#table">table</a><span class="r4">, </span><a class="r3" href="../doctree.html#tgroup">tgroup</a><span class="r4">, </span><a class="r3" href="../doctree.html#colspec">colspec</a><span class="r4">, </span><a class="r3" href="../doctree.html#thead">thead</a><span class="r4">, </span><a class="r3" href="../doctree.html#tbody">tbody</a><span class="r4">, </span><a class="r3" href="../doctree.html#row">row</a><span class="r4">, </span><a class="r3" href="../doctree.html#entry">entry</a><span class="r4">.</span>

<span class="r4">ReStructuredText provides two syntax variants for delineating table cells: </span><span class="r3">Grid Tables</span><span class="r4"> and </span><span class="r3">Simple Tables</span><span class="r4">. Tables are </span>
<span class="r4">also generated by the </span><a class="r3" href="directives.html#csv-table">CSV Table</a><span class="r4"> and </span><a class="r3" href="directives.html#list-table">List Table</a><span class="r4"> directives. The </span><a class="r3" href="directives.html#table">table directive</a><span class="r4"> is used to add a table title or specify </span>
<span class="r4">options.</span>

<span class="r4">As with other body elements, blank lines are required before and after tables.  Tables&#x27; left edges should align with the</span>
<span class="r4">left edge of preceding text blocks; if indented, the table is considered to be part of a block quote.</span>

<span class="r4">Once isolated, each table cell is treated as a miniature document; the top and bottom cell boundaries act as delimiting </span>
<span class="r4">blank lines.  Each cell contains zero or more body elements.  Cell contents may include left and/or right margins, which</span>
<span class="r4">are removed before processing.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Grid Tables                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Grid tables provide a complete table representation via grid-like &quot;ASCII art&quot;.  Grid tables allow arbitrary cell </span>
<span class="r4">contents (body elements), and both row and column spans.  However, grid tables can be cumbersome to produce, especially </span>
<span class="r4">for simple data sets.  The </span><span class="r3">Emacs table mode</span><span class="r4"> is a tool that allows easy editing of grid tables, in Emacs.  See </span><span class="r3">Simple </span>
<span class="r3">Tables</span><span class="r4"> for a simpler (but limited) representation.</span>

<span class="r4">Grid tables are described with a visual grid made up of the characters &quot;-&quot;, &quot;=&quot;, &quot;|&quot;, and &quot;+&quot;.  The hyphen (&quot;-&quot;) is used</span>
<span class="r4">for horizontal lines (row separators).  The equals sign (&quot;=&quot;) may be used to separate optional header rows from the </span>
<span class="r4">table body (not supported by the </span><a class="r3" href="http://table.sourceforge.net/">Emacs table mode</a><span class="r4">).  The vertical bar (&quot;|&quot;) is used for vertical lines (column </span>
<span class="r4">separators).  The plus sign (&quot;+&quot;) is used for intersections of horizontal and vertical lines.  Example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+------------------------+------------+----------+----------+</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> Header row, column </span><span class="r10">1</span><span class="r7">   </span><span class="r8">|</span><span class="r7"> Header </span><span class="r10">2</span><span class="r7">   </span><span class="r8">|</span><span class="r7"> Header </span><span class="r10">3</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> Header </span><span class="r10">4</span><span class="r7"> </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> (header rows optional) </span><span class="r8">|</span><span class="r7">            </span><span class="r8">|</span><span class="r7">          </span><span class="r8">|</span><span class="r7">          </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+========================+============+==========+==========+</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> body row </span><span class="r10">1</span><span class="r7">, column </span><span class="r10">1</span><span class="r7">   </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">2</span><span class="r7">   </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">3</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">4</span><span class="r7"> </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------+------------+----------+----------+</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> body row </span><span class="r10">2</span><span class="r7">             </span><span class="r8">|</span><span class="r7"> Cells may span columns</span><span class="r8">.</span><span class="r7">          </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------+------------+---------------------+</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> body row </span><span class="r10">3</span><span class="r7">             </span><span class="r8">|</span><span class="r7"> Cells may  </span><span class="r8">|</span><span class="r7"> </span><span class="r8">-</span><span class="r7"> Table cells       </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------+</span><span class="r7"> span rows</span><span class="r8">.</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> </span><span class="r8">-</span><span class="r7"> contain           </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> body row </span><span class="r10">4</span><span class="r7">             </span><span class="r8">|</span><span class="r7">            </span><span class="r8">|</span><span class="r7"> </span><span class="r8">-</span><span class="r7"> body elements</span><span class="r8">.</span><span class="r7">    </span><span class="r8">|</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+------------------------+------------+---------------------+</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Some care must be taken with grid tables to avoid undesired interactions with cell text in rare cases.  For example, the</span>
<span class="r4">following table contains a cell in row 2 spanning from column 2 to column 4:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">1</span><span class="r7">, col </span><span class="r10">1</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">2</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">3</span><span class="r7">  </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">4</span><span class="r7">  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">2</span><span class="r7">        </span><span class="r8">|</span><span class="r7">                                  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">3</span><span class="r7">        </span><span class="r8">|</span><span class="r7">          </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">If a vertical bar is used in the text of that cell, it could have unintended effects if accidentally aligned with column</span>
<span class="r4">boundaries:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">1</span><span class="r7">, col </span><span class="r10">1</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">2</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">3</span><span class="r7">  </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">4</span><span class="r7">  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">2</span><span class="r7">        </span><span class="r8">|</span><span class="r7"> Use the command </span><span class="r15">``</span><span class="r7">ls </span><span class="r8">|</span><span class="r7"> more</span><span class="r15">``</span><span class="r8">.</span><span class="r7">   </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">3</span><span class="r7">        </span><span class="r8">|</span><span class="r7">          </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Several solutions are possible.  All that is needed is to break the continuity of the cell outline rectangle.  One </span>
<span class="r4">possibility is to shift the text by adding an extra space before:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">1</span><span class="r7">, col </span><span class="r10">1</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">2</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">3</span><span class="r7">  </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">4</span><span class="r7">  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">2</span><span class="r7">        </span><span class="r8">|</span><span class="r7">  Use the command </span><span class="r15">``</span><span class="r7">ls </span><span class="r8">|</span><span class="r7"> more</span><span class="r15">``</span><span class="r8">.</span><span class="r7">  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">3</span><span class="r7">        </span><span class="r8">|</span><span class="r7">          </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Another possibility is to add an extra line to row 2:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">1</span><span class="r7">, col </span><span class="r10">1</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">2</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">3</span><span class="r7">  </span><span class="r8">|</span><span class="r7"> column </span><span class="r10">4</span><span class="r7">  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">2</span><span class="r7">        </span><span class="r8">|</span><span class="r7"> Use the command </span><span class="r15">``</span><span class="r7">ls </span><span class="r8">|</span><span class="r7"> more</span><span class="r15">``</span><span class="r8">.</span><span class="r7">   </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7">              </span><span class="r8">|</span><span class="r7">                                  </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> row </span><span class="r10">3</span><span class="r7">        </span><span class="r8">|</span><span class="r7">          </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r7">           </span><span class="r8">|</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+--------------+----------+-----------+-----------+</span><span class="r9">                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Simple Tables                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Simple tables provide a compact and easy to type but limited row-oriented table representation for simple data sets.  </span>
<span class="r4">Cell contents are typically single paragraphs, although arbitrary body elements may be represented in most cells.  </span>
<span class="r4">Simple tables allow multi-line rows (in all but the first column) and column spans, but not row spans.  See </span><span class="r3">Grid Tables</span><span class="r4"> </span>
<span class="r4">above for a complete table representation.</span>

<span class="r4">Simple tables are described with horizontal borders made up of &quot;=&quot; and &quot;-&quot; characters.  The equals sign (&quot;=&quot;) is used </span>
<span class="r4">for top and bottom table borders, and to separate optional header rows from the table body.  The hyphen (&quot;-&quot;) is used to</span>
<span class="r4">indicate column spans in a single row by underlining the joined columns, and may optionally be used to explicitly and/or</span>
<span class="r4">visually separate rows.</span>

<span class="r4">A simple table begins with a top border of equals signs with one or more spaces at each column boundary (two or more </span>
<span class="r4">spaces recommended). Regardless of spans, the top border </span><span class="r13">must</span><span class="r4"> fully describe all table columns.  There must be at least </span>
<span class="r4">two columns in the table (to differentiate it from section headers).  The top border may be followed by header rows, and</span>
<span class="r4">the last of the optional header rows is underlined with &#x27;=&#x27;, again with spaces at column boundaries.  There may not be a</span>
<span class="r4">blank line below the header row separator; it would be interpreted as the bottom border of the table.  The bottom </span>
<span class="r4">boundary of the table consists of &#x27;=&#x27; underlines, also with spaces at column boundaries.  For example, here is a truth </span>
<span class="r4">table, a three-column table with one header row and four body rows:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r7">  </span><span class="r8">=======</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  A      B    A </span><span class="r8">and</span><span class="r7"> B</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r7">  </span><span class="r8">=======</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">False</span><span class="r7">  </span><span class="r12">False</span><span class="r7">  </span><span class="r12">False</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">True</span><span class="r7">   </span><span class="r12">False</span><span class="r7">  </span><span class="r12">False</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">False</span><span class="r7">  </span><span class="r12">True</span><span class="r7">   </span><span class="r12">False</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">True</span><span class="r7">   </span><span class="r12">True</span><span class="r7">   </span><span class="r12">True</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r7">  </span><span class="r8">=======</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Underlines of &#x27;-&#x27; may be used to indicate column spans by &quot;filling in&quot; column margins to join adjacent columns.  Column </span>
<span class="r4">span underlines must be complete (they must cover all columns) and align with established column boundaries.  Text lines</span>
<span class="r4">containing column span underlines may not contain any other text.  A column span underline applies only to one row </span>
<span class="r4">immediately above it.  For example, here is a table with a column span in the header:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r7">  </span><span class="r8">======</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   Inputs     Output</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">------------</span><span class="r7">  </span><span class="r8">------</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  A      B    A </span><span class="r8">or</span><span class="r7"> B</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r7">  </span><span class="r8">======</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">False</span><span class="r7">  </span><span class="r12">False</span><span class="r7">  </span><span class="r12">False</span><span class="r9">                                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">True</span><span class="r7">   </span><span class="r12">False</span><span class="r7">  </span><span class="r12">True</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">False</span><span class="r7">  </span><span class="r12">True</span><span class="r7">   </span><span class="r12">True</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">True</span><span class="r7">   </span><span class="r12">True</span><span class="r7">   </span><span class="r12">True</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r7">  </span><span class="r8">======</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Each line of text must contain spaces at column boundaries, except where cells have been joined by column spans.  Each </span>
<span class="r4">line of text starts a new row, except when there is a blank cell in the first column.  In that case, that line of text </span>
<span class="r4">is parsed as a continuation line.  For this reason, cells in the first column of new rows (</span><span class="r13">not</span><span class="r4"> continuation lines) </span><span class="r13">must</span><span class="r4"> </span>
<span class="r4">contain some text; blank cells would lead to a misinterpretation (but see the tip below).  Also, this mechanism limits </span>
<span class="r4">cells in the first column to only one line of text.  Use </span><span class="r3">grid tables</span><span class="r4"> if this limitation is unacceptable.</span>

<span class="r23">╭─────────────────────────────────────────────────────── Tip:  ────────────────────────────────────────────────────────╮</span>
<span class="r23">│ To start a new row in a simple table without text in the first column in the processed output, use one of these:  an │</span>
<span class="r23">│ empty comment (&quot;..&quot;), which may be omitted from the processed output (see Comments below)  a backslash escape (&quot;\&quot;)  │</span>
<span class="r23">│ followed by a space (see Escaping Mechanism above)                                                                   │</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r4">Underlines of &#x27;-&#x27; may also be used to visually separate rows, even if there are no column spans.  This is especially </span>
<span class="r4">useful in long tables, where rows are many lines long.</span>

<span class="r4">Blank lines are permitted within simple tables.  Their interpretation depends on the context.  Blank lines </span><span class="r13">between</span><span class="r4"> rows </span>
<span class="r4">are ignored. Blank lines </span><span class="r13">within</span><span class="r4"> multi-line rows may separate paragraphs or other body elements within cells.</span>

<span class="r4">The rightmost column is unbounded; text may continue past the edge of the table (as indicated by the table borders).  </span>
<span class="r4">However, it is recommended that borders be made long enough to contain the entire text.</span>

<span class="r4">The following example illustrates continuation lines (row 2 consists of two lines of text, and four lines for row 3), a </span>
<span class="r4">blank line separating paragraphs (row 3, column 2), text extending past the right edge of the table, and a new row which</span>
<span class="r4">will have no text in the first column in the processed output (row 4):</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r9">                                                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">col </span><span class="r10">1</span><span class="r7">  col </span><span class="r10">2</span><span class="r9">                                                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r9">                                                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r10">1</span><span class="r7">      Second column of row </span><span class="r10">1.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r10">2</span><span class="r7">      Second column of row </span><span class="r10">2.</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">       Second line of paragraph</span><span class="r8">.</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r10">3</span><span class="r7">      </span><span class="r8">-</span><span class="r7"> Second column of row </span><span class="r10">3.</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">       </span><span class="r8">-</span><span class="r7"> Second item </span><span class="r8">in</span><span class="r7"> bullet</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">         list (row </span><span class="r10">3</span><span class="r7">, column </span><span class="r10">2</span><span class="r7">)</span><span class="r8">.</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">\      Row </span><span class="r10">4</span><span class="r7">; column </span><span class="r10">1</span><span class="r7"> will be empty</span><span class="r8">.</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">=====</span><span class="r7">  </span><span class="r8">=====</span><span class="r9">                                                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                Explicit Markup Blocks                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">The explicit markup syntax is used for </span><span class="r3">footnotes</span><span class="r4">, </span><span class="r3">citations</span><span class="r4">, </span><span class="r3">hyperlink targets</span><span class="r4">, </span><span class="r3">directives</span><span class="r4">, </span><span class="r3">substitution definitions</span><span class="r4">, </span>
<span class="r4">and </span><span class="r3">comments</span><span class="r4">.</span>

<span class="r4">An explicit markup block is a text block:</span>

<span class="r5"> • </span>whose first line begins with &quot;..&quot; followed by whitespace (the &quot;explicit markup start&quot;),
<span class="r5"> • </span>whose second and subsequent lines (if any) are indented relative to the first, and
<span class="r5"> • </span>which ends before an unindented line.

<span class="r4">Explicit markup blocks are analogous to field list items. The maximum common indentation is always removed from the </span>
<span class="r4">second and subsequent lines of the block body.  Therefore, if the first construct fits in one line and the indentation </span>
<span class="r4">of the first and second constructs should differ, the first construct should not begin on the same line as the explicit </span>
<span class="r4">markup start.</span>

<span class="r4">Blank lines are required between explicit markup blocks and other elements, but are optional between explicit markup </span>
<span class="r4">blocks where unambiguous.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Footnotes                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">See also: </span><span class="r3">Footnote References</span><span class="r4">.</span>

<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#footnote">footnote</a><span class="r4">, </span><a class="r3" href="../doctree.html#label">label</a><span class="r4">.</span>

<span class="r4">Configuration settings: </span><a class="r3" href="../../user/config.html#footnote-references">footnote_references</a><span class="r4">.</span>

<span class="r4">Each footnote consists of an explicit markup start (&quot;.. &quot;), a left square bracket, the footnote label, a right square </span>
<span class="r4">bracket, and whitespace, followed by indented body elements.  A footnote label can be:</span>

<span class="r5"> • </span>a whole decimal number consisting of one or more digits,
<span class="r5"> • </span>a single &quot;#&quot; (denoting auto-numbered footnotes),
<span class="r5"> • </span>a &quot;#&quot; followed by a simple reference name (an autonumber label), or
<span class="r5"> • </span>a single &quot;*&quot; (denoting auto-symbol footnotes).

<span class="r4">The footnote content (body elements) must be consistently indented and left-aligned.  The first body element within a </span>
<span class="r4">footnote may often begin on the same line as the footnote label. However, if the first element fits on one line and the </span>
<span class="r4">indentation of the remaining elements differ, the first element must begin on the line after the footnote label.  </span>
<span class="r4">Otherwise, the difference in indentation will not be detected.</span>

<span class="r4">Footnotes may occur anywhere in the document, not only at the end. Where and how they appear in the processed output </span>
<span class="r4">depends on the processing system.</span>

<span class="r4">Here is a manually numbered footnote:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r10">1</span><span class="r7">] Body elements go here</span><span class="r8">.</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Each footnote automatically generates a hyperlink target pointing to itself.  The text of the hyperlink target name is </span>
<span class="r4">the same as that of the footnote label.  </span><span class="r3">Auto-numbered footnotes</span><span class="r4"> generate a number as their footnote label and reference</span>
<span class="r4">name.  See </span><span class="r3">Implicit Hyperlink Targets</span><span class="r4"> for a complete description of the mechanism.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+-------+-------------------------+</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;.. &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;[&quot;</span><span class="r7"> label </span><span class="r11">&quot;]&quot;</span><span class="r7"> footnote  </span><span class="r8">|</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+</span><span class="r7">                         </span><span class="r8">|</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7"> (body elements)</span><span class="r8">+</span><span class="r7">        </span><span class="r8">|</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+-------------------------+</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Auto-Numbered Footnotes                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">A number sign (&quot;#&quot;) may be used as the first character of a footnote label to request automatic numbering of the </span>
<span class="r4">footnote or footnote reference.</span>

<span class="r4">The first footnote to request automatic numbering is assigned the label &quot;1&quot;, the second is assigned the label &quot;2&quot;, and </span>
<span class="r4">so on (assuming there are no manually numbered footnotes present; see </span><span class="r3">Mixed Manual and Auto-Numbered Footnotes</span><span class="r4"> below).  </span>
<span class="r4">A footnote which has automatically received a label &quot;1&quot; generates an implicit hyperlink target with name &quot;1&quot;, just as if</span>
<span class="r4">the label was explicitly specified.</span>

<span class="r4">A footnote may specify a label explicitly while at the same time requesting automatic numbering: </span><span class="r14">[#label]</span><span class="r4">.  These labels</span>
<span class="r4">are called .  Autonumber labels do two things:</span>

<span class="r5"> • </span>On the footnote itself, they generate a hyperlink target whose name is the autonumber label (doesn&#x27;t include the &quot;#&quot;)
<span class="r5"> • </span>They allow an automatically numbered footnote to be referred to more than once, as a footnote reference or hyperlink 
reference.  For example:  If [#note]_ is the first footnote reference, it will show up as &quot;[1]&quot;.  We can refer to it 
again as [#note]_ and again see &quot;[1]&quot;.  We can also refer to it as note_ (an ordinary internal hyperlink reference).  ..
[#note] This is the footnote labeled &quot;note&quot;.

<span class="r4">The numbering is determined by the order of the footnotes, not by the order of the references.  For footnote references </span>
<span class="r4">without autonumber labels (</span><span class="r14">[#]_</span><span class="r4">), the footnotes and footnote references must be in the same relative order but need not </span>
<span class="r4">alternate in lock-step.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">[</span><span class="r22">#]_ is a reference to footnote 1, and [#]_ is a reference to</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">footnote </span><span class="r10">2.</span><span class="r9">                                                                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r22">#] This is footnote 1.</span><span class="r9">                                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r22">#] This is footnote 2.</span><span class="r9">                                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r22">#] This is footnote 3.</span><span class="r9">                                                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">[</span><span class="r22">#]_ is a reference to footnote 3.</span><span class="r9">                                                                                  </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Special care must be taken if footnotes themselves contain auto-numbered footnote references, or if multiple references </span>
<span class="r4">are made in close proximity.  Footnotes and references are noted in the order they are encountered in the document, </span>
<span class="r4">which is not necessarily the same as the order in which a person would read them.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                Auto-Symbol Footnotes                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">An asterisk (&quot;*&quot;) may be used for footnote labels to request automatic symbol generation for footnotes and footnote </span>
<span class="r4">references.  The asterisk may be the only character in the label.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Here </span><span class="r8">is</span><span class="r7"> a symbolic footnote reference: [</span><span class="r8">*</span><span class="r7">]_</span><span class="r8">.</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r8">*</span><span class="r7">] This </span><span class="r8">is</span><span class="r7"> the footnote</span><span class="r8">.</span><span class="r9">                                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">A transform will insert symbols as labels into corresponding footnotes and footnote references.  The number of </span>
<span class="r4">references must be equal to the number of footnotes.  One symbol footnote cannot have multiple references.</span>

<span class="r4">The standard Docutils system uses the following symbols for footnote marks :</span>

<span class="r5"> • </span>asterisk/star (&quot;*&quot;)
<span class="r5"> • </span>dagger (HTML character entity &quot;&amp;dagger;&quot;, Unicode U+02020)
<span class="r5"> • </span>double dagger (&quot;&amp;Dagger;&quot;/U+02021)
<span class="r5"> • </span>section mark (&quot;&amp;sect;&quot;/U+000A7)
<span class="r5"> • </span>pilcrow or paragraph mark (&quot;&amp;para;&quot;/U+000B6)
<span class="r5"> • </span>number sign (&quot;#&quot;)
<span class="r5"> • </span>spade suit (&quot;&amp;spades;&quot;/U+02660)
<span class="r5"> • </span>heart suit (&quot;&amp;hearts;&quot;/U+02665)
<span class="r5"> • </span>diamond suit (&quot;&amp;diams;&quot;/U+02666)
<span class="r5"> • </span>club suit (&quot;&amp;clubs;&quot;/U+02663)

<span class="r4">If more than ten symbols are required, the same sequence will be reused, doubled and then tripled, and so on (&quot;**&quot; </span>
<span class="r4">etc.).</span>

<span class="r2">╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮</span>
<span class="r2">│ When using auto-symbol footnotes, the choice of output encoding is important.  Many of the symbols used are not      │</span>
<span class="r2">│ encodable in certain common text encodings such as Latin-1 (ISO 8859-1).  The use of UTF-8 for the output encoding   │</span>
<span class="r2">│ is recommended.  An alternative for HTML and XML output is to use the &quot;xmlcharrefreplace&quot; output encoding error      │</span>
<span class="r2">│ handler.                                                                                                             │</span>
<span class="r2">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                       Mixed Manual and Auto-Numbered Footnotes                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Manual and automatic footnote numbering may both be used within a single document, although the results may not be </span>
<span class="r4">expected.  Manual numbering takes priority.  Only unused footnote numbers are assigned to auto-numbered footnotes.  The </span>
<span class="r4">following example should be illustrative:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">[</span><span class="r10">2</span><span class="r7">]_ will be </span><span class="r11">&quot;2&quot;</span><span class="r7"> (manually numbered),</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">[</span><span class="r22">#]_ will be &quot;3&quot; (anonymous auto-numbered), and</span><span class="r9">                                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">[</span><span class="r22">#label]_ will be &quot;1&quot; (labeled auto-numbered).</span><span class="r9">                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r10">2</span><span class="r7">] This footnote </span><span class="r8">is</span><span class="r7"> labeled manually, so its number </span><span class="r8">is</span><span class="r7"> fixed</span><span class="r8">.</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r22">#label] This autonumber-labeled footnote will be labeled &quot;1&quot;.</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   It </span><span class="r8">is</span><span class="r7"> the first auto</span><span class="r8">-</span><span class="r7">numbered footnote </span><span class="r8">and</span><span class="r7"> no other footnote</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r12">with</span><span class="r7"> label </span><span class="r11">&quot;1&quot;</span><span class="r7"> exists</span><span class="r8">.</span><span class="r7">  The order of the footnotes </span><span class="r8">is</span><span class="r7"> used to</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   determine numbering, </span><span class="r8">not</span><span class="r7"> the order of the footnote references</span><span class="r8">.</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r22">#] This footnote will be labeled &quot;3&quot;.  It is the second</span><span class="r9">                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   auto</span><span class="r8">-</span><span class="r7">numbered footnote, but footnote label </span><span class="r11">&quot;2&quot;</span><span class="r7"> </span><span class="r8">is</span><span class="r7"> already used</span><span class="r8">.</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Citations                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">See also: </span><span class="r3">Citation References</span><span class="r4">.</span>

<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#citation">citation</a>

<span class="r4">Citations are identical to footnotes except that they use only non-numeric labels such as </span><span class="r14">[note]</span><span class="r4"> or </span><span class="r14">[GVR2001]</span><span class="r4">.  Citation</span>
<span class="r4">labels are simple </span><span class="r3">reference names</span><span class="r4"> (case-insensitive single words consisting of alphanumerics plus internal hyphens, </span>
<span class="r4">underscores, and periods; no whitespace).  Citations may be rendered separately and differently from footnotes.  For </span>
<span class="r4">example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Here </span><span class="r8">is</span><span class="r7"> a citation reference: [CIT2002]_</span><span class="r8">.</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [CIT2002] This </span><span class="r8">is</span><span class="r7"> the citation</span><span class="r8">.</span><span class="r7">  It</span><span class="r11">&#x27;s just like a footnote,</span><span class="r9">                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r12">except</span><span class="r7"> the label </span><span class="r8">is</span><span class="r7"> textual</span><span class="r8">.</span><span class="r9">                                                                                     </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Hyperlink Targets                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><span class="r3">target</span><span class="r4">.</span>

<span class="r4">These are also called , to differentiate them from </span><span class="r3">implicit hyperlink targets</span><span class="r4"> defined below.</span>

<span class="r4">Hyperlink targets identify a location within or outside of a document, which may be linked to by </span><span class="r3">hyperlink references</span><span class="r4">.</span>

<span class="r4">Hyperlink targets may be named or anonymous.  Named hyperlink targets consist of an explicit markup start (&quot;.. &quot;), an </span>
<span class="r4">underscore, the reference name (no trailing underscore), a colon, whitespace, and a link block:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> _hyperlink</span><span class="r8">-</span><span class="r7">name: link</span><span class="r8">-</span><span class="r7">block</span><span class="r9">                                                                                      </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Reference names are whitespace-neutral and case-insensitive.  See </span><span class="r3">Reference Names</span><span class="r4"> for details and examples.</span>

<span class="r4">Anonymous hyperlink targets consist of an explicit markup start (&quot;.. &quot;), two underscores, a colon, whitespace, and a </span>
<span class="r4">link block; there is no reference name:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> __: anonymous</span><span class="r8">-</span><span class="r7">hyperlink</span><span class="r8">-</span><span class="r7">target</span><span class="r8">-</span><span class="r7">link</span><span class="r8">-</span><span class="r7">block</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">An alternate syntax for anonymous hyperlinks consists of two underscores, a space, and a link block:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">__ anonymous</span><span class="r8">-</span><span class="r7">hyperlink</span><span class="r8">-</span><span class="r7">target</span><span class="r8">-</span><span class="r7">link</span><span class="r8">-</span><span class="r7">block</span><span class="r9">                                                                            </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">See </span><span class="r3">Anonymous Hyperlinks</span><span class="r4"> below.</span>

<span class="r4">There are three types of hyperlink targets: internal, external, and indirect.</span>

<span class="r5"> 1</span> Internal hyperlink targets have empty link blocks.  They provide an end point allowing a hyperlink to connect one pla
to another within a document.  An internal hyperlink target points to the element following the target.   For example:  
Clicking on this internal hyperlink will take us to the target_ below.  .. _target:  The hyperlink target above points 
to this paragraph.  Internal hyperlink targets may be &quot;chained&quot;.  Multiple adjacent internal hyperlink targets all point
to the same element:  .. _target1: .. _target2:  The targets &quot;target1&quot; and &quot;target2&quot; are synonyms; they both point to 
this paragraph.  If the element &quot;pointed to&quot; is an external hyperlink target (with a URI in its link block; see #2 
below) the URI from the external hyperlink target is propagated to the internal hyperlink targets; they will all &quot;point 
to&quot; the same URI.  There is no need to duplicate a URI.  For example, all three of the following hyperlink targets refer
to the same URI:  .. _Python DOC-SIG mailing list archive: .. _archive: .. _Doc-SIG: 
https://mail.python.org/pipermail/doc-sig/  An inline form of internal hyperlink target is available; see Inline 
Internal Targets.  Works also, if the internal hyperlink target is &quot;nested&quot; at the end of an indented text block. This 
behaviour allows setting targets to individual list items (except the first, as a preceding internal target applies to 
the list as a whole):  * bullet list    .. _`second item`:  * second item, with hyperlink target.
<span class="r5"> 2</span> External hyperlink targets have an absolute or relative URI or email address in their link blocks.  For example, take
the following input:  See the Python_ home page for info.  `Write to me`_ with your questions.  .. _Python: 
https://www.python.org .. _Write to me: jdoe@example.com  After processing into HTML, the hyperlinks might be expressed 
as:  See the &lt;a href=&quot;https://www.python.org&quot;&gt;Python&lt;/a&gt; home page for info.  &lt;a href=&quot;mailto:jdoe@example.com&quot;&gt;Write to
me&lt;/a&gt; with your questions.  An external hyperlink&#x27;s URI may begin on the same line as the explicit markup start and 
target name, or it may begin in an indented text block immediately following, with no intervening blank lines.  If there
are multiple lines in the link block, they are concatenated.  Any unescaped whitespace is removed (whitespace is 
permitted to allow for line wrapping).  The following external hyperlink targets are equivalent:  .. _one-liner: 
https://docutils.sourceforge.io/rst.html  .. _starts-on-this-line: https://    docutils.sourceforge.net/rst.html  .. 
_entirely-below:    https://docutils.    sourceforge.net/rst.html  Escaped whitespace is preserved as intentional 
spaces, e.g.:  .. _reference: ../local\ path\ with\ spaces.html  If an external hyperlink target&#x27;s URI contains an 
underscore as its last character, it must be escaped to avoid being mistaken for an indirect hyperlink target:  This 
link_ refers to a file called ``underscore_``.  .. _link: underscore\_  It is possible (although not generally 
recommended) to include URIs directly within hyperlink references.  See Embedded URIs and Aliases below.
<span class="r5"> 3</span> Indirect hyperlink targets have a hyperlink reference in their link blocks.  In the following example, target &quot;one&quot; 
indirectly references whatever target &quot;two&quot; references, and target &quot;two&quot; references target &quot;three&quot;, an internal 
hyperlink target.  In effect, all three reference the same thing:  .. _one: two_ .. _two: three_ .. _three:  Just as 
with hyperlink references anywhere else in a document, if a phrase-reference is used in the link block it must be 
enclosed in backquotes.  As with external hyperlink targets, the link block of an indirect hyperlink target may begin on
the same line as the explicit markup start or the next line.  It may also be split over multiple lines, in which case 
the lines are joined with whitespace before being normalized.  For example, the following indirect hyperlink targets are
equivalent:  .. _one-liner: `A HYPERLINK`_ .. _entirely-below:    `a    hyperlink`_ .. _split: `A    Hyperlink`_  It is 
possible to include an alias directly within hyperlink references. See Embedded URIs and Aliases below.

<span class="r4">If the reference name contains any colons, either:</span>

<span class="r5"> • </span>the phrase must be enclosed in backquotes:  .. _`FAQTS: Computers: Programming: Languages: Python`:    
http://python.faqts.com/
<span class="r5"> • </span>or the colon(s) must be backslash-escaped in the link target:  .. _Chapter One\: &quot;Tadpole Days&quot;:  It&#x27;s not easy being
green...

<span class="r4">See </span><span class="r3">Implicit Hyperlink Targets</span><span class="r4"> below for the resolution of duplicate reference names.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+-------+----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;.. &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;_&quot;</span><span class="r7"> name </span><span class="r11">&quot;:&quot;</span><span class="r7"> link    </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+</span><span class="r7"> block                </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7">                      </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Anonymous Hyperlinks                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">The </span><a class="r3" href="https://www.w3.org/">World Wide Web Consortium</a><span class="r4"> recommends in its </span><a class="r3" href="https://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text">HTML Techniques for Web Content Accessibility Guidelines</a><span class="r4"> that authors </span>
<span class="r4">should &quot;clearly identify the target of each link.&quot;  Hyperlink references should be as verbose as possible, but </span>
<span class="r4">duplicating a verbose hyperlink name in the target is onerous and error-prone.  Anonymous hyperlinks are designed to </span>
<span class="r4">allow convenient verbose hyperlink references, and are analogous to </span><span class="r3">Auto-Numbered Footnotes</span><span class="r4">.  They are particularly </span>
<span class="r4">useful in short or one-off documents.  However, this feature is easily abused and can result in unreadable plaintext </span>
<span class="r4">and/or unmaintainable documents.  Caution is advised.</span>

<span class="r4">Anonymous </span><span class="r3">hyperlink references</span><span class="r4"> are specified with two underscores instead of one:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See </span><span class="r15">`</span><span class="r7">the web site of my favorite programming language</span><span class="r15">`</span><span class="r7">__</span><span class="r8">.</span><span class="r9">                                                           </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Anonymous targets begin with &quot;.. __:&quot;; no reference name is required or allowed:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> __: https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">As a convenient alternative, anonymous targets may begin with &quot;__&quot; only:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">__ https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org</span><span class="r9">                                                                                           </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The reference name of the reference is not used to match the reference to its target.  Instead, the order of anonymous </span>
<span class="r4">hyperlink references and targets within the document is significant: the first anonymous reference will link to the </span>
<span class="r4">first anonymous target.  The number of anonymous hyperlink references in a document must match the number of anonymous </span>
<span class="r4">targets.  For readability, it is recommended that targets be kept close to references.  Take care when editing text </span>
<span class="r4">containing anonymous references; adding, removing, and rearranging references require attention to the order of </span>
<span class="r4">corresponding targets.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Directives                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: depend on the directive.</span>

<span class="r4">Directives are an extension mechanism for reStructuredText, a way of adding support for new constructs without adding </span>
<span class="r4">new primary syntax (directives may support additional syntax locally).  All standard directives (those implemented and </span>
<span class="r4">registered in the reference reStructuredText parser) are described in the </span><span class="r3">reStructuredText Directives</span><span class="r4"> document, and are </span>
<span class="r4">always available.  Any other directives are domain-specific, and may require special action to make them available when </span>
<span class="r4">processing the document.</span>

<span class="r4">For example, here&#x27;s how an </span><span class="r3">image</span><span class="r4"> may be placed:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> image:: mylogo</span><span class="r8">.</span><span class="r7">jpeg</span><span class="r9">                                                                                              </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">A </span><a class="r3" href="directives.html#figure">figure</a><span class="r4"> (a graphic with a caption) may placed like this:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> figure:: larch</span><span class="r8">.</span><span class="r7">png</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   The larch</span><span class="r8">.</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">An </span><a class="r3" href="directives.html#admonitions">admonition</a><span class="r4"> (note, caution, etc.) contains other body elements:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> note:: This </span><span class="r8">is</span><span class="r7"> a paragraph</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">-</span><span class="r7"> Here </span><span class="r8">is</span><span class="r7"> a bullet list</span><span class="r8">.</span><span class="r9">                                                                                         </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Directives are indicated by an explicit markup start (&quot;.. &quot;) followed by the directive type, two colons, and whitespace </span>
<span class="r4">(together called the &quot;directive marker&quot;).  Directive types are case-insensitive single words (alphanumerics plus </span>
<span class="r4">isolated internal hyphens, underscores, plus signs, colons, and periods; no whitespace).  Two colons are used after the </span>
<span class="r4">directive type for these reasons:</span>

<span class="r5"> • </span>Two colons are distinctive, and unlikely to be used in common text.
<span class="r5"> • </span>Two colons avoids clashes with common comment text like:  .. Danger: modify at your own risk!
<span class="r5"> • </span>If an implementation of reStructuredText does not recognize a directive (i.e., the directive-handler is not installed
a level-3 (error) system message is generated, and the entire directive block (including the directive itself) will be 
included as a literal block.  Thus &quot;::&quot; is a natural choice.

<span class="r4">The directive block consists of any text on the first line of the directive after the directive marker, and any </span>
<span class="r4">subsequent indented text.  The interpretation of the directive block is up to the directive code.  There are three </span>
<span class="r4">logical parts to the directive block:</span>

<span class="r5"> 1</span> Directive arguments.
<span class="r5"> 2</span> Directive options.
<span class="r5"> 3</span> Directive content.

<span class="r4">Individual directives can employ any combination of these parts. Directive arguments can be filesystem paths, URLs, </span>
<span class="r4">title text, etc. Directive options are indicated using </span><span class="r3">field lists</span><span class="r4">; the field names and contents are directive-specific.</span>
<span class="r4">Arguments and options must form a contiguous block beginning on the first or second line of the directive; a blank line </span>
<span class="r4">indicates the beginning of the directive content block.  If either arguments and/or options are employed by the </span>
<span class="r4">directive, a blank line must separate them from the directive content. The &quot;figure&quot; directive employs all three parts:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> figure:: larch</span><span class="r8">.</span><span class="r7">png</span><span class="r9">                                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   :scale: </span><span class="r10">50</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   The larch</span><span class="r8">.</span><span class="r9">                                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Simple directives may not require any content.  If a directive that does not employ a content block is followed by </span>
<span class="r4">indented text anyway, it is an error.  If a block quote should immediately follow a directive, use an empty comment </span>
<span class="r4">in-between (see </span><span class="r3">Comments</span><span class="r4"> below).</span>

<span class="r4">Actions taken in response to directives and the interpretation of text in the directive content block or subsequent text</span>
<span class="r4">block(s) are directive-dependent.  See </span><a class="r3" href="directives.html">reStructuredText Directives</a><span class="r4"> for details.</span>

<span class="r4">Directives are meant for the arbitrary processing of their contents, which can be transformed into something possibly </span>
<span class="r4">unrelated to the original text.  It may also be possible for directives to be used as pragmas, to modify the behavior of</span>
<span class="r4">the parser, such as to experiment with alternate syntax.  There is no parser support for this functionality at present; </span>
<span class="r4">if a reasonable need for pragma directives is found, they may be supported.</span>

<span class="r4">Directives do not generate &quot;directive&quot; elements; they are a </span><span class="r13">parser construct</span><span class="r4"> only, and have no intrinsic meaning outside</span>
<span class="r4">of reStructuredText.  Instead, the parser will transform recognized directives into (possibly specialized) document </span>
<span class="r4">elements.  Unknown directives will trigger level-3 (error) system messages.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+-------+-------------------------------+</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;.. &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> directive type </span><span class="r11">&quot;::&quot;</span><span class="r7"> directive </span><span class="r8">|</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+</span><span class="r7"> block                         </span><span class="r8">|</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7">                               </span><span class="r8">|</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+-------------------------------+</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Substitution Definitions                                               ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#substitution-definition">substitution_definition</a><span class="r4">.</span>

<span class="r4">Substitution definitions are indicated by an explicit markup start (&quot;.. &quot;) followed by a vertical bar, the substitution </span>
<span class="r4">text, another vertical bar, whitespace, and the definition block.  Substitution text may not begin or end with </span>
<span class="r4">whitespace.  A substitution definition block contains an embedded inline-compatible directive (without the leading &quot;.. </span>
<span class="r4">&quot;), such as &quot;</span><a class="r3" href="directives.html#image">image</a><span class="r4">&quot; or &quot;</span><a class="r3" href="directives.html#replace">replace</a><span class="r4">&quot;.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">The </span><span class="r8">|</span><span class="r7">biohazard</span><span class="r8">|</span><span class="r7"> symbol must be used on containers used to</span><span class="r9">                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">dispose of medical waste</span><span class="r8">.</span><span class="r9">                                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> </span><span class="r8">|</span><span class="r7">biohazard</span><span class="r8">|</span><span class="r7"> image:: biohazard</span><span class="r8">.</span><span class="r7">png</span><span class="r9">                                                                                </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">It is an error for a substitution definition block to directly or indirectly contain a circular substitution reference.</span>

<span class="r3">Substitution references</span><span class="r4"> are replaced in-line by the processed contents of the corresponding definition (linked by </span>
<span class="r4">matching substitution text).  Matches are case-sensitive but forgiving; if no exact match is found, a case-insensitive </span>
<span class="r4">comparison is attempted.</span>

<span class="r4">Substitution definitions allow the power and flexibility of block-level </span><span class="r3">directives</span><span class="r4"> to be shared by inline text.  They </span>
<span class="r4">are a way to include arbitrarily complex inline structures within text, while keeping the details out of the flow of </span>
<span class="r4">text.  They are the equivalent of SGML/XML&#x27;s named entities or programming language macros.</span>

<span class="r4">Without the substitution mechanism, every time someone wants an application-specific new inline structure, they would </span>
<span class="r4">have to petition for a syntax change.  In combination with existing directive syntax, any inline structure can be coded </span>
<span class="r4">without new syntax (except possibly a new directive).</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+-------+-----------------------------------------------------+</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;.. &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;|&quot;</span><span class="r7"> substitution text </span><span class="r11">&quot;| &quot;</span><span class="r7"> directive type </span><span class="r11">&quot;::&quot;</span><span class="r7"> data </span><span class="r8">|</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+</span><span class="r7"> directive block                                     </span><span class="r8">|</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7">                                                     </span><span class="r8">|</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+-----------------------------------------------------+</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Following are some use cases for the substitution mechanism.  Please note that most of the embedded directives shown are</span>
<span class="r4">examples only and have not been implemented.</span>

<span class="r24">Objects</span>
    Substitution references may be used to associate ambiguous text with a unique object identifier.  For example, many 
sites may wish to implement an inline &quot;user&quot; directive:  |Michael| and |Jon| are our widget-wranglers.  .. |Michael| 
user:: mjones .. |Jon|     user:: jhl  Depending on the needs of the site, this may be used to index the document for 
later searching, to hyperlink the inline text in various ways (mailto, homepage, mouseover Javascript with profile and 
contact information, etc.), or to customize presentation of the text (include username in the inline text, include an 
icon image with a link next to the text, make the text bold or a different color, etc.).  The same approach can be used 
in documents which frequently refer to a particular type of objects with unique identifiers but ambiguous common names. 
Movies, albums, books, photos, court cases, and laws are possible.  For example:  |The Transparent Society| offers a 
fascinating alternate view on privacy issues.  .. |The Transparent Society| book:: isbn=0738201448  Classes or 
functions, in contexts where the module or class names are unclear and/or interpreted text cannot be used, are another 
possibility:  4XSLT has the convenience method |runString|, so you don&#x27;t have to mess with DOM objects if all you want 
is the transformed output.  .. |runString| function:: module=xml.xslt class=Processor
      
<span class="r24">Images</span>
    Images are a common use for substitution references:  West led the |H| 3, covered by dummy&#x27;s |H| Q, East&#x27;s |H| K, 
and trumped in hand with the |S| 2.  .. |H| image:: /images/heart.png    :height: 11    :width: 11 .. |S| image:: 
/images/spade.png    :height: 11    :width: 11  * |Red light| means stop. * |Green light| means go. * |Yellow light| 
means go really fast.  .. |Red light|    image:: red_light.png .. |Green light|  image:: green_light.png .. |Yellow 
light| image:: yellow_light.png  |-&gt;&lt;-| is the official symbol of POEE_.  .. |-&gt;&lt;-| image:: discord.png .. _POEE: 
http://www.poee.org/  The &quot;image&quot; directive has been implemented.
      
<span class="r24">Styles </span>
    Substitution references may be used to associate inline text with an externally defined presentation style:  Even 
|the text in Texas| is big.  .. |the text in Texas| style:: big  The style name may be meaningful in the context of some
particular output format (CSS class name for HTML output, LaTeX style name for LaTeX, etc), or may be ignored for other 
output formats (such as plaintext).  @@@ This needs to be rethought &amp; rewritten or removed:  Interpreted text is 
unsuitable for this purpose because the set of style names cannot be predefined - it is the domain of the content 
author, not the author of the parser and output formatter - and there is no way to associate a style name argument with 
an interpreted text style role.  Also, it may be desirable to use the same mechanism for styling blocks::      .. 
style:: motto        At Bob&#x27;s Underwear Shop, we&#x27;ll do anything to get in        your pants.      .. style:: disclaimer 
All rights reversed.  Reprint what you like.  There may be sufficient need for a &quot;style&quot; mechanism to warrant simpler 
syntax such as an extension to the interpreted text role syntax.  The substitution mechanism is cumbersome for simple 
text styling.
      
<span class="r24">Templates</span>
    Inline markup may be used for later processing by a template engine.  For example, a Zope author might write:  
Welcome back, |name|!  .. |name| tal:: replace user/getUserName  After processing, this ZPT output would result:  
Welcome back, &lt;span tal:replace=&quot;user/getUserName&quot;&gt;name&lt;/span&gt;!  Zope would then transform this to something like 
&quot;Welcome back, David!&quot; during a session with an actual user.
      
<span class="r24">Replacement text</span>
    The substitution mechanism may be used for simple macro substitution.  This may be appropriate when the replacement 
text is repeated many times throughout one or more documents, especially if it may need to change later.  A short 
example is unavoidably contrived:  |RST|_ is a little annoying to type over and over, especially when writing about 
|RST| itself, and spelling out the bicapitalized word |RST| every time isn&#x27;t really necessary for |RST| source 
readability.  .. |RST| replace:: reStructuredText .. _RST: https://docutils.sourceforge.io/rst.html  Note the trailing 
underscore in the first use of a substitution reference.  This indicates a reference to the corresponding hyperlink 
target.  Substitution is also appropriate when the replacement text cannot be represented using other inline constructs,
or is obtrusively long:  But still, that&#x27;s nothing compared to a name like |j2ee-cas|__.  .. |j2ee-cas| replace::    the
Java `TM`:super: 2 Platform, Enterprise Edition Client    Access Services __ 
http://developer.java.sun.com/developer/earlyAccess/    j2eecas/  The &quot;replace&quot; directive has been implemented.
      
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Comments                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#comment">comment</a><span class="r4">.</span>

<span class="r3">Explicit markup blocks</span><span class="r4"> that are not recognized as </span><span class="r3">citations</span><span class="r4">, </span><span class="r3">directives</span><span class="r4">, </span><span class="r3">footnotes</span><span class="r4">, </span><span class="r3">hyperlink targets</span><span class="r4">, or </span><span class="r3">substitution </span>
<span class="r3">definitions</span><span class="r4"> will be processed as a comment element. Arbitrary indented text may be used on the lines following the </span>
<span class="r4">explicit markup start. To ensure that none of the other explicit markup constructs is recognized, leave the &quot;..&quot; on a </span>
<span class="r4">line by itself:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> This </span><span class="r8">is</span><span class="r7"> a comment</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   _so: </span><span class="r8">is</span><span class="r7"> this</span><span class="r15">!</span><span class="r9">                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   [</span><span class="r8">and</span><span class="r7">] this</span><span class="r15">!</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   this:: too</span><span class="r15">!</span><span class="r9">                                                                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">   </span><span class="r8">|</span><span class="r7">even</span><span class="r8">|</span><span class="r7"> this:: </span><span class="r15">!</span><span class="r9">                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [this] however, </span><span class="r8">is</span><span class="r7"> a citation</span><span class="r8">.</span><span class="r9">                                                                                   </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Apart from removing the maximum common indentation, no further processing is done on the content; a comment contains a </span>
<span class="r4">single &quot;text blob&quot;.  Depending on the output formatter, comments may be removed from the processed output.</span>

<span class="r4">Syntax diagram:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">+-------+----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">|</span><span class="r7"> </span><span class="r11">&quot;.. &quot;</span><span class="r7"> </span><span class="r8">|</span><span class="r7"> comment              </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">+-------+</span><span class="r7"> block                </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">|</span><span class="r7">                      </span><span class="r8">|</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">        </span><span class="r8">+----------------------+</span><span class="r9">                                                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Empty Comments                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">An explicit markup start followed by a blank line and nothing else (apart from whitespace) is an &quot;&quot;.  It serves to </span>
<span class="r4">terminate a preceding construct, and does </span><span class="r20">not</span><span class="r4"> consume any indented text following.  To have a block quote follow a list </span>
<span class="r4">or any indented construct, insert an unindented empty comment in-between:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r9">                                                                                                             </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  a definition list</span><span class="r8">.</span><span class="r9">                                                                                                </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r9">                                                                                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">  This </span><span class="r8">is</span><span class="r7"> a block quote</span><span class="r8">.</span><span class="r9">                                                                                            </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                              Implicit Hyperlink Targets                                              ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Implicit hyperlink targets are generated by section titles, footnotes, and citations, and may also be generated by </span>
<span class="r4">extension constructs. Implicit hyperlink targets otherwise behave identically to explicit </span><span class="r3">hyperlink targets</span><span class="r4">.</span>

<span class="r4">Problems of ambiguity due to conflicting duplicate implicit and explicit reference names are avoided by following this </span>
<span class="r4">procedure:</span>

<span class="r5"> 1</span> Explicit hyperlink targets override any implicit targets having the same reference name.  The implicit hyperlink targ
are removed, and level-1 (info) system messages are inserted.
<span class="r5"> 2</span> Duplicate implicit hyperlink targets are removed, and level-1 (info) system messages inserted.  For example, if two o
more sections have the same title (such as &quot;Introduction&quot; subsections of a rigidly-structured document), there will be 
duplicate implicit hyperlink targets.
<span class="r5"> 3</span> Duplicate explicit hyperlink targets are removed, and level-2 (warning) system messages are inserted.  Exception: 
duplicate external hyperlink targets (identical hyperlink names and referenced URIs) do not conflict, and are not 
removed.

<span class="r4">System messages are inserted where target links have been removed. See &quot;Error Handling&quot; in </span><span class="r3">PEP 258</span><span class="r4">.</span>

<span class="r4">The parser must return a set of </span><span class="r13">unique</span><span class="r4"> hyperlink targets.  The calling software (such as the </span><a class="r3" href="https://docutils.sourceforge.io/">Docutils</a><span class="r4">) can warn of </span>
<span class="r4">unresolvable links, giving reasons for the messages.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Inline Markup                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">In reStructuredText, inline markup applies to words or phrases within a text block.  The same whitespace and punctuation</span>
<span class="r4">that serves to delimit words in written text is used to delimit the inline markup syntax constructs (see the </span><span class="r3">inline </span>
<span class="r3">markup recognition rules</span><span class="r4"> for details).  The text within inline markup may not begin or end with whitespace.  Arbitrary </span>
<span class="r3">character-level inline markup</span><span class="r4"> is supported although not encouraged.  Inline markup cannot be nested.</span>

<span class="r4">There are nine inline markup constructs.  Five of the constructs use identical start-strings and end-strings to indicate</span>
<span class="r4">the markup:</span>

<span class="r5"> • </span>emphasis: &quot;*&quot;
<span class="r5"> • </span>strong emphasis: &quot;**&quot;
<span class="r5"> • </span>interpreted text: &quot;`&quot;
<span class="r5"> • </span>inline literals: &quot;``&quot;
<span class="r5"> • </span>substitution references: &quot;|&quot;

<span class="r4">Three constructs use different start-strings and end-strings:</span>

<span class="r5"> • </span>inline internal targets: &quot;_`&quot; and &quot;`&quot;
<span class="r5"> • </span>footnote references: &quot;[&quot; and &quot;]_&quot;
<span class="r5"> • </span>hyperlink references: &quot;`&quot; and &quot;`_&quot; (phrases), or just a trailing &quot;_&quot; (single words)

<span class="r3">Standalone hyperlinks</span><span class="r4"> are recognized implicitly, and use no extra markup.</span>

<span class="r4">Inline comments are not supported.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                           Inline markup recognition rules                                            ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Inline markup start-strings and end-strings are only recognized if the following conditions are met:</span>

<span class="r5"> 1</span> Inline markup start-strings must be immediately followed by non-whitespace.
<span class="r5"> 2</span> Inline markup end-strings must be immediately preceded by non-whitespace.
<span class="r5"> 3</span> The inline markup end-string must be separated by at least one character from the start-string.
<span class="r5"> 4</span> Both, inline markup start-string and end-string must not be preceded by an unescaped backslash (except for the 
end-string of inline literals). See Escaping Mechanism above for details.
<span class="r5"> 5</span> If an inline markup start-string is immediately preceded by one of the ASCII characters &#x27; &quot; &lt; ( [ { or a similar 
non-ASCII character , it must not be followed by the corresponding closing character from &#x27; &quot; &gt; ) ] } or a similar 
non-ASCII character . (For quotes, matching characters can be any of the quotation marks in international usage.)

<span class="r4">If the configuration setting </span><span class="r3">character-level-inline-markup</span><span class="r4"> is False (default), additional conditions apply to the </span>
<span class="r4">characters &quot;around&quot; the inline markup:</span>

<span class="r5"> 1</span> Inline markup start-strings must start a text block or be immediately preceded by  whitespace,  one of the ASCII 
characters - : / &#x27; &quot; &lt; ( [ {  or a similar non-ASCII punctuation character. 
<span class="r5"> 2</span> Inline markup end-strings must end a text block or be immediately followed by  whitespace,  one of the ASCII characte
- . , : ; ! ? \ / &#x27; &quot; ) ] } &gt;  or a similar non-ASCII punctuation character. 

<span class="r4">The inline markup recognition rules were devised to allow 90% of non-markup uses of &quot;*&quot;, &quot;`&quot;, &quot;_&quot;, and &quot;|&quot; without </span>
<span class="r4">escaping. For example, none of the following terms are recognized as containing inline markup strings:</span>

<span class="r5"> • </span>2 * x  a ** b  (* BOM32_* ` `` _ __ | (breaks rule 1)
<span class="r5"> • </span>|| (breaks rule 3)
<span class="r5"> • </span>&quot;*&quot; &#x27;|&#x27; (*) [*] {*} &lt;*&gt; â€˜*â€™ â€š*â€˜ â€˜*â€š â€™*â€™ â€š*â€™ â€œ*â€ â€ž*â€œ â€œ*â€ž â€*â€ â€ž*â€ Â»*Â« â€º*â€¹ Â«*
Â»*Â» â€º*â€º (breaks rule 5)  &lt;rst-document&gt;:2564: (WARNING/2) Inline emphasis start-string without end-string.  
&lt;rst-document&gt;:2564: (WARNING/2) Inline emphasis start-string without end-string.  &lt;rst-document&gt;:2564: (WARNING/2) 
Inline emphasis start-string without end-string.
<span class="r5"> • </span>2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* __init__ __init__()  (breaks rule 6)

<span class="r4">No escaping is required inside the following inline markup examples:</span>

<span class="r5"> • </span>*2 * x  *a **b *.txt* (breaks rule 2; renders as &quot;2 * x  *a **b *.txt&quot;)
<span class="r5"> • </span>*2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)* (breaks rule 7; renders as &quot;2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)

<span class="r4">It may be desirable to use </span><span class="r3">inline literals</span><span class="r4"> for some of these anyhow, especially if they represent code snippets.  It&#x27;s a</span>
<span class="r4">judgment call.</span>

<span class="r4">The following terms </span><span class="r13">do</span><span class="r4"> require either literal-quoting or escaping to avoid misinterpretation:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r8">*</span><span class="r10">4</span><span class="r7">, class_, </span><span class="r8">*</span><span class="r7">args, </span><span class="r8">**</span><span class="r7">kwargs, </span><span class="r15">`</span><span class="r7">TeX</span><span class="r8">-</span><span class="r7">quoted</span><span class="r11">&#x27;, *ML, *.txt</span><span class="r9">                                                               </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">In most use cases, </span><span class="r3">inline literals</span><span class="r4"> or </span><span class="r3">literal blocks</span><span class="r4"> are the best choice (by default, this also selects a monospaced </span>
<span class="r4">font). Alternatively, the inline markup characters can be escaped:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">\</span><span class="r8">*</span><span class="r10">4</span><span class="r7">, class\_, \</span><span class="r8">*</span><span class="r7">args, \</span><span class="r8">**</span><span class="r7">kwargs, \</span><span class="r15">`</span><span class="r7">TeX</span><span class="r8">-</span><span class="r7">quoted</span><span class="r11">&#x27;, \*ML, \*.txt</span><span class="r9">                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">For languages that don&#x27;t use whitespace between words (e.g. Japanese or Chinese) it is recommended to set </span>
<a class="r3" href="../../user/config.html#character-level-inline-markup">character-level-inline-markup</a><span class="r4"> to True and eventually escape inline markup characters. The examples breaking rules 6 and </span>
<span class="r4">7 above show which constructs may need special attention.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Recognition order                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Inline markup delimiter characters are used for multiple constructs, so to avoid ambiguity there must be a specific </span>
<span class="r4">recognition order for each character.  The inline markup recognition order is as follows:</span>

<span class="r5"> • </span>Asterisks: Strong emphasis (&quot;**&quot;) is recognized before emphasis (&quot;*&quot;).
<span class="r5"> • </span>Backquotes: Inline literals (&quot;``&quot;), inline internal targets (leading &quot;_`&quot;, trailing &quot;`&quot;), are mutually independent, a
are recognized before phrase hyperlink references (leading &quot;`&quot;, trailing &quot;`_&quot;) and interpreted text (&quot;`&quot;).
<span class="r5"> • </span>Trailing underscores: Footnote references (&quot;[&quot; + label + &quot;]_&quot;) and simple hyperlink references (name + trailing &quot;_&quot;) 
mutually independent.
<span class="r5"> • </span>Vertical bars: Substitution references (&quot;|&quot;) are independently recognized.
<span class="r5"> • </span>Standalone hyperlinks are the last to be recognized.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                            Character-Level Inline Markup                                             ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">It is possible to mark up individual characters within a word with backslash escapes (see </span><span class="r3">Escaping Mechanism</span><span class="r4"> above).  </span>
<span class="r4">Backslash escapes can be used to allow arbitrary text to immediately follow inline markup:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Python </span><span class="r15">``</span><span class="r7">list</span><span class="r15">``</span><span class="r7">\s use square bracket syntax</span><span class="r8">.</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The backslash will disappear from the processed document.  The word &quot;list&quot; will appear as inline literal text, and the </span>
<span class="r4">letter &quot;s&quot; will immediately follow it as normal text, with no space in-between.</span>

<span class="r4">Arbitrary text may immediately precede inline markup using backslash-escaped whitespace:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Possible </span><span class="r8">in</span><span class="r7"> </span><span class="r8">*</span><span class="r7">re</span><span class="r8">*</span><span class="r7">\ </span><span class="r15">``</span><span class="r7">Structured</span><span class="r15">``</span><span class="r7">\ </span><span class="r8">*</span><span class="r7">Text</span><span class="r8">*</span><span class="r7">, though </span><span class="r8">not</span><span class="r7"> encouraged</span><span class="r8">.</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The backslashes and spaces separating &quot;re&quot;, &quot;Structured&quot;, and &quot;Text&quot; above will disappear from the processed document.</span>

<span class="r25">╭───────────────────────────────────────────────────── Caution:  ──────────────────────────────────────────────────────╮</span>
<span class="r25">│ The use of backslash-escapes for character-level inline markup is not encouraged.  Such use is ugly and detrimental  │</span>
<span class="r25">│ to the unprocessed document&#x27;s readability.  Please use this feature sparingly and only where absolutely necessary.   │</span>
<span class="r25">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Emphasis                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><span class="r3">emphasis</span><span class="r4">.</span>

<span class="r4">Start-string = end-string = &quot;*&quot;.</span>

<span class="r4">Text enclosed by single asterisk characters is emphasized:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> </span><span class="r8">*</span><span class="r7">emphasized text</span><span class="r8">*.</span><span class="r9">                                                                                          </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Emphasized text is typically displayed in italics.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Strong Emphasis                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#strong">strong</a><span class="r4">.</span>

<span class="r4">Start-string = end-string = &quot;**&quot;.</span>

<span class="r4">Text enclosed by double-asterisks is emphasized strongly:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> </span><span class="r8">**</span><span class="r7">strong text</span><span class="r8">**.</span><span class="r9">                                                                                            </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Strongly emphasized text is typically displayed in boldface.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Interpreted Text                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: depends on the explicit or implicit role and processing.</span>

<span class="r4">Start-string = end-string = &quot;`&quot;.</span>

<span class="r4">Interpreted text is text that is meant to be related, indexed, linked, summarized, or otherwise processed, but the text </span>
<span class="r4">itself is typically left alone.  Interpreted text is enclosed by single backquote characters:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> </span><span class="r15">`</span><span class="r7">interpreted text</span><span class="r15">`</span><span class="r8">.</span><span class="r9">                                                                                         </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The &quot;role&quot; of the interpreted text determines how the text is interpreted.  The role may be inferred implicitly (as </span>
<span class="r4">above; the &quot;default role&quot; is used) or indicated explicitly, using a role marker. A role marker consists of a colon, the </span>
<span class="r4">role name, and another colon. A role name is a single word consisting of alphanumerics plus isolated internal hyphens, </span>
<span class="r4">underscores, plus signs, colons, and periods; no whitespace or other characters are allowed.  A role marker is either a </span>
<span class="r4">prefix or a suffix to the interpreted text, whichever reads better; it&#x27;s up to the author:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">:role:</span><span class="r15">`</span><span class="r7">interpreted text</span><span class="r15">`</span><span class="r9">                                                                                            </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r15">`</span><span class="r7">interpreted text</span><span class="r15">`</span><span class="r7">:role:</span><span class="r9">                                                                                            </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Interpreted text allows extensions to the available inline descriptive markup constructs.  To </span><span class="r3">emphasis</span><span class="r4">, </span><span class="r3">strong emphasis</span><span class="r4">,</span>
<span class="r3">inline literals</span><span class="r4">, and </span><span class="r3">hyperlink references</span><span class="r4">, we can add &quot;title reference&quot;, &quot;index entry&quot;, &quot;acronym&quot;, &quot;class&quot;, &quot;red&quot;, </span>
<span class="r4">&quot;blinking&quot; or anything else we want (as long as it is a simple </span><span class="r3">reference name</span><span class="r4">). Only pre-determined roles are </span>
<span class="r4">recognized; unknown roles will generate errors.  A core set of standard roles is implemented in the reference parser; </span>
<span class="r4">see </span><a class="r3" href="roles.html">reStructuredText Interpreted Text Roles</a><span class="r4"> for individual descriptions.  The </span><a class="r3" href="directives.html#custom-interpreted-text-roles">role</a><span class="r4"> directive can be used to define </span>
<span class="r4">custom interpreted text roles.  In addition, applications may support specialized roles.</span>

<span class="r4">In </span><span class="r3">field lists</span><span class="r4">, care must be taken when using interpreted text with explicit roles in field names: the role must be a </span>
<span class="r4">suffix to the interpreted text. The following are recognized as field list items:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">:</span><span class="r15">`</span><span class="r7">field name</span><span class="r15">`</span><span class="r7">:code:: interpreted text </span><span class="r12">with</span><span class="r7"> explicit role </span><span class="r12">as</span><span class="r7"> suffix</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:a </span><span class="r15">`</span><span class="r7">complex</span><span class="r15">`</span><span class="r7">:code:\  field name: a backslash</span><span class="r8">-</span><span class="r7">escaped space</span><span class="r9">                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">                                 </span><span class="r8">is</span><span class="r7"> necessary</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The following are </span><span class="r20">not</span><span class="r4"> recognized as field list items:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">::code:</span><span class="r15">`</span><span class="r8">not</span><span class="r7"> a field name</span><span class="r15">`</span><span class="r7">: paragraph </span><span class="r12">with</span><span class="r7"> interpreted text</span><span class="r9">                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:code:</span><span class="r15">`</span><span class="r8">not</span><span class="r7"> a field name</span><span class="r15">`</span><span class="r7">: paragraph </span><span class="r12">with</span><span class="r7"> interpreted text</span><span class="r9">                                                           </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Edge cases:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">:field\:</span><span class="r15">`</span><span class="r7">name</span><span class="r15">`</span><span class="r7">: interpreted text (standard role) requires</span><span class="r9">                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">                escaping the leading colon </span><span class="r8">in</span><span class="r7"> a field name</span><span class="r9">                                                          </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">:field:\</span><span class="r15">`</span><span class="r7">name</span><span class="r15">`</span><span class="r7">: </span><span class="r8">not</span><span class="r7"> interpreted text</span><span class="r9">                                                                                </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Inline Literals                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#literal">literal</a><span class="r4">.</span>

<span class="r4">Start-string = end-string = &quot;``&quot;.</span>

<span class="r4">Text enclosed by double-backquotes is treated as inline literals:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This text </span><span class="r8">is</span><span class="r7"> an example of </span><span class="r15">``</span><span class="r7">inline literals</span><span class="r15">``</span><span class="r8">.</span><span class="r9">                                                                     </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Inline literals may contain any characters except two adjacent backquotes in an end-string context (according to the </span>
<span class="r4">recognition rules above).  No markup interpretation (including backslash-escape interpretation) is done within inline </span>
<span class="r4">literals.</span>

<span class="r4">Line breaks and sequences of whitespace characters are </span><span class="r13">not</span><span class="r4"> protected in inline literals. Although a reStructuredText </span>
<span class="r4">parser will preserve them in its output, the final representation of the processed document depends on the output </span>
<span class="r4">formatter, thus the preservation of whitespace cannot be guaranteed.  If the preservation of line breaks and/or other </span>
<span class="r4">whitespace is important, </span><span class="r3">literal blocks</span><span class="r4"> should be used.</span>

<span class="r4">Inline literals are useful for short code snippets.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">The regular expression </span><span class="r15">``</span><span class="r7">[</span><span class="r8">+-</span><span class="r7">]</span><span class="r15">?</span><span class="r7">(\d</span><span class="r8">+</span><span class="r7">(\</span><span class="r8">.</span><span class="r7">\d</span><span class="r8">*</span><span class="r7">)</span><span class="r15">?</span><span class="r8">|</span><span class="r7">\</span><span class="r8">.</span><span class="r7">\d</span><span class="r8">+</span><span class="r7">)</span><span class="r15">``</span><span class="r7"> matches</span><span class="r9">                                                         </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">floating</span><span class="r8">-</span><span class="r7">point numbers (without exponents)</span><span class="r8">.</span><span class="r9">                                                                         </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Hyperlink References                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><span class="r3">reference</span><span class="r4">.</span>

  <span class="r5"> ∘ </span>Named hyperlink references:
  <span class="r5"> ∘ </span>No start-string, end-string = &quot;_&quot;.  Start-string = &quot;`&quot;, end-string = &quot;`_&quot;.  (Phrase references.)
    <span class="r5"> ▪ </span>No start-string, end-string = &quot;_&quot;.
    <span class="r5"> ▪ </span>Start-string = &quot;`&quot;, end-string = &quot;`_&quot;.  (Phrase references.)
<span class="r5"> • </span>Start-string = &quot;`&quot;, end-string = &quot;`_&quot;.  (Phrase references.)
  <span class="r5"> ∘ </span>Anonymous hyperlink references:
  <span class="r5"> ∘ </span>No start-string, end-string = &quot;__&quot;.  Start-string = &quot;`&quot;, end-string = &quot;`__&quot;.  (Phrase references.)
    <span class="r5"> ▪ </span>No start-string, end-string = &quot;__&quot;.
    <span class="r5"> ▪ </span>Start-string = &quot;`&quot;, end-string = &quot;`__&quot;.  (Phrase references.)
<span class="r5"> • </span>Start-string = &quot;`&quot;, end-string = &quot;`__&quot;.  (Phrase references.)

<span class="r4">Hyperlink references are indicated by a trailing underscore, &quot;_&quot;, except for </span><span class="r3">standalone hyperlinks</span><span class="r4"> which are recognized </span>
<span class="r4">independently.  The underscore can be thought of as a right-pointing arrow.  The trailing underscores point away from </span>
<span class="r4">hyperlink references, and the leading underscores point toward </span><span class="r3">hyperlink targets</span><span class="r4">.</span>

<span class="r4">Hyperlinks consist of two parts.  In the text body, there is a source link, a reference name with a trailing underscore </span>
<span class="r4">(or two underscores for </span><span class="r3">anonymous hyperlinks</span><span class="r4">):</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See the Python_ home page </span><span class="r12">for</span><span class="r7"> info</span><span class="r8">.</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">A target link with a matching reference name must exist somewhere else in the document.  See </span><span class="r3">Hyperlink Targets</span><span class="r4"> for a </span>
<span class="r4">full description).</span>

<span class="r3">Anonymous hyperlinks</span><span class="r4"> (which see) do not use reference names to match references to targets, but otherwise behave </span>
<span class="r4">similarly to named hyperlinks.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                              Embedded URIs and Aliases                                               ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">A hyperlink reference may directly embed a target URI or (since DocutilsÂ 0.11) a hyperlink reference within angle </span>
<span class="r4">brackets (&quot;&lt;...&gt;&quot;) as follows:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See the </span><span class="r15">`</span><span class="r7">Python home page </span><span class="r8">&lt;</span><span class="r7">https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">_ </span><span class="r12">for</span><span class="r7"> info</span><span class="r8">.</span><span class="r9">                                                      </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r15">`</span><span class="r7">link </span><span class="r8">&lt;</span><span class="r7">Python home page_</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">_ </span><span class="r8">is</span><span class="r7"> an alias to the link above</span><span class="r8">.</span><span class="r9">                                                     </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">This is exactly equivalent to:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See the </span><span class="r15">`</span><span class="r7">Python home page</span><span class="r15">`</span><span class="r7">_ </span><span class="r12">for</span><span class="r7"> info</span><span class="r8">.</span><span class="r9">                                                                               </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">This link_ </span><span class="r8">is</span><span class="r7"> an alias to the link above</span><span class="r8">.</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> _Python home page: https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> _link: </span><span class="r15">`</span><span class="r7">Python home page</span><span class="r15">`</span><span class="r7">_</span><span class="r9">                                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The bracketed URI must be preceded by whitespace and be the last text before the end string.</span>

<span class="r4">With a single trailing underscore, the reference is named and the same target URI may be referred to again. With two </span>
<span class="r4">trailing underscores, the reference and target are both anonymous, and the target cannot be referred to again.  These </span>
<span class="r4">are &quot;one-off&quot; hyperlinks.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r15">`</span><span class="r7">RFC </span><span class="r10">2396</span><span class="r7"> </span><span class="r8">&lt;</span><span class="r7">https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">rfc</span><span class="r8">-</span><span class="r7">editor</span><span class="r8">.</span><span class="r7">org</span><span class="r8">/</span><span class="r7">rfc</span><span class="r8">/</span><span class="r7">rfc2396</span><span class="r8">.</span><span class="r7">txt</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">__ </span><span class="r8">and</span><span class="r7"> </span><span class="r15">`</span><span class="r7">RFC</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r10">2732</span><span class="r7"> </span><span class="r8">&lt;</span><span class="r7">https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">rfc</span><span class="r8">-</span><span class="r7">editor</span><span class="r8">.</span><span class="r7">org</span><span class="r8">/</span><span class="r7">rfc</span><span class="r8">/</span><span class="r7">rfc2732</span><span class="r8">.</span><span class="r7">txt</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">__ together</span><span class="r9">                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">define the syntax of URIs</span><span class="r8">.</span><span class="r9">                                                                                          </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Equivalent to:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r15">`</span><span class="r7">RFC </span><span class="r10">2396</span><span class="r15">`</span><span class="r7">__ </span><span class="r8">and</span><span class="r7"> </span><span class="r15">`</span><span class="r7">RFC </span><span class="r10">2732</span><span class="r15">`</span><span class="r7">__ together define the syntax of URIs</span><span class="r8">.</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">__ https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">rfc</span><span class="r8">-</span><span class="r7">editor</span><span class="r8">.</span><span class="r7">org</span><span class="r8">/</span><span class="r7">rfc</span><span class="r8">/</span><span class="r7">rfc2396</span><span class="r8">.</span><span class="r7">txt</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">__ https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">rfc</span><span class="r8">-</span><span class="r7">editor</span><span class="r8">.</span><span class="r7">org</span><span class="r8">/</span><span class="r7">rfc</span><span class="r8">/</span><span class="r7">rfc2732</span><span class="r8">.</span><span class="r7">txt</span><span class="r9">                                                                       </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r3">Standalone hyperlinks</span><span class="r4"> are treated as URIs, even if they end with an underscore like in the example of a Python function </span>
<span class="r4">documentation:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r15">`</span><span class="r21">__init__</span><span class="r7"> </span><span class="r8">&lt;</span><span class="r7">http:example</span><span class="r8">.</span><span class="r7">py</span><span class="r8">.</span><span class="r7">html</span><span class="r22">#__init__&gt;`__</span><span class="r9">                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">If a target URI that is not recognized as </span><span class="r3">standalone hyperlink</span><span class="r4"> happens to end with an underscore, this needs to be </span>
<span class="r4">backslash-escaped to avoid being parsed as hyperlink reference. For example</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Use the </span><span class="r15">`</span><span class="r7">source </span><span class="r8">&lt;</span><span class="r7">parrots</span><span class="r8">.</span><span class="r7">txt\_</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">__</span><span class="r8">.</span><span class="r9">                                                                                 </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">creates an anonymous reference to the file </span><span class="r14">parrots.txt_</span><span class="r4">.</span>

<span class="r4">If the reference text happens to end with angle-bracketed text that is </span><span class="r13">not</span><span class="r4"> a URI or hyperlink reference, at least one </span>
<span class="r4">angle-bracket needs to be backslash-escaped or an escaped space should follow. For example, here are three references to</span>
<span class="r4">titles describing a tag:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See </span><span class="r15">`</span><span class="r7">HTML Element: \</span><span class="r8">&lt;</span><span class="r7">a</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">_, </span><span class="r15">`</span><span class="r7">HTML Element: </span><span class="r8">&lt;</span><span class="r7">b\</span><span class="r8">&gt;</span><span class="r7"> </span><span class="r15">`</span><span class="r7">_, </span><span class="r8">and</span><span class="r9">                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r15">`</span><span class="r7">HTML Element: </span><span class="r8">&lt;</span><span class="r7">c</span><span class="r8">&gt;</span><span class="r7">\ </span><span class="r15">`</span><span class="r7">_</span><span class="r8">.</span><span class="r9">                                                                                             </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">The reference text may also be omitted, in which case the URI will be duplicated for use as the reference text.  This is</span>
<span class="r4">useful for relative URIs where the address or file name is also the desired reference text:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See </span><span class="r15">`</span><span class="r8">&lt;</span><span class="r7">a_named_relative_link</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">_ </span><span class="r8">or</span><span class="r7"> </span><span class="r15">`</span><span class="r8">&lt;</span><span class="r7">an_anonymous_relative_link</span><span class="r8">&gt;</span><span class="r15">`</span><span class="r7">__</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r12">for</span><span class="r7"> details</span><span class="r8">.</span><span class="r9">                                                                                                        </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r25">╭───────────────────────────────────────────────────── Caution:  ──────────────────────────────────────────────────────╮</span>
<span class="r25">│ This construct offers easy authoring and maintenance of hyperlinks at the expense of general readability.  Inline    │</span>
<span class="r25">│ URIs, especially long ones, inevitably interrupt the natural flow of text.  For documents meant to be read in source │</span>
<span class="r25">│ form, the use of independent block-level hyperlink targets is strongly recommended.  The embedded URI construct is   │</span>
<span class="r25">│ most suited to documents intended only to be read in processed form.                                                 │</span>
<span class="r25">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Inline Internal Targets                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#target">target</a><span class="r4">.</span>

<span class="r4">Start-string = &quot;_`&quot;, end-string = &quot;`&quot;.</span>

<span class="r4">Inline internal targets are the equivalent of explicit </span><span class="r3">internal hyperlink targets</span><span class="r4">, but may appear within running text.  </span>
<span class="r4">The syntax begins with an underscore and a backquote, is followed by a hyperlink name or phrase, and ends with a </span>
<span class="r4">backquote.  Inline internal targets may not be anonymous.</span>

<span class="r4">For example, the following paragraph contains a hyperlink target named &quot;Norwegian Blue&quot;:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Oh yes, the _</span><span class="r15">`</span><span class="r7">Norwegian Blue</span><span class="r15">`</span><span class="r8">.</span><span class="r7">  What</span><span class="r11">&#x27;s, um, what&#x27;</span><span class="r7">s wrong </span><span class="r12">with</span><span class="r7"> it</span><span class="r15">?</span><span class="r9">                                                   </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">See </span><span class="r3">Implicit Hyperlink Targets</span><span class="r4"> for the resolution of duplicate reference names.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Footnote References                                                  ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">See also: </span><span class="r3">Footnotes</span>

<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#footnote-reference">footnote_reference</a><span class="r4">.</span>

<span class="r4">Configuration settings: </span><span class="r3">footnote_references</span><span class="r4">, </span><a class="r3" href="../../user/config.html#trim-footnote-reference-space">trim_footnote_reference_space</a><span class="r4">.</span>

<span class="r4">Start-string = &quot;[&quot;, end-string = &quot;]_&quot;.</span>

<span class="r4">Each footnote reference consists of a square-bracketed label followed by a trailing underscore.  Footnote labels are one</span>
<span class="r4">of:</span>

<span class="r5"> • </span>one or more digits (i.e., a number),
<span class="r5"> • </span>a single &quot;#&quot; (denoting auto-numbered footnotes),
<span class="r5"> • </span>a &quot;#&quot; followed by a simple reference name (an autonumber label), or
<span class="r5"> • </span>a single &quot;*&quot; (denoting auto-symbol footnotes).

<span class="r4">For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Please RTFM [</span><span class="r10">1</span><span class="r7">]_</span><span class="r8">.</span><span class="r9">                                                                                                   </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r8">..</span><span class="r7"> [</span><span class="r10">1</span><span class="r7">] Read The Fine Manual</span><span class="r9">                                                                                         </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r3">Inline markup recognition rules</span><span class="r4"> may require whitespace in front of the footnote reference. To remove the whitespace from</span>
<span class="r4">the output, use an escaped whitespace character (see </span><span class="r3">Escaping Mechanism</span><span class="r4">) or set the </span><span class="r3">trim_footnote_reference_space</span><span class="r4"> </span>
<span class="r4">configuration setting. Leading whitespace is removed by default, if the </span><span class="r3">footnote_references setting</span><span class="r4"> is &quot;superscript&quot;.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Citation References                                                  ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">See also: </span><span class="r3">Citations</span>

<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#citation-reference">citation_reference</a><span class="r4">.</span>

<span class="r4">Start-string = &quot;[&quot;, end-string = &quot;]_&quot;.</span>

<span class="r4">Each citation reference consists of a square-bracketed label followed by a trailing underscore.  Citation labels are </span>
<span class="r4">simple </span><span class="r3">reference names</span><span class="r4"> (case-insensitive single words, consisting of alphanumerics plus internal hyphens, underscores, </span>
<span class="r4">and periods; no whitespace).</span>

<span class="r4">For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">Here </span><span class="r8">is</span><span class="r7"> a citation reference: [CIT2002]_</span><span class="r8">.</span><span class="r9">                                                                           </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Substitution References                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#substitution-reference">substitution_reference</a><span class="r4">, </span><span class="r3">reference</span><span class="r4">.</span>

<span class="r4">Start-string = &quot;|&quot;, end-string = &quot;|&quot; (optionally followed by &quot;_&quot; or &quot;__&quot;).</span>

<span class="r4">Vertical bars are used to bracket the substitution reference text.  A substitution reference may also be a hyperlink </span>
<span class="r4">reference by appending a &quot;_&quot; (named) or &quot;__&quot; (anonymous) suffix; the substitution text is used for the reference text in</span>
<span class="r4">the named case.</span>

<span class="r4">The processing system replaces substitution references with the processed contents of the corresponding </span><span class="r3">substitution </span>
<span class="r3">definitions</span><span class="r4"> (which see for the definition of &quot;correspond&quot;).  Substitution definitions produce inline-compatible </span>
<span class="r4">elements.</span>

<span class="r4">Examples:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> a simple </span><span class="r8">|</span><span class="r7">substitution reference</span><span class="r8">|.</span><span class="r7">  It will be replaced by</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">the processing system</span><span class="r8">.</span><span class="r9">                                                                                              </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r9">                                                                                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">This </span><span class="r8">is</span><span class="r7"> a combination </span><span class="r8">|</span><span class="r7">substitution </span><span class="r8">and</span><span class="r7"> hyperlink reference</span><span class="r8">|</span><span class="r7">_</span><span class="r8">.</span><span class="r7">  In</span><span class="r9">                                                  </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">addition to being replaced, the replacement text </span><span class="r8">or</span><span class="r7"> element will</span><span class="r9">                                                    </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">refer to the </span><span class="r11">&quot;substitution and hyperlink reference&quot;</span><span class="r7"> target</span><span class="r8">.</span><span class="r9">                                                         </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                Standalone Hyperlinks                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree element: </span><a class="r3" href="../doctree.html#reference">reference</a><span class="r4">.</span>

<span class="r4">No start-string or end-string.</span>

<span class="r4">A URI (absolute URI  or standalone email address) within a text block is treated as a general external hyperlink with </span>
<span class="r4">the URI itself as the link&#x27;s text.  For example:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org </span><span class="r12">for</span><span class="r7"> info</span><span class="r8">.</span><span class="r9">                                                                                </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">would be marked up in HTML as:</span>
<span class="r6">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r6">│</span> <span class="r7">See </span><span class="r8">&lt;</span><span class="r7">a href</span><span class="r8">=</span><span class="r11">&quot;https://www.python.org&quot;</span><span class="r8">&gt;</span><span class="r7">https:</span><span class="r8">//</span><span class="r7">www</span><span class="r8">.</span><span class="r7">python</span><span class="r8">.</span><span class="r7">org</span><span class="r8">&lt;/</span><span class="r7">a</span><span class="r8">&gt;</span><span class="r7"> </span><span class="r12">for</span><span class="r9">                                                 </span> <span class="r6">│</span>
<span class="r6">│</span> <span class="r7">info</span><span class="r8">.</span><span class="r9">                                                                                                               </span> <span class="r6">│</span>
<span class="r6">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r4">Two forms of URI are recognized:</span>

<span class="r5"> 1</span> Absolute URIs.  These consist of a scheme, a colon (&quot;:&quot;), and a scheme-specific part whose interpretation depends on 
scheme.  The scheme is the name of the protocol, such as &quot;http&quot;, &quot;ftp&quot;, &quot;mailto&quot;, or &quot;telnet&quot;.  The scheme consists of 
an initial letter, followed by letters, numbers, and/or &quot;+&quot;, &quot;-&quot;, &quot;.&quot;.  Recognition is limited to known schemes, per the
Official IANA Registry of URI Schemes and the W3C&#x27;s Retired Index of WWW Addressing Schemes.  The scheme-specific part 
of the resource identifier may be either hierarchical or opaque:  Hierarchical identifiers begin with one or two slashes
and may use slashes to separate hierarchical components of the path. Examples are web pages and FTP sites:  
https://www.python.org  ftp://ftp.python.org/pub/python  Opaque identifiers do not begin with slashes.  Examples are 
email addresses and newsgroups:  mailto:someone@somewhere.com  news:comp.lang.python  With queries, fragments, and 
%-escape sequences, URIs can become quite complicated.  A reStructuredText parser must be able to recognize any absolute
URI, as defined in RFC2396 and RFC2732.
<span class="r5"> 2</span> Standalone email addresses, which are treated as if they were absolute URIs with a &quot;mailto:&quot; scheme.  Example:  
someone@somewhere.com

<span class="r4">Punctuation at the end of a URI is not considered part of the URI, unless the URI is terminated by a closing angle </span>
<span class="r4">bracket (&quot;&gt;&quot;). Backslashes may be used in URIs to escape markup characters, specifically asterisks (&quot;*&quot;) and underscores</span>
<span class="r4">(&quot;_&quot;) which are valid URI characters (see </span><span class="r3">Escaping Mechanism</span><span class="r4"> above).</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Units                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">(New in Docutils 0.3.10.)</span>

<span class="r4">All measures consist of a positive floating point number in standard (non-scientific) notation and a unit, possibly </span>
<span class="r4">separated by one or more spaces.</span>

<span class="r4">Units are only supported where explicitly mentioned in the reference manuals.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Length Units                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">The following length units are supported by the reStructuredText parser:</span>

<span class="r5"> • </span>em (em unit, the element&#x27;s font size)
<span class="r5"> • </span>ex (ex unit, x-height of the elementâ€™s font)
<span class="r5"> • </span>mm (millimeters; 1Â mm = 1/1000Â m)
<span class="r5"> • </span>cm (centimeters; 1Â cm = 10Â mm)
<span class="r5"> • </span>in (inches; 1Â in = 2.54Â cm = 96Â px)
<span class="r5"> • </span>px (pixels, 1Â px = 1/96Â in) 
<span class="r5"> • </span>pt (points; 1Â pt = 1/72Â in)
<span class="r5"> • </span>pc (picas; 1Â pc = 1/6Â in = 12Â pt)

<span class="r4">This set corresponds to the </span><a class="r3" href="https://www.w3.org/TR/CSS2/syndata.html#length-units">length units in CSS2</a><span class="r4"> (a subset of </span><a class="r3" href="https://www.w3.org/TR/css-values-3/#absolute-lengths">length units in CSS3</a><span class="r4">).</span>

<span class="r4">The following are all valid length values: &quot;1.5em&quot;, &quot;20 mm&quot;, &quot;.5in&quot;.</span>

<span class="r4">Length values without unit are completed with a writer-dependent default (e.g. &quot;px&quot; with HTML, &quot;pt&quot; with latex2e). See </span>
<span class="r4">the writer specific documentation in the </span><span class="r3">user doc</span><span class="r4"> for details.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Percentage Units                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Percentage values have a percent sign (&quot;%&quot;) as unit.  Percentage values are relative to other values, depending on the </span>
<span class="r4">context in which they occur.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Error Handling                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r4">Doctree elements: </span><a class="r3" href="../doctree.html#system-message">system_message</a><span class="r4">, </span><a class="r3" href="../doctree.html#problematic">problematic</a><span class="r4">.</span>

<span class="r4">Markup errors are handled according to the specification in </span><a class="r3" href="../../peps/pep-0258.html">PEP 258</a><span class="r4">.</span>
<span class="r26">╭────────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 5); ──────────────────────────────────╮</span>
<span class="r26">│</span> <span class="r1">&lt;</span><span class="r27">rst-document</span><span class="r1">&gt;</span>:<span class="r26">5</span>: <span class="r1">(</span>INFO/<span class="r26">1</span><span class="r1">)</span> Enumerated list start value not ordinal-<span class="r26">1</span>: <span class="r28">&quot;6&quot;</span> <span class="r1">(</span>ordinal <span class="r26">6</span><span class="r1">)</span>                                <span class="r26">│</span>
<span class="r26">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r26">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 3197); ─────────────────────────────────╮</span>
<span class="r26">│</span> <span class="r1">&lt;</span><span class="r27">rst-document</span><span class="r1">&gt;</span>:<span class="r26">3197</span>: <span class="r1">(</span>INFO/<span class="r26">1</span><span class="r1">)</span> Duplicate explicit target name: <span class="r28">&quot;topic&quot;</span>.                                               <span class="r26">│</span>
<span class="r26">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r26">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 3208); ─────────────────────────────────╮</span>
<span class="r26">│</span> <span class="r1">&lt;</span><span class="r27">rst-document</span><span class="r1">&gt;</span>:<span class="r26">3208</span>: <span class="r1">(</span>INFO/<span class="r26">1</span><span class="r1">)</span> Duplicate explicit target name: <span class="r28">&quot;list_item&quot;</span>.                                           <span class="r26">│</span>
<span class="r26">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r26">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 3254); ─────────────────────────────────╮</span>
<span class="r26">│</span> <span class="r1">&lt;</span><span class="r27">rst-document</span><span class="r1">&gt;</span>:<span class="r26">3254</span>: <span class="r1">(</span>INFO/<span class="r26">1</span><span class="r1">)</span> Duplicate explicit target name: <span class="r28">&quot;reference&quot;</span>.                                           <span class="r26">│</span>
<span class="r26">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r26">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 3255); ─────────────────────────────────╮</span>
<span class="r26">│</span> <span class="r1">&lt;</span><span class="r27">rst-document</span><span class="r1">&gt;</span>:<span class="r26">3255</span>: <span class="r1">(</span>INFO/<span class="r26">1</span><span class="r1">)</span> Duplicate explicit target name: <span class="r28">&quot;reference&quot;</span>.                                           <span class="r26">│</span>
<span class="r26">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r29">┌─────────────────────────────────────────────────────── Footer ───────────────────────────────────────────────────────┐</span>
<span class="r29">│</span>                          In LaTeX, the default definition is 1Â px = 1/72Â in (cf. How to                            <span class="r29">│</span>
<span class="r29">│</span>                          configure the size of a pixel in the LaTeX writer documentation).                           <span class="r29">│</span>
<span class="r29">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
</code></pre>
</body>
</html>