File: directives_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 (1748 lines) | stat: -rw-r--r-- 306,472 bytes
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<style>
.r1 {font-weight: bold}
.r2 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #282a36}
.r3 {color: #949494; text-decoration-color: #949494}
.r4 {color: #ff4689; text-decoration-color: #ff4689; background-color: #272822}
.r5 {background-color: #272822}
.r6 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #272822}
.r7 {color: #e6db74; text-decoration-color: #e6db74; background-color: #272822}
.r8 {color: #bd93f9; text-decoration-color: #bd93f9; background-color: #282a36; text-decoration: underline}
.r9 {color: #ed007e; text-decoration-color: #ed007e; background-color: #1e0010}
.r10 {color: #f1fa8c; text-decoration-color: #f1fa8c; font-weight: bold}
.r11 {color: #a6e22e; text-decoration-color: #a6e22e; background-color: #272822}
.r12 {color: #ae81ff; text-decoration-color: #ae81ff; background-color: #272822}
.r13 {color: #8be9fd; text-decoration-color: #8be9fd}
.r14 {color: #66d9ef; text-decoration-color: #66d9ef; background-color: #272822}
.r15 {color: #ffffff; text-decoration-color: #ffffff; font-weight: bold}
.r16 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #282a36; font-style: italic}
.r17 {color: #c6c6c6; text-decoration-color: #c6c6c6; background-color: #121212}
.r18 {color: #ff79c6; text-decoration-color: #ff79c6}
.r19 {color: #ffffff; text-decoration-color: #ffffff}
.r20 {color: #e4e4e4; text-decoration-color: #e4e4e4}
.r21 {color: #f8f8f2; text-decoration-color: #f8f8f2; background-color: #282a36; font-weight: bold}
.r22 {color: #ff5555; text-decoration-color: #ff5555}
.r23 {color: #8be9fd; text-decoration-color: #8be9fd; font-weight: bold}
.r24 {color: #ff79c6; text-decoration-color: #ff79c6; font-weight: bold}
.r25 {color: #50fa7b; text-decoration-color: #50fa7b}
.r26 {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 Directives                                              ║</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. Jan 2022) $ │
├────────────┼───────────────────────────────────────────────────────┤
│ <span class="r1">Copyright </span> │ This document has been placed in the public domain.   │
└────────────┴───────────────────────────────────────────────────────┘
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Contents                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">This document describes the directives implemented in the reference reStructuredText parser.</span>

<span class="r2">Directives have the following syntax:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">+-------+-------------------------------+</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">|</span><span class="r6"> </span><span class="r7">&quot;.. &quot;</span><span class="r6"> </span><span class="r4">|</span><span class="r6"> directive type </span><span class="r7">&quot;::&quot;</span><span class="r6"> directive </span><span class="r4">|</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">+-------+</span><span class="r6"> block                         </span><span class="r4">|</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        </span><span class="r4">|</span><span class="r6">                               </span><span class="r4">|</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        </span><span class="r4">+-------------------------------+</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Directives begin with an explicit markup start (two periods and a space), followed by the directive type and two colons </span>
<span class="r2">(collectively, the &quot;directive marker&quot;).  The directive block begins immediately after the directive marker, and includes</span>
<span class="r2">all subsequent indented lines.  The directive block is divided into arguments, options (a field list), and content (in </span>
<span class="r2">that order), any of which may appear.  See the </span><a class="r8" href="restructuredtext.html#directives">Directives</a><span class="r2"> section in the </span><a class="r8" href="restructuredtext.html">reStructuredText Markup Specification</a><span class="r2"> for </span>
<span class="r2">syntax details.</span>

<span class="r2">Descriptions below list &quot;doctree elements&quot; (document tree element names; XML DTD generic identifiers) corresponding to </span>
<span class="r2">individual directives.  For details on the hierarchy of elements, please see </span><a class="r8" href="../doctree.html">The Docutils Document Tree</a><span class="r2"> and the </span><a class="r8" href="../docutils.dtd">Docutils</a>
<a class="r8" href="../docutils.dtd">Generic DTD</a><span class="r2"> XML document type definition.  For directive implementation details, see </span><a class="r8" href="../../howto/rst-directives.html">Creating reStructuredText </a>
<a class="r8" href="../../howto/rst-directives.html">Directives</a><span class="r2">.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                     Admonitions                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Specific Admonitions                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                         </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Types    </span> │ &quot;attention&quot;, &quot;caution&quot;, &quot;danger&quot;, &quot;error&quot;, &quot;hint&quot;,  │
│                     │ &quot;important&quot;, &quot;note&quot;, &quot;tip&quot;, &quot;warning&quot;, &quot;admonition&quot; │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ <span class="r1">Doctree Elements   </span> │ attention, caution, danger, error, hint, important, │
│                     │ note, tip, warning, admonition, title               │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                               │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                                         │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as body elements.                       │
└─────────────────────┴─────────────────────────────────────────────────────┘
<span class="r2">Admonitions are specially marked &quot;topics&quot; that can appear anywhere an ordinary body element can.  They contain arbitrary</span>
<span class="r2">body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with</span>
<span class="r2">a title matching the admonition type.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> DANGER::</span><span class="r5">                                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   Beware killer rabbits</span><span class="r9">!</span><span class="r5">                                                                                           </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">This directive might be rendered something like this:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">+------------------------+</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">|</span><span class="r6">        </span><span class="r9">!</span><span class="r6">DANGER</span><span class="r9">!</span><span class="r6">        </span><span class="r4">|</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">|</span><span class="r6">                        </span><span class="r4">|</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">|</span><span class="r6"> Beware killer rabbits</span><span class="r9">!</span><span class="r6"> </span><span class="r4">|</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">+------------------------+</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following admonition directives have been implemented:</span>

<span class="r10"> • </span>attention
<span class="r10"> • </span>caution
<span class="r10"> • </span>danger
<span class="r10"> • </span>error
<span class="r10"> • </span>hint
<span class="r10"> • </span>important
<span class="r10"> • </span>note
<span class="r10"> • </span>tip
<span class="r10"> • </span>warning

<span class="r2">Any text immediately following the directive indicator (on the same line and/or indented on following lines) is </span>
<span class="r2">interpreted as a directive block and is parsed for normal body elements.  For example, the following &quot;note&quot; admonition </span>
<span class="r2">directive contains one paragraph and a bullet list consisting of two list items:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> note:: This </span><span class="r4">is</span><span class="r6"> a note admonition</span><span class="r4">.</span><span class="r5">                                                                                </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   This </span><span class="r4">is</span><span class="r6"> the second line of the first paragraph</span><span class="r4">.</span><span class="r5">                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">-</span><span class="r6"> The note contains all indented body elements</span><span class="r5">                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     following</span><span class="r4">.</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">-</span><span class="r6"> It includes this bullet list</span><span class="r4">.</span><span class="r5">                                                                                  </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Generic Admonition                                                  ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                      </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;admonition&quot;                     │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Doctree Elements   </span> │ admonition, title                │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, required (admonition title) │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                      │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as body elements.    │
└─────────────────────┴──────────────────────────────────┘
<span class="r2">This is a generic, titled admonition.  The title may be anything the author desires.</span>

<span class="r2">The author-supplied title is also used as a </span><span class="r8">&quot;classes&quot;</span><span class="r2"> attribute value after being converted into a valid identifier form</span>
<span class="r2">(down-cased; non-alphanumeric characters converted to single hyphens; &quot;admonition-&quot; prefixed).  For example, this </span>
<span class="r2">admonition:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> admonition:: And, by the way</span><span class="r4">...</span><span class="r5">                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   You can make up your own admonition too</span><span class="r4">.</span><span class="r5">                                                                         </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">becomes the following document tree (pseudo-XML)</span>
<span class="r3">┌──────────────────────────────────────────────────────── xml ─────────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">&lt;document</span><span class="r6"> </span><span class="r11">source=</span><span class="r7">&quot;test data&quot;</span><span class="r4">&gt;</span><span class="r5">                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">&lt;admonition</span><span class="r6"> </span><span class="r11">classes=</span><span class="r7">&quot;admonition-and-by-the-way&quot;</span><span class="r4">&gt;</span><span class="r5">                                                                </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        </span><span class="r4">&lt;title&gt;</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">            And, by the way...</span><span class="r5">                                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        </span><span class="r4">&lt;paragraph&gt;</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">            You can make up your own admonition too.</span><span class="r5">                                                                </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The </span><span class="r8">class</span><span class="r2"> option overrides the computed </span><span class="r8">&quot;classes&quot;</span><span class="r2"> attribute value.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Images                                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">There are two image directives: &quot;image&quot; and &quot;figure&quot;.</span>

<span class="r2">It is up to the author to ensure compatibility of the image data format with the output format or user agent (</span><span class="r8">LaTeX</span><span class="r2"> </span>
<span class="r2">engine, </span><span class="r8">HTML5 browser</span><span class="r2">, ODT, ...). The following, non exhaustive table provides an overview</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Image                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;image&quot;                    │
├─────────────────────┼────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ image                      │
├─────────────────────┼────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, required (image URI). │
├─────────────────────┼────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).      │
├─────────────────────┼────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                      │
└─────────────────────┴────────────────────────────┘
<span class="r2">An &quot;image&quot; is a simple picture:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> image:: picture</span><span class="r4">.</span><span class="r6">png</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Inline images can be defined with an &quot;image&quot; directive in a </span><a class="r8" href="restructuredtext.html#substitution-definitions">substitution definition</a>

<span class="r2">The URI for the image source file is specified in the directive argument.  As with hyperlink targets, the image URI may </span>
<span class="r2">begin on the same line as the explicit markup start and target name, or it may begin in an indented text block </span>
<span class="r2">immediately following, with no intervening blank lines.  If there are multiple lines in the link block, they are </span>
<span class="r2">stripped of leading and trailing whitespace and joined together.</span>

<span class="r2">Optionally, the image link block may contain a flat field list, the .  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> image:: picture</span><span class="r4">.</span><span class="r6">jpeg</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :height: </span><span class="r12">100</span><span class="r6">px</span><span class="r5">                                                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :width: </span><span class="r12">200</span><span class="r6"> px</span><span class="r5">                                                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :scale: </span><span class="r12">50</span><span class="r6"> </span><span class="r4">%</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :alt: alternate text</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :align: right</span><span class="r5">                                                                                                    </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following options are recognized:</span>

    alt : <span class="r13">text</span>
      Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken 
by applications for visually impaired users.

    height : <span class="r13">length</span>
      The desired height of the image. Used to reserve space or scale the image vertically.  When the &quot;scale&quot; option is 
also specified, they are combined.  For example, a height of 200px and a scale of 50 is equivalent to a height of 100px 
with no scale.

    width : <span class="r13">length or percentage of the current line width</span>
      The width of the image. Used to reserve space or scale the image horizontally.  As with &quot;height&quot; above, when the 
&quot;scale&quot; option is also specified, they are combined.

    scale : <span class="r13">integer percentage (the &quot;%&quot; symbol is optional)</span>
      The uniform scaling factor of the image.  The default is &quot;100Â %&quot;, i.e. no scaling.  If no &quot;height&quot; or &quot;width&quot; 
options are specified, the Python Imaging Library (PIL/Pillow) may be used to determine them, if it is installed and the
image file is available.

    align : <span class="r13">&quot;top&quot;, &quot;middle&quot;, &quot;bottom&quot;, &quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span>
      The alignment of the image, equivalent to the HTML &lt;img&gt; tag&#x27;s deprecated &quot;align&quot; attribute or the corresponding 
&quot;vertical-align&quot; and &quot;text-align&quot; CSS properties. The values &quot;top&quot;, &quot;middle&quot;, and &quot;bottom&quot; control an image&#x27;s vertical 
alignment (relative to the text baseline); they are only useful for inline images (substitutions). The values &quot;left&quot;, 
&quot;center&quot;, and &quot;right&quot; control an image&#x27;s horizontal alignment, allowing the image to float and have the text flow around
it.  The specific behavior depends upon the browser or rendering software used.

    target : <span class="r13">text (URI or reference name)</span>
      Makes the image into a hyperlink reference (&quot;clickable&quot;).  The option argument may be a URI (relative or 
absolute), or a reference name with underscore suffix (e.g. `a name`_).
<span class="r2">and the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2">.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Figure                                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                       </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;figure&quot;                                          │
├─────────────────────┼───────────────────────────────────────────────────┤
│ <span class="r1">Doctree Elements   </span> │ figure, image, caption, legend                    │
├─────────────────────┼───────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, required (image URI).                        │
├─────────────────────┼───────────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).                             │
├─────────────────────┼───────────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as the figure caption and an optional │
│                     │ legend.                                           │
└─────────────────────┴───────────────────────────────────────────────────┘
<span class="r2">A &quot;figure&quot; consists of </span><span class="r8">image</span><span class="r2"> data (including </span><span class="r8">image options</span><span class="r2">), an optional caption (a single paragraph), and an optional </span>
<span class="r2">legend (arbitrary body elements). For page-based output media, figures might float to a different position if this helps</span>
<span class="r2">the page layout.</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> figure:: picture</span><span class="r4">.</span><span class="r6">png</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :scale: </span><span class="r12">50</span><span class="r6"> </span><span class="r4">%</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :alt: map to buried treasure</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   This </span><span class="r4">is</span><span class="r6"> the caption of the figure (a simple paragraph)</span><span class="r4">.</span><span class="r5">                                                          </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">There must be blank lines before the caption paragraph and before the legend.  To specify a legend without a caption, </span>
<span class="r2">use an empty comment (&quot;..&quot;) in place of the caption.</span>

<span class="r2">The &quot;figure&quot; directive supports all of the options of the &quot;image&quot; directive (see </span><span class="r8">image options</span><span class="r2"> above). These options </span>
<span class="r2">(except &quot;align&quot;) are passed on to the contained image.</span>

    align : <span class="r13">&quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span>
      The horizontal alignment of the figure, allowing the image to float and have the text flow around it.  The 
specific behavior depends upon the browser or rendering software used.
<span class="r2">In addition, the following options are recognized:</span>
    figwidth : <span class="r13">&quot;image&quot;, length, or percentage of current line width</span>
      The width of the figure. Limits the horizontal space used by the figure. A special value of &quot;image&quot; is allowed, in
which case the included image&#x27;s actual width is used (requires the Python Imaging Library). If the image file is not 
found or the required software is unavailable, this option is ignored.  Sets the &quot;width&quot; attribute of the &quot;figure&quot; 
doctree element.  This option does not scale the included image; use the &quot;width&quot; image option for that.

    figclass : <span class="r13">text</span>
      Set a &quot;classes&quot; attribute value on the figure element.  See the class directive below.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Body Elements                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Topic                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                    </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;topic&quot;                        │
├─────────────────────┼────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ topic                          │
├─────────────────────┼────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, required (topic title).   │
├─────────────────────┼────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                    │
├─────────────────────┼────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as the topic body. │
└─────────────────────┴────────────────────────────────┘
<span class="r2">A topic is like a block quote with a title, or a self-contained section with no subsections.  Use the &quot;topic&quot; directive </span>
<span class="r2">to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or</span>
<span class="r2">transition may occur.  Body elements and topics may not contain nested topics.</span>

<span class="r2">The directive&#x27;s sole argument is interpreted as the topic title; the next line must be blank.  All subsequent lines make</span>
<span class="r2">up the topic body, interpreted as body elements.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> topic:: Topic Title</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    Subsequent indented lines comprise</span><span class="r5">                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    the body of the topic, </span><span class="r4">and</span><span class="r6"> are</span><span class="r5">                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    interpreted </span><span class="r14">as</span><span class="r6"> body elements</span><span class="r4">.</span><span class="r5">                                                                                   </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Sidebar                                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                      </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;sidebar&quot;                        │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ sidebar                          │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional (sidebar title).   │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).            │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as the sidebar body. │
└─────────────────────┴──────────────────────────────────┘
<span class="r2">Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference </span>
<span class="r2">material.  A sidebar is typically offset by a border and &quot;floats&quot; to the side of the page; the document&#x27;s main text may </span>
<span class="r2">flow around it.  Sidebars can also be likened to super-footnotes; their content is outside of the flow of the document&#x27;s</span>
<span class="r2">main text.</span>

<span class="r2">Sidebars may occur anywhere a section or transition may occur.  Body elements (including sidebars) may not contain </span>
<span class="r2">nested sidebars.</span>

<span class="r2">The directive&#x27;s sole argument is interpreted as the sidebar title, which may be followed by a subtitle option (see </span>
<span class="r2">below); the next line must be blank.  All subsequent lines make up the sidebar body, interpreted as body elements.  For </span>
<span class="r2">example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> sidebar:: Optional Sidebar Title</span><span class="r5">                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :subtitle: Optional Sidebar Subtitle</span><span class="r5">                                                                             </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   Subsequent indented lines comprise</span><span class="r5">                                                                               </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   the body of the sidebar, </span><span class="r4">and</span><span class="r6"> are</span><span class="r5">                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   interpreted </span><span class="r14">as</span><span class="r6"> body elements</span><span class="r4">.</span><span class="r5">                                                                                    </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following options are recognized:</span>

    subtitle : <span class="r13">text</span>
      The sidebar&#x27;s subtitle.
<span class="r2">and the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2">.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Line Block                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r15">╭──────────────────────────────────────────────────── Admonition:  ────────────────────────────────────────────────────╮</span>
<span class="r15">│ Deprecated  The &quot;line-block&quot; directive is deprecated.  Use the line block syntax instead.                            │</span>
<span class="r15">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                         </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;line-block&quot;                        │
├─────────────────────┼─────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ line_block                          │
├─────────────────────┼─────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                               │
├─────────────────────┼─────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                         │
├─────────────────────┼─────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Becomes the body of the line block. │
└─────────────────────┴─────────────────────────────────────┘
<span class="r2">The &quot;line-block&quot; directive constructs an element where line breaks and initial indentation is significant and inline </span>
<span class="r2">markup is supported.  It is equivalent to a </span><span class="r8">parsed literal block</span><span class="r2"> with different rendering: typically in an ordinary </span>
<span class="r2">serif typeface instead of a typewriter/monospaced face, and not automatically indented.  (Have the line-block directive </span>
<span class="r2">begin a block quote to get an indented line block.)  Line blocks are useful for address blocks and verse (poetry, song </span>
<span class="r2">lyrics), where the structure of lines is significant.  For example, here&#x27;s a classic:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r7">&quot;To Ma Own Beloved Lassie: A Poem on her 17th Birthday&quot;</span><span class="r6">, by</span><span class="r5">                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">Ewan McTeagle (</span><span class="r14">for</span><span class="r6"> Lassie O</span><span class="r7">&#x27;Shea):</span><span class="r5">                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">..</span><span class="r6"> line</span><span class="r4">-</span><span class="r6">block::</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        Lend us a couple of bob till Thursday</span><span class="r4">.</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        I</span><span class="r7">&#x27;m absolutely skint.</span><span class="r5">                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        But I</span><span class="r7">&#x27;m expecting a postal order and I can pay you back</span><span class="r5">                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">            </span><span class="r14">as</span><span class="r6"> soon </span><span class="r14">as</span><span class="r6"> it comes</span><span class="r4">.</span><span class="r5">                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        Love, Ewan</span><span class="r4">.</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                 Parsed Literal Block                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                            </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;parsed-literal&quot;                       │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ literal_block                          │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                  │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                            │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Becomes the body of the literal block. │
└─────────────────────┴────────────────────────────────────────┘
<span class="r2">Unlike an ordinary literal block, the &quot;parsed-literal&quot; directive constructs a literal block where the text is parsed for</span>
<span class="r2">inline markup. It is equivalent to a </span><span class="r8">line block</span><span class="r2"> with different rendering: typically in a typewriter/monospaced typeface,</span>
<span class="r2">like an ordinary literal block.  Parsed literal blocks are useful for adding hyperlinks to code examples.</span>

<span class="r2">However, care must be taken with the text, because inline markup is recognized and there is no protection from parsing. </span>
<span class="r2">Backslash-escapes may be necessary to prevent unintended parsing.  And because the markup characters are removed by the </span>
<span class="r2">parser, care must also be taken with vertical alignment.  Parsed &quot;ASCII art&quot; is tricky, and extra whitespace may be </span>
<span class="r2">necessary.</span>

<span class="r2">For example, all the element names in this content model are links:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> parsed</span><span class="r4">-</span><span class="r6">literal::</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   ( (title_, subtitle_</span><span class="r9">?</span><span class="r6">)</span><span class="r9">?</span><span class="r6">,</span><span class="r5">                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     decoration_</span><span class="r9">?</span><span class="r6">,</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     (docinfo_, transition_</span><span class="r9">?</span><span class="r6">)</span><span class="r9">?</span><span class="r6">,</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r9">`</span><span class="r4">%</span><span class="r6">structure</span><span class="r4">.</span><span class="r6">model;</span><span class="r9">`</span><span class="r6">_ )</span><span class="r5">                                                                                         </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                         Code                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name            </span>┃<span class="r1"> Field Value                            </span>┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type       </span> │ &quot;code&quot;                                 │
├───────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Doctree Element      </span> │ literal_block, inline elements         │
├───────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Arguments  </span> │ One, optional (formal language).       │
├───────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Options    </span> │ name, class, number-lines.             │
├───────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Content    </span> │ Becomes the body of the literal block. │
├───────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Configuration Setting</span> │ syntax_highlight.                      │
└───────────────────────┴────────────────────────────────────────┘
<span class="r2">The &quot;code&quot; directive constructs a literal block. If the code language is specified, the content is parsed by the </span>
<span class="r8">Pygments</span><span class="r2"> syntax highlighter and tokens are stored in nested </span><a class="r8" href="../doctree.html#inline-elements">inline elements</a><span class="r2"> with class arguments according to their </span>
<span class="r2">syntactic category. The actual highlighting requires a style-sheet (e.g. one </span><span class="r8">generated by Pygments</span><span class="r2">, see the </span>
<span class="r8">sandbox/stylesheets</span><span class="r2"> for examples).</span>

<span class="r2">The parsing can be turned off with the </span><a class="r8" href="../../user/config.html#syntax-highlight">syntax_highlight</a><span class="r2"> configuration setting and command line option or by specifying </span>
<span class="r2">the language as </span><span class="r8">class</span><span class="r2"> option instead of directive argument. This also avoids warnings when </span><a class="r8" href="https://pygments.org/">Pygments</a><span class="r2"> is not installed or </span>
<span class="r2">the language is not in the </span><a class="r8" href="https://pygments.org/languages/">supported languages and markup formats</a><span class="r2">.</span>

<span class="r2">For inline code, use the </span><a class="r8" href="roles.html#code">&quot;code&quot; role</a><span class="r2">.</span>

<span class="r2">The following options are recognized:</span>

    number-lines : <span class="r13">[integer] (start line number)</span>
      Precede every line with a line number. The optional argument is the number of the first line (default 1).
<span class="r2">and the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2">.Example:</span>

<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">The content of the following directive ::</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">  </span><span class="r4">..</span><span class="r6"> code:: python</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r14">def</span><span class="r6"> </span><span class="r11">my_function</span><span class="r6">():</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        </span><span class="r7">&quot;just a test&quot;</span><span class="r5">                                                                                               </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        print </span><span class="r12">8</span><span class="r4">/</span><span class="r12">2</span><span class="r5">                                                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">is</span><span class="r6"> parsed </span><span class="r4">and</span><span class="r6"> marked up </span><span class="r14">as</span><span class="r6"> Python source code</span><span class="r4">.</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                         Math                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name            </span>┃<span class="r1"> Field Value                                          </span>┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type       </span> │ &quot;math&quot;                                               │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ <span class="r1">Doctree Element      </span> │ math_block                                           │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments  </span> │ None.                                                │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ <span class="r1">Directive Options    </span> │ class, name                                          │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ <span class="r1">Directive Content    </span> │ Becomes the body of the math block.                  │
│                       │ (Content blocks separated by a blank line are put in │
│                       │ adjacent math blocks.)                               │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ <span class="r1">Configuration Setting</span> │ math_output                                          │
└───────────────────────┴──────────────────────────────────────────────────────┘
<span class="r2">The &quot;math&quot; directive inserts blocks with mathematical content (display formulas, equations) into the document. The input</span>
<span class="r2">format is </span><a class="r8" href="../../ref/rst/mathematics.html">LaTeX math syntax</a><span class="r2"> with support for Unicode symbols, for example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> math::</span><span class="r5">                                                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">  Î</span><span class="r9">±</span><span class="r6">_t(i) </span><span class="r4">=</span><span class="r6"> P(O_1, O_2, â</span><span class="r9">€¦</span><span class="r6"> O_t, q_t </span><span class="r4">=</span><span class="r6"> S_i Î</span><span class="r9">»</span><span class="r6">)</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Support is limited to a subset of </span><span class="r16">LaTeX math</span><span class="r2"> by the conversion required for many output formats.  For HTML, the </span>
<a class="r8" href="../../user/config.html#math-output">math_output</a><span class="r2"> configuration setting (or the corresponding </span><span class="r17">--math-output</span><span class="r2"> command line option) select between alternative </span>
<span class="r2">output formats with different subsets of supported elements. If a writer does not support math typesetting, the content </span>
<span class="r2">is inserted verbatim.</span>

<span class="r2">For inline formulas, use the </span><a class="r8" href="roles.html#math">&quot;math&quot; role</a><span class="r2">.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Rubric                                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                  </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;rubric&quot;                     │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ rubric                       │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, required (rubric text). │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                  │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                        │
└─────────────────────┴──────────────────────────────┘
<span class="r18">▌ </span><span class="r19">rubric n. 1. a title, heading, or the like, in a manuscript,</span>
<span class="r19">book, statute, etc., written or printed in red or otherwise</span>
<span class="r19">distinguished from the rest of the text. ...</span>
<span class="r20">  - Random House Webster&#x27;s College Dictionary, 1991</span><span class="r2">The &quot;rubric&quot; directive inserts a &quot;rubric&quot; element into the document </span>
<span class="r2">tree.  A rubric is like an informal heading that doesn&#x27;t correspond to the document&#x27;s structure.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Epigraph                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                 </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;epigraph&quot;                                  │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ block_quote                                 │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as the body of the block quote. │
└─────────────────────┴─────────────────────────────────────────────┘
<span class="r2">An epigraph is an apposite (suitable, apt, or pertinent) short inscription, often a quotation or poem, at the beginning </span>
<span class="r2">of a document or section.</span>

<span class="r2">The &quot;epigraph&quot; directive produces an &quot;epigraph&quot;-class block quote. For example, this input:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> epigraph::</span><span class="r5">                                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   No matter where you go, there you are</span><span class="r4">.</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">--</span><span class="r6"> Buckaroo Banzai</span><span class="r5">                                                                                               </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">becomes this document tree fragment:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">&lt;</span><span class="r6">block_quote classes</span><span class="r4">=</span><span class="r7">&quot;epigraph&quot;</span><span class="r4">&gt;</span><span class="r5">                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">&lt;</span><span class="r6">paragraph</span><span class="r4">&gt;</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        No matter where you go, there you are</span><span class="r4">.</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">&lt;</span><span class="r6">attribution</span><span class="r4">&gt;</span><span class="r5">                                                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        Buckaroo Banzai</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Highlights                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                 </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;highlights&quot;                                │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ block_quote                                 │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as the body of the block quote. │
└─────────────────────┴─────────────────────────────────────────────┘
<span class="r2">Highlights summarize the main points of a document or section, often consisting of a list.</span>

<span class="r2">The &quot;highlights&quot; directive produces a &quot;highlights&quot;-class block quote. See </span><span class="r8">Epigraph</span><span class="r2"> above for an analogous example.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Pull-Quote                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                 </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;pull-quote&quot;                                │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ block_quote                                 │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as the body of the block quote. │
└─────────────────────┴─────────────────────────────────────────────┘
<span class="r2">A pull-quote is a small selection of text &quot;pulled out and quoted&quot;, typically in a larger typeface.  Pull-quotes are used</span>
<span class="r2">to attract attention, especially in long articles.</span>

<span class="r2">The &quot;pull-quote&quot; directive produces a &quot;pull-quote&quot;-class block quote. See </span><span class="r8">Epigraph</span><span class="r2"> above for an analogous example.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Compound Paragraph                                                  ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                   </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;compound&quot;                    │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ compound                      │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                         │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                   │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as body elements. │
└─────────────────────┴───────────────────────────────┘
<span class="r2">The &quot;compound&quot; directive is used to create a compound paragraph, which is a single logical paragraph containing multiple</span>
<span class="r2">physical body elements such as simple paragraphs, literal blocks, tables, lists, etc., instead of directly containing </span>
<span class="r2">text and inline elements.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> compound::</span><span class="r5">                                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   The </span><span class="r7">&#x27;rm&#x27;</span><span class="r6"> command </span><span class="r4">is</span><span class="r6"> very dangerous</span><span class="r4">.</span><span class="r6">  If you are logged</span><span class="r5">                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">in</span><span class="r6"> </span><span class="r14">as</span><span class="r6"> root </span><span class="r4">and</span><span class="r6"> enter ::</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">       cd </span><span class="r4">/</span><span class="r5">                                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">       rm </span><span class="r4">-</span><span class="r6">rf </span><span class="r4">*</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   you will erase the entire contents of your file system</span><span class="r4">.</span><span class="r5">                                                          </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">In the example above, a literal block is &quot;embedded&quot; within a sentence that begins in one physical paragraph and ends in </span>
<span class="r2">another.</span>

<span class="r15">╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮</span>
<span class="r15">│ The &quot;compound&quot; directive is not a generic block-level container like HTML&#x27;s &lt;div&gt; element.  Do not use it only to    │</span>
<span class="r15">│ group a sequence of elements, or you may get unexpected results.  If you need a generic block-level container,       │</span>
<span class="r15">│ please use the container directive, described below.                                                                 │</span>
<span class="r15">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r2">Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to </span>
<span class="r2">emphasize their logical unity:</span>

<span class="r10"> • </span>If paragraphs are rendered with a first-line indent, only the first physical paragraph of a compound paragraph should
have that indent -- second and further physical paragraphs should omit the indents;
<span class="r10"> • </span>vertical spacing between physical elements may be reduced;
<span class="r10"> • </span>and so on.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Container                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                          </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;container&quot;                          │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ container                            │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One or more, optional (class names). │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ name                                 │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as body elements.        │
└─────────────────────┴──────────────────────────────────────┘
<span class="r2">The &quot;container&quot; directive surrounds its contents (arbitrary body elements) with a generic block-level &quot;container&quot; </span>
<span class="r2">element.  Combined with the optional &quot;</span><span class="r8">classes</span><span class="r2">&quot; attribute argument(s), this is an extension mechanism for users &amp; </span>
<span class="r2">applications.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> container:: custom</span><span class="r5">                                                                                               </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   This paragraph might be rendered </span><span class="r4">in</span><span class="r6"> a custom way</span><span class="r4">.</span><span class="r5">                                                                </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Parsing the above results in the following pseudo-XML</span>
<span class="r3">┌──────────────────────────────────────────────────────── xml ─────────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">&lt;container</span><span class="r6"> </span><span class="r11">classes=</span><span class="r7">&quot;custom&quot;</span><span class="r4">&gt;</span><span class="r5">                                                                                        </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">&lt;paragraph&gt;</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        This paragraph might be rendered in a custom way.</span><span class="r5">                                                           </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The &quot;container&quot; directive is the equivalent of HTML&#x27;s </span><span class="r17">&lt;div&gt;</span><span class="r2"> element.  It may be used to group a sequence of elements for</span>
<span class="r2">user- or application-specific purposes.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Tables                                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">Formal tables need more structure than the reStructuredText syntax supplies.  Tables may be given titles with the </span><a class="r8" href="../doctree.html#table">table</a><span class="r2"> </span>
<span class="r2">directive. Sometimes reStructuredText tables are inconvenient to write, or table data in a standard format is readily </span>
<span class="r2">available.  The </span><span class="r8">csv-table</span><span class="r2"> directive supports CSV data.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Table                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                      </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;table&quot;                          │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ table                            │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional (table title).     │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).            │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ A normal reStructuredText table. │
└─────────────────────┴──────────────────────────────────┘
<span class="r2">The &quot;table&quot; directive is used to associate a title with a table or specify options, e.g.:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> table:: Truth table </span><span class="r14">for</span><span class="r6"> </span><span class="r7">&quot;not&quot;</span><span class="r5">                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :widths: auto</span><span class="r5">                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">=====</span><span class="r6">  </span><span class="r4">=====</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     A    </span><span class="r4">not</span><span class="r6"> A</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">=====</span><span class="r6">  </span><span class="r4">=====</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r14">False</span><span class="r6">  </span><span class="r14">True</span><span class="r5">                                                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r14">True</span><span class="r6">   </span><span class="r14">False</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">=====</span><span class="r6">  </span><span class="r4">=====</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following options are recognized:</span>

    align : <span class="r13">&quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span>
      The horizontal alignment of the table (new in Docutils 0.13).

    width : <span class="r13">length or percentage</span>
      Sets the width of the table to the specified length or percentage of the line width.  If omitted, the renderer 
determines the width of the table based on its contents or the column widths.  

    widths : <span class="r13">&quot;auto&quot;, &quot;grid&quot;, or a list of integers</span>
      A list of relative column widths. The default is the width of the input columns (in characters).  &quot;auto&quot; delegates
the determination of column widths to the backend (LaTeX, the HTML browser, ...).  &quot;grid&quot; restores the default, 
overriding a table_style or class value &quot;colwidths-auto&quot;.
<span class="r2">Plus the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2">.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      CSV Table                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                           </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;csv-table&quot;                           │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ table                                 │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional (table title).          │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).                 │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ A CSV (comma-separated values) table. │
└─────────────────────┴───────────────────────────────────────┘
<span class="r10">╭───────────────────────────────────────────────────── Warning:  ──────────────────────────────────────────────────────╮</span>
<span class="r10">│ The &quot;csv-table&quot; directive&#x27;s &quot;:file:&quot; and &quot;:url:&quot; options represent a potential security holes.  They can be disabled │</span>
<span class="r10">│ with the &quot;file_insertion_enabled&quot; runtime setting.                                                                   │</span>
<span class="r10">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r2">The &quot;csv-table&quot; directive is used to create a table from CSV (comma-separated values) data.  CSV is a common data format</span>
<span class="r2">generated by spreadsheet applications and commercial databases.  The data may be internal (an integral part of the </span>
<span class="r2">document) or external (a separate file).</span>

<span class="r10"> • </span>Block markup and inline markup within cells is supported.  Line ends are recognized within cells.
<span class="r10"> • </span>There is no support for checking that the number of columns in each row is the same. The directive automatically adds
empty entries at the end of short rows.  Add &quot;strict&quot; option to verify input?

<span class="r2">Example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> csv</span><span class="r4">-</span><span class="r6">table:: Frozen Delights</span><span class="r9">!</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :header: </span><span class="r7">&quot;Treat&quot;</span><span class="r6">, </span><span class="r7">&quot;Quantity&quot;</span><span class="r6">, </span><span class="r7">&quot;Description&quot;</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :widths: </span><span class="r12">15</span><span class="r6">, </span><span class="r12">10</span><span class="r6">, </span><span class="r12">30</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r7">&quot;Albatross&quot;</span><span class="r6">, </span><span class="r12">2.99</span><span class="r6">, </span><span class="r7">&quot;On a stick!&quot;</span><span class="r5">                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r7">&quot;Crunchy Frog&quot;</span><span class="r6">, </span><span class="r12">1.49</span><span class="r6">, </span><span class="r7">&quot;If we took the bones out, it wouldn&#x27;t be</span><span class="r5">                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   crunchy, now would it</span><span class="r9">?</span><span class="r7">&quot;</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r7">&quot;Gannet Ripple&quot;</span><span class="r6">, </span><span class="r12">1.99</span><span class="r6">, </span><span class="r7">&quot;On a stick!&quot;</span><span class="r5">                                                                             </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following options are recognized:</span>

    align : <span class="r13">&quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span>
      The horizontal alignment of the table. (New in Docutils 0.13)

    delim : <span class="r13">char | &quot;tab&quot; | &quot;space&quot; </span>
      A one-character string used to separate fields. Defaults to , (comma).  May be specified as a Unicode code point; 
see the unicode directive for syntax details.

    encoding : <span class="r13">string</span>
      The text encoding of the external CSV data (file or URL). Defaults to the document&#x27;s input_encoding.

    escape : <span class="r13">char</span>
      A one-character string used to escape the delimiter or quote characters.  May be specified as a Unicode code 
point; see the unicode directive for syntax details.  Used when the delimiter is used in an unquoted field, or when 
quote characters are used within a field.  The default is to double-up the character, e.g. &quot;He said, &quot;&quot;Hi!&quot;&quot;&quot;  Add 
another possible value, &quot;double&quot;, to explicitly indicate the default case?

    file : <span class="r13">string (newlines removed)</span>
      The local filesystem path to a CSV data file.

    header : <span class="r13">CSV data</span>
      Supplemental data for the table header, added independently of and before any header-rows from the main CSV data. 
Must use the same CSV format as the main CSV data.

    header-rows : <span class="r13">integer</span>
      The number of rows of CSV data to use in the table header. Defaults to 0.

    keepspace : <span class="r13">flag (empty)</span>
      Treat whitespace immediately following the delimiter as significant.  The default is to ignore such whitespace.

    quote : <span class="r13">char</span>
      A one-character string used to quote elements containing the delimiter or which start with the quote character.  
Defaults to &quot; (quote).  May be specified as a Unicode code point; see the unicode directive for syntax details.

    stub-columns : <span class="r13">integer</span>
      The number of table columns to use as stubs (row titles, on the left).  Defaults to 0.

    url : <span class="r13">string (whitespace removed)</span>
      An Internet URL reference to a CSV data file.

    widths : <span class="r13">integer [integer...] or &quot;auto&quot;</span>
      A list of relative column widths. The default is equal-width columns (100%/#columns).  &quot;auto&quot; delegates the 
determination of column widths to the backend (LaTeX, the HTML browser, ...).

    width : <span class="r13">length or percentage</span>
      Sets the width of the table to the specified length or percentage of the line width.  If omitted, the renderer 
determines the width of the table based on its contents or the column widths.
<span class="r2">and the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2">.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      List Table                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                      </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;list-table&quot;                     │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ table                            │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional (table title).     │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).            │
├─────────────────────┼──────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ A uniform two-level bullet list. │
└─────────────────────┴──────────────────────────────────┘
<span class="r2">(This is an initial implementation; </span><span class="r8">further ideas</span><span class="r2"> may be implemented in the future.)</span>

<span class="r2">The &quot;list-table&quot; directive is used to create a table from data in a uniform two-level bullet list.  &quot;Uniform&quot; means that</span>
<span class="r2">each sublist (second-level list) must contain the same number of list items.</span>

<span class="r2">Example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> list</span><span class="r4">-</span><span class="r6">table:: Frozen Delights</span><span class="r9">!</span><span class="r5">                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :widths: </span><span class="r12">15</span><span class="r6"> </span><span class="r12">10</span><span class="r6"> </span><span class="r12">30</span><span class="r5">                                                                                                </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :header</span><span class="r4">-</span><span class="r6">rows: </span><span class="r12">1</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">*</span><span class="r6"> </span><span class="r4">-</span><span class="r6"> Treat</span><span class="r5">                                                                                                        </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> Quantity</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> Description</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">*</span><span class="r6"> </span><span class="r4">-</span><span class="r6"> Albatross</span><span class="r5">                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> </span><span class="r12">2.99</span><span class="r5">                                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> On a stick</span><span class="r9">!</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">*</span><span class="r6"> </span><span class="r4">-</span><span class="r6"> Crunchy Frog</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> </span><span class="r12">1.49</span><span class="r5">                                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> If we took the bones out, it wouldn</span><span class="r7">&#x27;t be</span><span class="r5">                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">       crunchy, now would it</span><span class="r9">?</span><span class="r5">                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">*</span><span class="r6"> </span><span class="r4">-</span><span class="r6"> Gannet Ripple</span><span class="r5">                                                                                                </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> </span><span class="r12">1.99</span><span class="r5">                                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r4">-</span><span class="r6"> On a stick</span><span class="r9">!</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following options are recognized:</span>

    align : <span class="r13">&quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span>
      The horizontal alignment of the table. (New in Docutils 0.13)

    header-rows : <span class="r13">integer</span>
      The number of rows of list data to use in the table header. Defaults to 0.

    stub-columns : <span class="r13">integer</span>
      The number of table columns to use as stubs (row titles, on the left).  Defaults to 0.  

    width : <span class="r13">length or percentage</span>
      Sets the width of the table to the specified length or percentage of the line width.  If omitted, the renderer 
determines the width of the table based on its contents or the column widths.  

    widths : <span class="r13">integer [integer...] or &quot;auto&quot;</span>
      A list of relative column widths. The default is equal-width columns (100%/#columns).  &quot;auto&quot; delegates the 
determination of column widths to the backend (LaTeX, the HTML browser, ...).
<span class="r2">and the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2">.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Document Parts                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                  Table of Contents                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value           </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;contents&quot;            │
├─────────────────────┼───────────────────────┤
│ <span class="r1">Doctree Elements   </span> │ pending, topic        │
├─────────────────────┼───────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional: title. │
├─────────────────────┼───────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below). │
├─────────────────────┼───────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                 │
└─────────────────────┴───────────────────────┘
<span class="r2">The &quot;contents&quot; directive generates a table of contents (TOC) in a </span><a class="r8" href="../doctree.html#topic">topic</a><span class="r2">.  Topics, and therefore tables of contents, may </span>
<span class="r2">occur anywhere a section or transition may occur.  Body elements and topics may not contain tables of contents.</span>

<span class="r2">Here&#x27;s the directive in its simplest form:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> contents::</span><span class="r5">                                                                                                       </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Language-dependent boilerplate text will be used for the title.  The English default title text is &quot;Contents&quot;.</span>

<span class="r2">An explicit title may be specified:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> contents:: Table of Contents</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The title may span lines, although it is not recommended:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> contents:: Here</span><span class="r7">&#x27;s a very long Table of</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   Contents title</span><span class="r5">                                                                                                   </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Options may be specified for the directive, using a field list:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> contents:: Table of Contents</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :depth: </span><span class="r12">2</span><span class="r5">                                                                                                        </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">If the default title is to be used, the options field list may begin on the same line as the directive marker:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> contents:: :depth: </span><span class="r12">2</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The following options are recognized:</span>

    depth : <span class="r13">integer</span>
      The number of section levels that are collected in the table of contents.  The default is unlimited depth.

    local : <span class="r13">flag (empty)</span>
      Generate a local table of contents.  Entries will only include subsections of the section in which the directive 
is given.  If no explicit title is given, the table of contents will not be titled.

    backlinks : <span class="r13">&quot;entry&quot; or &quot;top&quot; or &quot;none&quot;</span>
      Generate links from section headers back to the table of contents entries, the table of contents itself, or 
generate no back-links.

    class : <span class="r13">text</span>
      Set a &quot;classes&quot; attribute value on the topic element.  See the class directive below.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                             Automatic Section Numbering                                              ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name            </span>┃<span class="r1"> Field Value                                 </span>┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type       </span> │ &quot;sectnum&quot; or &quot;section-numbering&quot; (synonyms) │
├───────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Doctree Elements     </span> │ pending, generated                          │
├───────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments  </span> │ None.                                       │
├───────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Options    </span> │ Possible (see below).                       │
├───────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Directive Content    </span> │ None.                                       │
├───────────────────────┼─────────────────────────────────────────────┤
│ <span class="r1">Configuration Setting</span> │ sectnum_xform                               │
└───────────────────────┴─────────────────────────────────────────────┘
<span class="r2">The &quot;sectnum&quot; (or &quot;section-numbering&quot;) directive automatically numbers sections and subsections in a document (if not </span>
<span class="r2">disabled by the </span><span class="r17">--no-section-numbering</span><span class="r2"> command line option or the </span><a class="r8" href="../../user/config.html#sectnum-xform">sectnum_xform</a><span class="r2"> configuration setting).</span>

<span class="r2">Section numbers are of the &quot;multiple enumeration&quot; form, where each level has a number, separated by periods.  For </span>
<span class="r2">example, the title of section 1, subsection 2, subsubsection 3 would have &quot;1.2.3&quot; prefixed.</span>

<span class="r2">The &quot;sectnum&quot; directive does its work in two passes: the initial parse and a transform.  During the initial parse, a </span>
<span class="r2">&quot;pending&quot; element is generated which acts as a placeholder, storing any options internally. At a later stage in the </span>
<span class="r2">processing, the &quot;pending&quot; element triggers a transform, which adds section numbers to titles.  Section numbers are </span>
<span class="r2">enclosed in a &quot;generated&quot; element, and titles have their &quot;auto&quot; attribute set to &quot;1&quot;.</span>

<span class="r2">The following options are recognized:</span>

    depth : <span class="r13">integer</span>
      The number of section levels that are numbered by this directive. The default is unlimited depth.

    prefix : <span class="r13">string</span>
      An arbitrary string that is prefixed to the automatically generated section numbers.  It may be something like 
&quot;3.2.&quot;, which will produce &quot;3.2.1&quot;, &quot;3.2.2&quot;, &quot;3.2.2.1&quot;, and so on.  Note that any separating punctuation (in the 
example, a period, &quot;.&quot;) must be explicitly provided.  The default is no prefix.

    suffix : <span class="r13">string</span>
      An arbitrary string that is appended to the automatically generated section numbers.  The default is no suffix.

    start : <span class="r13">integer</span>
      The value that will be used for the first section number. Combined with prefix, this may be used to force the 
right numbering for a document split over several source files.  The default is 1.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Document Header &amp; Footer                                               ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                   </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Types    </span> │ &quot;header&quot; and &quot;footer&quot;         │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Doctree Elements   </span> │ decoration, header, footer    │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                         │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                         │
├─────────────────────┼───────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as body elements. │
└─────────────────────┴───────────────────────────────┘
<span class="r2">The &quot;header&quot; and &quot;footer&quot; directives create document decorations, useful for page navigation, notes, time/datestamp, </span>
<span class="r2">etc.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> header:: This space </span><span class="r14">for</span><span class="r6"> rent</span><span class="r4">.</span><span class="r5">                                                                                    </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">This will add a paragraph to the document header, which will appear at the top of the generated web page or at the top </span>
<span class="r2">of every printed page.</span>

<span class="r2">These directives may be used multiple times, cumulatively.  There is currently support for only one header and footer.</span>

<span class="r15">╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮</span>
<span class="r15">│ While it is possible to use the &quot;header&quot; and &quot;footer&quot; directives to create navigational elements for web pages, you  │</span>
<span class="r15">│ should be aware that Docutils is meant to be used for document processing, and that a navigation bar is not          │</span>
<span class="r15">│ typically part of a document.  Thus, you may soon find Docutils&#x27; abilities to be insufficient for these purposes.    │</span>
<span class="r15">│ At that time, you should consider using a documentation generator like Sphinx rather than the &quot;header&quot; and &quot;footer&quot;  │</span>
<span class="r15">│ directives.                                                                                                          │</span>
<span class="r15">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r2">In addition to the use of these directives to populate header and footer content, content may also be added </span>
<span class="r2">automatically by the processing system.  For example, if certain runtime settings are enabled, the document footer is </span>
<span class="r2">populated with processing information such as a datestamp, a link to </span><a class="r8" href="https://docutils.sourceforge.io">the Docutils website</a><span class="r2">, etc.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      References                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Target Footnotes                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                           </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;target-notes&quot;                        │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Doctree Elements   </span> │ pending, footnote, footnote_reference │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                 │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ class, name                           │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).                 │
├─────────────────────┼───────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                                 │
└─────────────────────┴───────────────────────────────────────┘
<span class="r2">The &quot;target-notes&quot; directive creates a footnote for each external target in the text, and corresponding footnote </span>
<span class="r2">references after each reference.  For every explicit target (of the form, </span><span class="r17">.. _target name: URL</span><span class="r2">) in the text, a footnote </span>
<span class="r2">will be generated containing the visible URL as content.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Footnotes                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">NOT IMPLEMENTED YET</span>

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value    </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;footnotes&quot;    │
├─────────────────────┼────────────────┤
│ <span class="r1">Doctree Elements   </span> │ pending, topic │
├─────────────────────┼────────────────┤
│ <span class="r1">Directive Arguments</span> │ None?          │
├─────────────────────┼────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible?      │
├─────────────────────┼────────────────┤
│ <span class="r1">Directive Content  </span> │ None.          │
└─────────────────────┴────────────────┘
<span class="r2">@@@</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Citations                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">NOT IMPLEMENTED YET</span>

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value    </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;citations&quot;    │
├─────────────────────┼────────────────┤
│ <span class="r1">Doctree Elements   </span> │ pending, topic │
├─────────────────────┼────────────────┤
│ <span class="r1">Directive Arguments</span> │ None?          │
├─────────────────────┼────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible?      │
├─────────────────────┼────────────────┤
│ <span class="r1">Directive Content  </span> │ None.          │
└─────────────────────┴────────────────┘
<span class="r2">@@@</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    HTML-Specific                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Imagemap                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">NOT IMPLEMENTED YET</span>

<span class="r21">Non-standard element: imagemap.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                       Directives for Substitution Definitions                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">The directives in this section may only be used in </span><span class="r8">substitution definitions</span><span class="r2">.  They may not be used directly, in </span>
<span class="r2">standalone context. The </span><a class="r8" href="../doctree.html#image">image</a><span class="r2"> directive may be used both in substitution definitions and in the standalone context.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                   Replacement Text                                                   ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                    </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;replace&quot;                                      │
├─────────────────────┼────────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ Text &amp; inline elements                         │
├─────────────────────┼────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                                          │
├─────────────────────┼────────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                          │
├─────────────────────┼────────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ A single paragraph; may contain inline markup. │
└─────────────────────┴────────────────────────────────────────────────┘
<span class="r2">The &quot;replace&quot; directive is used to indicate replacement text for a substitution reference.  It may be used within </span>
<span class="r8">substitution definitions</span><span class="r2"> only.  For example, this directive can be used to expand abbreviations:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|</span><span class="r6">reST</span><span class="r4">|</span><span class="r6"> replace:: reStructuredText</span><span class="r5">                                                                                </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">Yes, </span><span class="r4">|</span><span class="r6">reST</span><span class="r4">|</span><span class="r6"> </span><span class="r4">is</span><span class="r6"> a long word, so I can</span><span class="r7">&#x27;t blame anyone for wanting to</span><span class="r5">                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">abbreviate it</span><span class="r4">.</span><span class="r5">                                                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">As reStructuredText doesn&#x27;t support nested inline markup, the only way to create a reference with styled text is to use </span>
<span class="r2">substitutions with the &quot;replace&quot; directive:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">I recommend you </span><span class="r14">try</span><span class="r6"> </span><span class="r4">|</span><span class="r6">Python</span><span class="r4">|</span><span class="r6">_</span><span class="r4">.</span><span class="r5">                                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|</span><span class="r6">Python</span><span class="r4">|</span><span class="r6"> replace:: Python, </span><span class="r4">*</span><span class="r6">the</span><span class="r4">*</span><span class="r6"> best language around</span><span class="r5">                                                            </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> _Python: https:</span><span class="r4">//</span><span class="r6">www</span><span class="r4">.</span><span class="r6">python</span><span class="r4">.</span><span class="r6">org</span><span class="r4">/</span><span class="r5">                                                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Unicode Character Codes                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                     </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;unicode&quot;                                       │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ Text                                            │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One or more, required (Unicode character codes, │
│                     │ optional text, and comments).                   │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (see below).                           │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                                           │
└─────────────────────┴─────────────────────────────────────────────────┘
<span class="r2">The &quot;unicode&quot; directive converts Unicode character codes (numerical values) to characters, and may be used in </span>
<span class="r8">substitution definitions</span><span class="r2"> only.</span>

<span class="r2">The arguments, separated by spaces, can be:</span>

  <span class="r10"> ∘ </span>character codes as
  <span class="r10"> ∘ </span>decimal numbers or  hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character 
entities, e.g. &amp;#x1a2b;
    <span class="r10"> ▪ </span>decimal numbers or
    <span class="r10"> ▪ </span>hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. &amp;#x
<span class="r10"> • </span>hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. &amp;#x1a2b
<span class="r10"> • </span>text, which is used as-is.

<span class="r2">Text following &quot; .. &quot; is a comment and is ignored.  The spaces between the arguments are ignored and thus do not appear </span>
<span class="r2">in the output. Hexadecimal codes are case-insensitive.</span>

<span class="r2">For example, the following text:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">Copyright </span><span class="r4">|</span><span class="r6">copy</span><span class="r4">|</span><span class="r6"> </span><span class="r12">2003</span><span class="r6">, </span><span class="r4">|</span><span class="r6">BogusMegaCorp (TM)</span><span class="r4">|</span><span class="r6"> </span><span class="r4">|---|</span><span class="r5">                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">all rights reserved</span><span class="r4">.</span><span class="r5">                                                                                                </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|</span><span class="r6">copy</span><span class="r4">|</span><span class="r6"> unicode:: </span><span class="r12">0xA9</span><span class="r6"> </span><span class="r4">..</span><span class="r6"> copyright sign</span><span class="r5">                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|</span><span class="r6">BogusMegaCorp (TM)</span><span class="r4">|</span><span class="r6"> unicode:: BogusMegaCorp U</span><span class="r4">+</span><span class="r12">2122</span><span class="r5">                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">..</span><span class="r6"> </span><span class="r14">with</span><span class="r6"> trademark sign</span><span class="r5">                                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|---|</span><span class="r6"> unicode:: U</span><span class="r4">+</span><span class="r12">02014</span><span class="r6"> </span><span class="r4">..</span><span class="r6"> em dash</span><span class="r5">                                                                               </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :trim:</span><span class="r5">                                                                                                           </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">results in:</span>

    <span class="r19">Copyright copy 2003, BogusMegaCorp (TM) --- all rights reserved.</span>

<span class="r2">The following options are recognized:</span>
    ltrim : <span class="r13">flag (empty)</span>
      Whitespace to the left of the substitution reference is removed.

    rtrim : <span class="r13">flag (empty)</span>
      Whitespace to the right of the substitution reference is removed.

    trim : <span class="r13">flag (empty)</span>
      Equivalent to ltrim plus rtrim; whitespace on both sides of the substitution reference is removed.

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                         Date                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                  </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;date&quot;                       │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ Text                         │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional (date format). │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                        │
├─────────────────────┼──────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                        │
└─────────────────────┴──────────────────────────────┘
<span class="r2">The &quot;date&quot; directive generates the current local date and inserts it into the document as text.  This directive may be </span>
<span class="r2">used in substitution definitions only.</span>

<span class="r2">The optional directive content is interpreted as the desired date format, using the same codes as Python&#x27;s </span>
<span class="r8">time.strftime()</span><span class="r2"> function.  The default format is &quot;%Y-%m-%d&quot; (ISO 8601 date), but time fields can also be used.  </span>
<span class="r2">Examples:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|</span><span class="r6">date</span><span class="r4">|</span><span class="r6"> date::</span><span class="r5">                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> </span><span class="r4">|</span><span class="r6">time</span><span class="r4">|</span><span class="r6"> date:: </span><span class="r4">%</span><span class="r6">H:</span><span class="r4">%</span><span class="r6">M</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">Today</span><span class="r7">&#x27;s date is |date|.</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">This document was generated on </span><span class="r4">|</span><span class="r6">date</span><span class="r4">|</span><span class="r6"> at </span><span class="r4">|</span><span class="r6">time</span><span class="r4">|.</span><span class="r5">                                                                    </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Miscellaneous                                                     ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                       Including an External Document Fragment                                        ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name            </span>┃<span class="r1"> Field Value                                  </span>┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type       </span> │ &quot;include&quot;                                    │
├───────────────────────┼──────────────────────────────────────────────┤
│ <span class="r1">Doctree Elements     </span> │ Depend on data being included                │
│                       │ (literal_block with code or literal option). │
├───────────────────────┼──────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments  </span> │ One, required (path to the file to include). │
├───────────────────────┼──────────────────────────────────────────────┤
│ <span class="r1">Directive Options    </span> │ Possible (see below).                        │
├───────────────────────┼──────────────────────────────────────────────┤
│ <span class="r1">Directive Content    </span> │ None.                                        │
├───────────────────────┼──────────────────────────────────────────────┤
│ <span class="r1">Configuration Setting</span> │ file_insertion_enabled                       │
└───────────────────────┴──────────────────────────────────────────────┘
<span class="r10">╭───────────────────────────────────────────────────── Warning:  ──────────────────────────────────────────────────────╮</span>
<span class="r10">│ The &quot;include&quot; directive represents a potential security hole.  It can be disabled with the &quot;file_insertion_enabled&quot;  │</span>
<span class="r10">│ runtime setting.                                                                                                     │</span>
<span class="r10">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r2">The &quot;include&quot; directive reads a text file. The directive argument is the path to the file to be included, relative to </span>
<span class="r2">the document containing the directive. Unless the options </span><span class="r17">literal</span><span class="r2">, </span><span class="r17">code</span><span class="r2">, or </span><span class="r17">parser</span><span class="r2"> are given, the file is parsed in the </span>
<span class="r2">current document&#x27;s context at the point of the directive. For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">This first example will be parsed at the document level, </span><span class="r4">and</span><span class="r6"> can</span><span class="r5">                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">thus contain any construct, including section headers</span><span class="r4">.</span><span class="r5">                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> include:: inclusion</span><span class="r4">.</span><span class="r6">txt</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">Back </span><span class="r4">in</span><span class="r6"> the main document</span><span class="r4">.</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    This second example will be parsed </span><span class="r4">in</span><span class="r6"> a block quote context</span><span class="r4">.</span><span class="r5">                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    Therefore it may only contain body elements</span><span class="r4">.</span><span class="r6">  It may </span><span class="r4">not</span><span class="r5">                                                        </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    contain section headers</span><span class="r4">.</span><span class="r5">                                                                                        </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">..</span><span class="r6"> include:: inclusion</span><span class="r4">.</span><span class="r6">txt</span><span class="r5">                                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">If an included document fragment contains section structure, the title adornments must match those of the master </span>
<span class="r2">document.</span>

<span class="r2">Standard data files intended for inclusion in reStructuredText documents are distributed with the Docutils source code, </span>
<span class="r2">located in the &quot;docutils&quot; package in the </span><span class="r17">docutils/parsers/rst/include</span><span class="r2"> directory.  To access these files, use the special</span>
<span class="r2">syntax for standard &quot;include&quot; data files, angle brackets around the file name:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> include:: </span><span class="r4">&lt;</span><span class="r6">isonum</span><span class="r4">.</span><span class="r6">txt</span><span class="r4">&gt;</span><span class="r5">                                                                                           </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The current set of standard &quot;include&quot; data files consists of sets of substitution definitions.  See </span><span class="r8">reStructuredText </span>
<span class="r8">Standard Definition Files</span><span class="r2"> for details.</span>

<span class="r2">The following options are recognized:</span>

    start-line : <span class="r13">integer</span>
      Only the content starting from this line will be included. (As usual in Python, the first line has index 0 and 
negative values count from the end.)

    end-line : <span class="r13">integer</span>
      Only the content up to (but excluding) this line will be included.

    start-after : <span class="r13">text to find in the external data file</span>
      Only the content after the first occurrence of the specified text will be included.

    end-before : <span class="r13">text to find in the external data file</span>
      Only the content before the first occurrence of the specified text (but after any after text) will be included.

    parser : <span class="r13">parser name</span>
      Parse the included content with the specified parser. (New in Docutils 0.17)

    literal : <span class="r13">flag (empty)</span>
      The entire included text is inserted into the document as a single literal block.

    code : <span class="r13">[string] (formal language)</span>
      The argument and the included content are passed to the code directive (useful for program listings).

    number-lines : <span class="r13">[integer] (start line number)</span>
      Precede every code line with a line number. The optional argument is the number of the first line (default 1). 
Works only with code or literal.

    encoding : <span class="r13">string</span>
      The text encoding of the external data file.  Defaults to the document&#x27;s input_encoding.  

    tab-width : <span class="r13">integer</span>
      Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the 
tab_width configuration setting.  
<span class="r2">With </span><span class="r17">code</span><span class="r2"> or </span><span class="r17">literal</span><span class="r2"> the common options </span><span class="r8">class</span><span class="r2"> and </span><span class="r8">name</span><span class="r2"> are recognized as well.Combining </span><span class="r17">start/end-line</span><span class="r2"> and </span>
<span class="r17">start-after/end-before</span><span class="r2"> is possible. The text markers will be searched in the specified lines (further limiting the </span>
<span class="r2">included content).</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                Raw Data Pass-Through                                                 ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name            </span>┃<span class="r1"> Field Value                                        </span>┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type       </span> │ &quot;raw&quot;                                              │
├───────────────────────┼────────────────────────────────────────────────────┤
│ <span class="r1">Doctree Element      </span> │ raw                                                │
├───────────────────────┼────────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments  </span> │ One or more, required (output format types).       │
├───────────────────────┼────────────────────────────────────────────────────┤
│ <span class="r1">Directive Options    </span> │ Possible (see below).                              │
├───────────────────────┼────────────────────────────────────────────────────┤
│ <span class="r1">Directive Content    </span> │ Stored verbatim, uninterpreted.  None (empty) if a │
│                       │ &quot;file&quot; or &quot;url&quot; option given.                      │
├───────────────────────┼────────────────────────────────────────────────────┤
│ <span class="r1">Configuration Setting</span> │ raw_enabled                                        │
└───────────────────────┴────────────────────────────────────────────────────┘
<span class="r10">╭───────────────────────────────────────────────────── Warning:  ──────────────────────────────────────────────────────╮</span>
<span class="r10">│ The &quot;raw&quot; directive represents a potential security hole.  It can be disabled with the &quot;raw_enabled&quot; or              │</span>
<span class="r10">│ &quot;file_insertion_enabled&quot; runtime settings.                                                                           │</span>
<span class="r10">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r22">╭───────────────────────────────────────────────────── Caution:  ──────────────────────────────────────────────────────╮</span>
<span class="r22">│ The &quot;raw&quot; directive is a stop-gap measure allowing the author to bypass reStructuredText&#x27;s markup.  It is a          │</span>
<span class="r22">│ &quot;power-user&quot; feature that should not be overused or abused.  The use of &quot;raw&quot; ties documents to specific output      │</span>
<span class="r22">│ formats and makes them less portable.  If you often need to use the &quot;raw&quot; directive or a &quot;raw&quot;-derived interpreted   │</span>
<span class="r22">│ text role, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText.        │</span>
<span class="r22">│ Please describe your situation in a message to the Docutils-users mailing list.                                      │</span>
<span class="r22">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r2">The &quot;raw&quot; directive indicates non-reStructuredText data that is to be passed untouched to the Writer.  The names of the </span>
<span class="r2">output formats are given in the directive arguments.  The interpretation of the raw data is up to the Writer.  A Writer </span>
<span class="r2">may ignore any raw output not matching its format.</span>

<span class="r2">For example, the following input would be passed untouched by an HTML Writer:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> raw:: html</span><span class="r5">                                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   </span><span class="r4">&lt;</span><span class="r6">hr width</span><span class="r4">=</span><span class="r12">50</span><span class="r6"> size</span><span class="r4">=</span><span class="r12">10</span><span class="r4">&gt;</span><span class="r5">                                                                                            </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">A LaTeX Writer could insert the following raw content into its output stream:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> raw:: latex</span><span class="r5">                                                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   \setlength{\parindent}{</span><span class="r12">0</span><span class="r6">pt}</span><span class="r5">                                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Raw data can also be read from an external file, specified in a directive option.  In this case, the content block must </span>
<span class="r2">be empty.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> raw:: html</span><span class="r5">                                                                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :file: inclusion</span><span class="r4">.</span><span class="r6">html</span><span class="r5">                                                                                            </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Inline equivalents of the &quot;raw&quot; directive can be defined via </span><span class="r8">custom interpreted text roles</span><span class="r2"> derived from the </span><a class="r8" href="roles.html#raw">&quot;raw&quot; role</a><span class="r2">.</span>

<span class="r2">The following options are recognized:</span>

    file : <span class="r13">string (newlines removed)</span>
      The local filesystem path of a raw data file to be included.

    url : <span class="r13">string (whitespace removed)</span>
      An Internet URL reference to a raw data file to be included.

    encoding : <span class="r13">string</span>
      The text encoding of the external raw data (file or URL). Defaults to the document&#x27;s encoding (if specified).
<span class="r2">and the common option </span><span class="r8">class</span><span class="r2">.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                        Class                                                         ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                      </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;class&quot;                                          │
├─────────────────────┼──────────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ pending                                          │
├─────────────────────┼──────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One or more, required (class names / attribute   │
│                     │ values).                                         │
├─────────────────────┼──────────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                            │
├─────────────────────┼──────────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Optional.  If present, it is interpreted as body │
│                     │ elements.                                        │
└─────────────────────┴──────────────────────────────────────────────────┘
<span class="r2">The &quot;class&quot; directive sets the </span><span class="r8">&quot;classes&quot;</span><span class="r2"> attribute value on its content or on the first immediately following  </span>
<span class="r2">non-comment element . The directive argument consists of one or more space-separated class names. The names are </span>
<span class="r2">transformed to conform to the regular expression </span><span class="r17">[a-z](-?[a-z0-9]+)*</span><span class="r2"> (see </span><span class="r8">Identifier Normalization</span><span class="r2"> below).</span>

<span class="r2">Examples:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> class:: special</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">This </span><span class="r4">is</span><span class="r6"> a </span><span class="r7">&quot;special&quot;</span><span class="r6"> paragraph</span><span class="r4">.</span><span class="r5">                                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> class:: exceptional remarkable</span><span class="r5">                                                                                   </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">An Exceptional Section</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">======================</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">This </span><span class="r4">is</span><span class="r6"> an ordinary paragraph</span><span class="r4">.</span><span class="r5">                                                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> class:: multiple</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   First paragraph</span><span class="r4">.</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   Second paragraph</span><span class="r4">.</span><span class="r5">                                                                                                </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The text above is parsed and transformed into this doctree fragment:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> code</span><span class="r4">-</span><span class="r6">block:: xml</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
    <span class="r19">&lt;paragraph classes=&quot;special&quot;&gt;  This is a &quot;special&quot; paragraph.  &lt;section classes=&quot;exceptional remarkable&quot;&gt;  &lt;title&gt;  </span>
<span class="r19">An Exceptional Section  &lt;paragraph&gt;  This is an ordinary paragraph.  &lt;paragraph classes=&quot;multiple&quot;&gt;  First paragraph.  </span>
<span class="r19">&lt;paragraph classes=&quot;multiple&quot;&gt;  Second paragraph.</span>


<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Identifier Normalization                                               ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">Docutils </span><a class="r8" href="../doctree.html#classnames-type">class names</a><span class="r2"> and </span><a class="r8" href="../doctree.html#ids-type">identifier keys</a><span class="r2"> are normalized to conform to the regular expression &quot;</span><span class="r17">[a-z](-?[a-z0-9]+)*</span><span class="r2">&quot; by </span>
<span class="r2">converting</span>

<span class="r10"> • </span>alphabetic characters to lowercase,
<span class="r10"> • </span>accented characters to the base character,
<span class="r10"> • </span>non-alphanumeric characters to hyphens,
<span class="r10"> • </span>consecutive hyphens into one hyphen

<span class="r2">and stripping</span>

<span class="r10"> • </span>leading hyphens and number characters, and
<span class="r10"> • </span>trailing hyphens.

<span class="r2">For example </span><span class="r17">&quot;Rot.Gelb&amp;GrÃ¼n:+2008&quot;</span><span class="r2"> becomes </span><span class="r17">&quot;rot-gelb-grun-2008&quot;</span><span class="r2"> and </span><span class="r17">&quot;1000_Steps!&quot;</span><span class="r2"> becomes </span><span class="r17">&quot;steps&quot;</span><span class="r2">.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                      Rationale:                                                      ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">Identifier keys must be valid in all supported output formats.</span>

<span class="r2">For HTMLÂ 4.1 + CSS1 compatibility, identifiers should have no underscores, colons, or periods.  Hyphens may be used.</span>

<span class="r10"> • </span>The HTML 4.01 spec defines identifiers based on SGML tokens:  ID and NAME tokens must begin with a letter ([A-Za-z]) 
may be followed by any number of letters, digits ([0-9]), hyphens (&quot;-&quot;), underscores (&quot;_&quot;), colons (&quot;:&quot;), and periods 
(&quot;.&quot;).  https://www.w3.org/TR/html401/types.html#type-name
<span class="r10"> • </span>The CSS1 spec defines identifiers based on the &quot;name&quot; token (&quot;flex&quot; tokenizer notation below; &quot;latin1&quot; and &quot;escape&quot; 
8-bit characters have been replaced with XML entities):  unicode     \\[0-9a-f]{1,4} latin1      [&amp;iexcl;-&amp;yuml;] escape
{unicode}|\\[ -~&amp;iexcl;-&amp;yuml;] nmchar      [-A-Za-z0-9]|{latin1}|{escape} name        {nmchar}+

<span class="r2">The CSS1 rule requires underscores (&quot;_&quot;), colons (&quot;:&quot;), and periods (&quot;.&quot;) to be escaped , therefore </span><span class="r8">&quot;classes&quot;</span><span class="r2"> and </span><a class="r8" href="../doctree.html#ids">&quot;ids&quot;</a><span class="r2"> </span>
<span class="r2">attributes should not contain these characters.  Combined with HTML4.1 requirements (the first character must be a </span>
<span class="r2">letter; no &quot;unicode&quot;, &quot;latin1&quot;, or &quot;escape&quot; characters), this results in the regular expression </span><span class="r17">[A-Za-z][-A-Za-z0-9]*</span><span class="r2">. </span>
<span class="r2">Docutils adds a normalization by downcasing and merge of consecutive hyphens.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                            Custom Interpreted Text Roles                                             ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                                     </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;role&quot;                                          │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ None; affects subsequent parsing.               │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ Two; one required (new role name), one optional │
│                     │ (base role name, in parentheses).               │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ Possible (depends on base role).                │
├─────────────────────┼─────────────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ depends on base role.                           │
└─────────────────────┴─────────────────────────────────────────────────┘
<span class="r2">The &quot;role&quot; directive dynamically creates a custom </span><a class="r8" href="roles.html">interpreted text role</a><span class="r2"> and registers it with the parser.  This means </span>
<span class="r2">that after declaring a role like this:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> role:: custom</span><span class="r5">                                                                                                    </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">the document may use the new &quot;custom&quot; role:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">An example of using :custom:</span><span class="r9">`</span><span class="r6">interpreted text</span><span class="r9">`</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">This will be parsed into the following document tree fragment:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> code</span><span class="r4">-</span><span class="r6">block:: xml</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
    <span class="r19">&lt;paragraph&gt;  An example of using &lt;inline classes=&quot;custom&quot;&gt;  &lt;rst-document&gt;:1726: (ERROR/3) Unexpected indentation.  </span>
<span class="r19">interpreted text</span>

<span class="r2">The role must be declared in a document before it can be used.Role names are case insensitive and must conform to the </span>
<span class="r2">rules of simple </span><a class="r8" href="restructuredtext.html#reference-names">reference names</a><span class="r2"> (but do not share a namespace with hyperlinks, footnotes, and citations).The new role </span>
<span class="r2">may be based on an existing role, specified as a second argument in parentheses (whitespace optional):</span>

<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> role:: custom(emphasis)</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">:custom:</span><span class="r9">`</span><span class="r6">text</span><span class="r9">`</span><span class="r5">                                                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">The parsed result is as follows:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> code</span><span class="r4">-</span><span class="r6">block:: xml</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
    <span class="r19">&lt;paragraph&gt;  &lt;emphasis classes=&quot;custom&quot;&gt;  text</span>

<span class="r2">A special case is the </span><span class="r8">&quot;raw&quot; role</span><span class="r2">: derived roles enable inline </span><span class="r8">raw data pass-through</span><span class="r2">, e.g.:</span>

<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> role:: raw</span><span class="r4">-</span><span class="r6">role(raw)</span><span class="r5">                                                                                             </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :format: html latex</span><span class="r5">                                                                                              </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">:raw</span><span class="r4">-</span><span class="r6">role:</span><span class="r9">`</span><span class="r6">raw text</span><span class="r9">`</span><span class="r5">                                                                                                </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">If no base role is explicitly specified, a generic custom role is automatically used.  Subsequent interpreted text will </span>
<span class="r2">produce an &quot;inline&quot; element with a </span><a class="r8" href="../doctree.html#classes">&quot;classes&quot;</a><span class="r2"> attribute, as in the first example above.</span>

<span class="r2">With most roles, the &quot;:class:&quot; option can be used to set a &quot;classes&quot; attribute that is different from the role name.  </span>
<span class="r2">For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> role:: custom</span><span class="r5">                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :class: special</span><span class="r5">                                                                                                  </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r5">                                                                                                                    </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">:custom:</span><span class="r9">`</span><span class="r6">interpreted text</span><span class="r9">`</span><span class="r5">                                                                                          </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">This is the parsed result:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> code</span><span class="r4">-</span><span class="r6">block:: xml</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
    <span class="r19">&lt;paragraph&gt;  &lt;inline classes=&quot;special&quot;&gt;  interpreted text</span>

<span class="r2">The following option is recognized by the &quot;role&quot; directive for most base roles:</span>
    class : <span class="r13">text</span>
      Set the &quot;classes&quot; attribute value on the element produced (inline, or element associated with a base class) when 
the custom interpreted text role is used.  If no directive options are specified, a &quot;class&quot; option with the directive 
argument (role name) as the value is implied.  See the class directive above.
<span class="r2">Specific base roles may support other options and/or directive content.  See the </span><a class="r8" href="roles.html">reStructuredText Interpreted Text Roles</a>
<span class="r2">document for details.</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                      Setting the Default Interpreted Text Role                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                            </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;default-role&quot;                         │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ None; affects subsequent parsing.      │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, optional (new default role name). │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                  │
├─────────────────────┼────────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                                  │
└─────────────────────┴────────────────────────────────────────┘
<span class="r2">The &quot;default-role&quot; directive sets the default interpreted text role, the role that is used for interpreted text without </span>
<span class="r2">an explicit role. For example, after setting the default role like this:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> default</span><span class="r4">-</span><span class="r6">role:: subscript</span><span class="r5">                                                                                         </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">any subsequent use of implicit-role interpreted text in the document will use the &quot;subscript&quot; role:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">An example of a </span><span class="r9">`</span><span class="r6">default</span><span class="r9">`</span><span class="r6"> role</span><span class="r4">.</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">This will be parsed into the following document tree fragment</span>
<span class="r3">┌──────────────────────────────────────────────────────── xml ─────────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">&lt;paragraph&gt;</span><span class="r5">                                                                                                         </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    An example of a</span><span class="r5">                                                                                                 </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r4">&lt;subscript&gt;</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">        default</span><span class="r5">                                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     role.</span><span class="r5">                                                                                                          </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Custom roles may be used (see the &quot;</span><span class="r8">role</span><span class="r2">&quot; directive above), but it must have been declared in a document before it can be</span>
<span class="r2">set as the default role.  See the </span><span class="r8">reStructuredText Interpreted Text Roles</span><span class="r2"> document for details of built-in roles.</span>

<span class="r2">The directive may be used without an argument to restore the initial default interpreted text role, which is </span>
<span class="r2">application-dependent.  The initial default interpreted text role of the standard reStructuredText parser is </span>
<span class="r2">&quot;title-reference&quot;.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                       Metadata                                                       ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                     </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;meta&quot;                          │
├─────────────────────┼─────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ meta                            │
├─────────────────────┼─────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                           │
├─────────────────────┼─────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                           │
├─────────────────────┼─────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Must contain a flat field list. │
└─────────────────────┴─────────────────────────────────┘
<span class="r2">The &quot;meta&quot; directive is used to specify metadata to be stored in, e.g., </span><a class="r8" href="https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element">HTML meta elements</a><span class="r2"> or as </span><a class="r8" href="https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Metadata">ODT file properties</a><span class="r2">. </span>
<span class="r2">The LaTeX writer passes it to the </span><span class="r17">pdfinfo</span><span class="r2"> option of the </span><a class="r8" href="https://ctan.org/pkg/hyperref">hyperref</a><span class="r2"> package. If an output format does not support </span>
<span class="r2">&quot;invisible&quot; metadata, content is silently dropped by the writer.</span>

<span class="r15">╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮</span>
<span class="r15">│ Data from some bibliographic fields is automatically extracted and stored as metadata, too. However, Bibliographic   │</span>
<span class="r15">│ Fields are also displayed in the document&#x27;s screen rendering or printout.  For an &quot;invisible&quot; document title, see    │</span>
<span class="r15">│ the metadata document title directive below.                                                                         │</span>
<span class="r15">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r2">Within the directive block, a flat field list provides the syntax for metadata.  The field name becomes the contents of </span>
<span class="r2">the &quot;name&quot; attribute of the META tag, and the field body (interpreted as a single string without inline markup) becomes </span>
<span class="r2">the contents of the &quot;content&quot; attribute.  For example:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> meta::</span><span class="r5">                                                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :description: The reStructuredText plaintext markup language</span><span class="r5">                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :keywords: plaintext, markup language</span><span class="r5">                                                                            </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">This would be converted to the following HTML</span>
<span class="r3">┌──────────────────────────────────────────────────────── html ────────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">&lt;</span><span class="r4">meta</span><span class="r6"> </span><span class="r11">name</span><span class="r4">=</span><span class="r7">&quot;description&quot;</span><span class="r5">                                                                                            </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">    </span><span class="r11">content</span><span class="r4">=</span><span class="r7">&quot;The reStructuredText plaintext markup language&quot;</span><span class="r6">&gt;</span><span class="r5">                                                       </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">&lt;</span><span class="r4">meta</span><span class="r6"> </span><span class="r11">name</span><span class="r4">=</span><span class="r7">&quot;keywords&quot;</span><span class="r6"> </span><span class="r11">content</span><span class="r4">=</span><span class="r7">&quot;plaintext, markup language&quot;</span><span class="r6">&gt;</span><span class="r5">                                                         </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Support for other META attributes (&quot;http-equiv&quot;, &quot;scheme&quot;, &quot;lang&quot;, &quot;dir&quot;) are provided through field arguments, which </span>
<span class="r2">must be of the form &quot;attr=value&quot;:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> meta::</span><span class="r5">                                                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :description lang</span><span class="r4">=</span><span class="r6">en: An amusing story</span><span class="r5">                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :description lang</span><span class="r4">=</span><span class="r6">fr: Une histoire amusante</span><span class="r5">                                                                      </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">And their HTML equivalents</span>
<span class="r3">┌──────────────────────────────────────────────────────── html ────────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">&lt;</span><span class="r4">meta</span><span class="r6"> </span><span class="r11">name</span><span class="r4">=</span><span class="r7">&quot;description&quot;</span><span class="r6"> </span><span class="r11">lang</span><span class="r4">=</span><span class="r7">&quot;en&quot;</span><span class="r6"> </span><span class="r11">content</span><span class="r4">=</span><span class="r7">&quot;An amusing story&quot;</span><span class="r6">&gt;</span><span class="r5">                                                      </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">&lt;</span><span class="r4">meta</span><span class="r6"> </span><span class="r11">name</span><span class="r4">=</span><span class="r7">&quot;description&quot;</span><span class="r6"> </span><span class="r11">lang</span><span class="r4">=</span><span class="r7">&quot;fr&quot;</span><span class="r6"> </span><span class="r11">content</span><span class="r4">=</span><span class="r7">&quot;Une histoire amusante&quot;</span><span class="r6">&gt;</span><span class="r5">                                                 </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">Some META tags use an &quot;http-equiv&quot; attribute instead of the &quot;name&quot; attribute.  To specify &quot;http-equiv&quot; META tags, simply</span>
<span class="r2">omit the name:</span>
<span class="r3">┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r4">..</span><span class="r6"> meta::</span><span class="r5">                                                                                                           </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">   :http</span><span class="r4">-</span><span class="r6">equiv</span><span class="r4">=</span><span class="r6">Content</span><span class="r4">-</span><span class="r6">Type: text</span><span class="r4">/</span><span class="r6">html; charset</span><span class="r4">=</span><span class="r6">ISO</span><span class="r4">-</span><span class="r12">8859</span><span class="r4">-</span><span class="r12">1</span><span class="r5">                                                          </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r2">HTML equivalent</span>
<span class="r3">┌──────────────────────────────────────────────────────── html ────────────────────────────────────────────────────────┐</span>
<span class="r3">│</span> <span class="r6">&lt;</span><span class="r4">meta</span><span class="r6"> </span><span class="r11">http-equiv</span><span class="r4">=</span><span class="r7">&quot;Content-Type&quot;</span><span class="r5">                                                                                     </span> <span class="r3">│</span>
<span class="r3">│</span> <span class="r6">     </span><span class="r11">content</span><span class="r4">=</span><span class="r7">&quot;text/html; charset=ISO-8859-1&quot;</span><span class="r6">&gt;</span><span class="r5">                                                                       </span> <span class="r3">│</span>
<span class="r3">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                               Metadata Document Title                                                ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                          </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;title&quot;                              │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ Sets the document&#x27;s title attribute. │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ One, required (the title text).      │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                                │
├─────────────────────┼──────────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ None.                                │
└─────────────────────┴──────────────────────────────────────┘
<span class="r2">The &quot;title&quot; directive specifies the document title as metadata, which does not become part of the document body. It </span>
<span class="r2">overrides the document-supplied </span><a class="r8" href="restructuredtext.html#document-title">document title</a><span class="r2"> and the </span><a class="r8" href="../../user/config.html#title">&quot;title&quot; configuration setting</a><span class="r2">. For example, in HTML output the </span>
<span class="r2">metadata document title appears in the title bar of the browser window.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                           Restructuredtext-Test-Directive                                            ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃<span class="r1"> Field Name          </span>┃<span class="r1"> Field Value                       </span>┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ <span class="r1">Directive Type     </span> │ &quot;restructuredtext-test-directive&quot; │
├─────────────────────┼───────────────────────────────────┤
│ <span class="r1">Doctree Element    </span> │ system_warning                    │
├─────────────────────┼───────────────────────────────────┤
│ <span class="r1">Directive Arguments</span> │ None.                             │
├─────────────────────┼───────────────────────────────────┤
│ <span class="r1">Directive Options  </span> │ None.                             │
├─────────────────────┼───────────────────────────────────┤
│ <span class="r1">Directive Content  </span> │ Interpreted as a literal block.   │
└─────────────────────┴───────────────────────────────────┘
<span class="r2">This directive is provided for test purposes only.  (Nobody is expected to type in a name </span><span class="r16">that</span><span class="r2"> long!)  It is converted </span>
<span class="r2">into a level-1 (info) system message showing the directive data, possibly followed by a literal block containing the </span>
<span class="r2">rest of the directive block.</span>

<span class="r1">╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗</span>
<span class="r1">║                                                    Common Options                                                    ║</span>
<span class="r1">╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝</span>
<span class="r2">Most of the directives that generate doctree elements support the following options:</span>

    class : <span class="r13">text (space separated list of class names)</span>
      Set a &quot;classes&quot; attribute value on the doctree element generated by the directive. See also the class directive.  

    name : <span class="r13">text</span>
      Add text to the &quot;names&quot; attribute of the doctree element generated by the directive. This allows hyperlink 
references to the element using text as reference name.  Specifying the name option of a directive, e.g.,  .. image:: 
bild.png    :name: my picture  is a concise syntax alternative to preceding it with a hyperlink target  .. _my picture: 
.. image:: bild.png
<span class="r23">╭───────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 982); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">982</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;contents&quot;</span>.                                             <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 1965); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">1965</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;class&quot;</span>.                                               <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 2006); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">2006</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;figure&quot;</span>.                                              <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 2010); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">2010</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;image&quot;</span>.                                               <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 2022); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">2022</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;rubric&quot;</span>.                                              <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 2023); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">2023</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;sidebar&quot;</span>.                                             <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 2024); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">2024</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;table&quot;</span>.                                               <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r23">╭──────────────────────────────── System Message: INFO/1 (&lt;rst-document&gt;, line 2027); ─────────────────────────────────╮</span>
<span class="r23">│</span> <span class="r1">&lt;</span><span class="r24">rst-document</span><span class="r1">&gt;</span>:<span class="r23">2027</span>: <span class="r1">(</span>INFO/<span class="r23">1</span><span class="r1">)</span> Duplicate implicit target name: <span class="r25">&quot;topic&quot;</span>.                                               <span class="r23">│</span>
<span class="r23">╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>
<span class="r26">┌─────────────────────────────────────────────────────── Footer ───────────────────────────────────────────────────────┐</span>
<span class="r26">│</span>                            &quot;Metadata&quot; is data about data, in this case data about the                                <span class="r26">│</span>
<span class="r26">│</span>                            document. Metadata is, e.g., used to describe and classify web                            <span class="r26">│</span>
<span class="r26">│</span>                            pages in the World Wide Web, in a form that is easy for search                            <span class="r26">│</span>
<span class="r26">│</span>                            engines to extract and collate.                                                           <span class="r26">│</span>
<span class="r26">└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘</span>
</code></pre>
</body>
</html>