ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/osprai/osprai/trunk/sphinx/reST_directives.html
Revision: 46
Committed: Fri Feb 4 00:29:01 2011 UTC (8 years, 3 months ago) by clausted
File size: 98992 byte(s)
Log Message:
Update the sphinx documentation.  Add a new file called mainapi.rst to join tutorial01.rst and index.rst.  
Line User Rev File contents
1 clausted 46 <?xml version="1.0" encoding="utf-8" ?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4     <head>
5     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6     <meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
7     <title>reStructuredText Directives</title>
8     <meta name="author" content="David Goodger" />
9     <meta name="date" content="2010-06-16" />
10     <meta name="copyright" content="This document has been placed in the public domain." />
11     <link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" />
12     </head>
13     <body>
14     <div class="document" id="restructuredtext-directives">
15     <h1 class="title">reStructuredText Directives</h1>
16     <table class="docinfo" frame="void" rules="none">
17     <col class="docinfo-name" />
18     <col class="docinfo-content" />
19     <tbody valign="top">
20     <tr><th class="docinfo-name">Author:</th>
21     <td>David Goodger</td></tr>
22     <tr><th class="docinfo-name">Contact:</th>
23     <td><a class="first last reference external" href="mailto:goodger&#64;python.org">goodger&#64;python.org</a></td></tr>
24     <tr><th class="docinfo-name">Revision:</th>
25     <td>6342</td></tr>
26     <tr><th class="docinfo-name">Date:</th>
27     <td>2010-06-16</td></tr>
28     <tr><th class="docinfo-name">Copyright:</th>
29     <td>This document has been placed in the public domain.</td></tr>
30     </tbody>
31     </table>
32     <div class="contents topic" id="contents">
33     <p class="topic-title first">Contents</p>
34     <ul class="simple">
35     <li><a class="reference internal" href="#admonitions" id="id8">Admonitions</a><ul>
36     <li><a class="reference internal" href="#specific-admonitions" id="id9">Specific Admonitions</a></li>
37     <li><a class="reference internal" href="#generic-admonition" id="id10">Generic Admonition</a></li>
38     </ul>
39     </li>
40     <li><a class="reference internal" href="#images" id="id11">Images</a><ul>
41     <li><a class="reference internal" href="#image" id="id12">Image</a></li>
42     <li><a class="reference internal" href="#figure" id="id13">Figure</a></li>
43     </ul>
44     </li>
45     <li><a class="reference internal" href="#body-elements" id="id14">Body Elements</a><ul>
46     <li><a class="reference internal" href="#topic" id="id15">Topic</a></li>
47     <li><a class="reference internal" href="#sidebar" id="id16">Sidebar</a></li>
48     <li><a class="reference internal" href="#line-block" id="id17">Line Block</a></li>
49     <li><a class="reference internal" href="#parsed-literal-block" id="id18">Parsed Literal Block</a></li>
50     <li><a class="reference internal" href="#rubric" id="id19">Rubric</a></li>
51     <li><a class="reference internal" href="#epigraph" id="id20">Epigraph</a></li>
52     <li><a class="reference internal" href="#highlights" id="id21">Highlights</a></li>
53     <li><a class="reference internal" href="#pull-quote" id="id22">Pull-Quote</a></li>
54     <li><a class="reference internal" href="#compound-paragraph" id="id23">Compound Paragraph</a></li>
55     <li><a class="reference internal" href="#container" id="id24">Container</a></li>
56     </ul>
57     </li>
58     <li><a class="reference internal" href="#tables" id="id25">Tables</a><ul>
59     <li><a class="reference internal" href="#table" id="id26">Table</a></li>
60     <li><a class="reference internal" href="#id1" id="id27">CSV Table</a></li>
61     <li><a class="reference internal" href="#list-table" id="id28">List Table</a></li>
62     </ul>
63     </li>
64     <li><a class="reference internal" href="#document-parts" id="id29">Document Parts</a><ul>
65     <li><a class="reference internal" href="#table-of-contents" id="id30">Table of Contents</a></li>
66     <li><a class="reference internal" href="#automatic-section-numbering" id="id31">Automatic Section Numbering</a></li>
67     <li><a class="reference internal" href="#document-header-footer" id="id32">Document Header &amp; Footer</a></li>
68     </ul>
69     </li>
70     <li><a class="reference internal" href="#references" id="id33">References</a><ul>
71     <li><a class="reference internal" href="#target-footnotes" id="id34">Target Footnotes</a></li>
72     <li><a class="reference internal" href="#footnotes" id="id35">Footnotes</a></li>
73     <li><a class="reference internal" href="#citations" id="id36">Citations</a></li>
74     </ul>
75     </li>
76     <li><a class="reference internal" href="#html-specific" id="id37">HTML-Specific</a><ul>
77     <li><a class="reference internal" href="#meta" id="id38">Meta</a></li>
78     <li><a class="reference internal" href="#imagemap" id="id39">Imagemap</a></li>
79     </ul>
80     </li>
81     <li><a class="reference internal" href="#directives-for-substitution-definitions" id="id40">Directives for Substitution Definitions</a><ul>
82     <li><a class="reference internal" href="#replacement-text" id="id41">Replacement Text</a></li>
83     <li><a class="reference internal" href="#unicode-character-codes" id="id42">Unicode Character Codes</a></li>
84     <li><a class="reference internal" href="#date" id="id43">Date</a></li>
85     </ul>
86     </li>
87     <li><a class="reference internal" href="#miscellaneous" id="id44">Miscellaneous</a><ul>
88     <li><a class="reference internal" href="#including-an-external-document-fragment" id="id45">Including an External Document Fragment</a></li>
89     <li><a class="reference internal" href="#raw-data-pass-through" id="id46">Raw Data Pass-Through</a></li>
90     <li><a class="reference internal" href="#class" id="id47">Class</a></li>
91     <li><a class="reference internal" href="#custom-interpreted-text-roles" id="id48">Custom Interpreted Text Roles</a></li>
92     <li><a class="reference internal" href="#setting-the-default-interpreted-text-role" id="id49">Setting the Default Interpreted Text Role</a></li>
93     <li><a class="reference internal" href="#metadata-document-title" id="id50">Metadata Document Title</a></li>
94     <li><a class="reference internal" href="#restructuredtext-test-directive" id="id51">Restructuredtext-Test-Directive</a></li>
95     </ul>
96     </li>
97     </ul>
98     </div>
99     <p>This document describes the directives implemented in the reference
100     reStructuredText parser.</p>
101     <p>Directives have the following syntax:</p>
102     <pre class="literal-block">
103     +-------+-------------------------------+
104     | &quot;.. &quot; | directive type &quot;::&quot; directive |
105     +-------+ block |
106     | |
107     +-------------------------------+
108     </pre>
109     <p>Directives begin with an explicit markup start (two periods and a
110     space), followed by the directive type and two colons (collectively,
111     the &quot;directive marker&quot;). The directive block begins immediately after
112     the directive marker, and includes all subsequent indented lines. The
113     directive block is divided into arguments, options (a field list), and
114     content (in that order), any of which may appear. See the <a class="reference external" href="restructuredtext.html#directives">Directives</a>
115     section in the <a class="reference external" href="restructuredtext.html">reStructuredText Markup Specification</a> for syntax
116     details.</p>
117     <p>Descriptions below list &quot;doctree elements&quot; (document tree element
118     names; XML DTD generic identifiers) corresponding to individual
119     directives. For details on the hierarchy of elements, please see <a class="reference external" href="../doctree.html">The
120     Docutils Document Tree</a> and the <a class="reference external" href="../docutils.dtd">Docutils Generic DTD</a> XML document
121     type definition. For directive implementation details, see <a class="reference external" href="../../howto/rst-directives.html">Creating
122     reStructuredText Directives</a>.</p>
123     <div class="section" id="admonitions">
124     <h1><a class="toc-backref" href="#id8">Admonitions</a></h1>
125     <div class="section" id="specific-admonitions">
126     <span id="warning"></span><span id="tip"></span><span id="note"></span><span id="important"></span><span id="hint"></span><span id="error"></span><span id="danger"></span><span id="caution"></span><span id="attention"></span><h2><a class="toc-backref" href="#id9">Specific Admonitions</a></h2>
127     <table class="docutils field-list" frame="void" rules="none">
128     <col class="field-name" />
129     <col class="field-body" />
130     <tbody valign="top">
131     <tr class="field"><th class="field-name">Directive Types:</th><td class="field-body">&quot;attention&quot;, &quot;caution&quot;, &quot;danger&quot;, &quot;error&quot;, &quot;hint&quot;,
132     &quot;important&quot;, &quot;note&quot;, &quot;tip&quot;, &quot;warning&quot;, &quot;admonition&quot;</td>
133     </tr>
134     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">attention, caution, danger, error, hint, important,
135     note, tip, warning, admonition, title</td>
136     </tr>
137     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
138     </tr>
139     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
140     </tr>
141     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as body elements.</td>
142     </tr>
143     </tbody>
144     </table>
145     <p>Admonitions are specially marked &quot;topics&quot; that can appear anywhere an
146     ordinary body element can. They contain arbitrary body elements.
147     Typically, an admonition is rendered as an offset block in a document,
148     sometimes outlined or shaded, with a title matching the admonition
149     type. For example:</p>
150     <pre class="literal-block">
151     .. DANGER::
152     Beware killer rabbits!
153     </pre>
154     <p>This directive might be rendered something like this:</p>
155     <pre class="literal-block">
156     +------------------------+
157     | !DANGER! |
158     | |
159     | Beware killer rabbits! |
160     +------------------------+
161     </pre>
162     <p>The following admonition directives have been implemented:</p>
163     <ul class="simple">
164     <li>attention</li>
165     <li>caution</li>
166     <li>danger</li>
167     <li>error</li>
168     <li>hint</li>
169     <li>important</li>
170     <li>note</li>
171     <li>tip</li>
172     <li>warning</li>
173     </ul>
174     <p>Any text immediately following the directive indicator (on the same
175     line and/or indented on following lines) is interpreted as a directive
176     block and is parsed for normal body elements. For example, the
177     following &quot;note&quot; admonition directive contains one paragraph and a
178     bullet list consisting of two list items:</p>
179     <pre class="literal-block">
180     .. note:: This is a note admonition.
181     This is the second line of the first paragraph.
182    
183     - The note contains all indented body elements
184     following.
185     - It includes this bullet list.
186     </pre>
187     </div>
188     <div class="section" id="generic-admonition">
189     <span id="admonition"></span><h2><a class="toc-backref" href="#id10">Generic Admonition</a></h2>
190     <table class="docutils field-list" frame="void" rules="none">
191     <col class="field-name" />
192     <col class="field-body" />
193     <tbody valign="top">
194     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;admonition&quot;</td>
195     </tr>
196     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">admonition, title</td>
197     </tr>
198     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, required (admonition title)</td>
199     </tr>
200     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
201     </tr>
202     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as body elements.</td>
203     </tr>
204     </tbody>
205     </table>
206     <p>This is a generic, titled admonition. The title may be anything the
207     author desires.</p>
208     <p>The author-supplied title is also used as a &quot;classes&quot; attribute value
209     after being converted into a valid identifier form (down-cased;
210     non-alphanumeric characters converted to single hyphens; &quot;admonition-&quot;
211     prefixed). For example, this admonition:</p>
212     <pre class="literal-block">
213     .. admonition:: And, by the way...
214    
215     You can make up your own admonition too.
216     </pre>
217     <p>becomes the following document tree (pseudo-XML):</p>
218     <pre class="literal-block">
219     &lt;document source=&quot;test data&quot;&gt;
220     &lt;admonition classes=&quot;admonition-and-by-the-way&quot;&gt;
221     &lt;title&gt;
222     And, by the way...
223     &lt;paragraph&gt;
224     You can make up your own admonition too.
225     </pre>
226     <p>The following option is recognized:</p>
227     <dl class="docutils">
228     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
229     <dd>Override the computed &quot;classes&quot; attribute value. See the <a class="reference internal" href="#class">class</a>
230     directive below.</dd>
231     </dl>
232     </div>
233     </div>
234     <div class="section" id="images">
235     <h1><a class="toc-backref" href="#id11">Images</a></h1>
236     <p>There are two image directives: &quot;image&quot; and &quot;figure&quot;.</p>
237     <div class="section" id="image">
238     <h2><a class="toc-backref" href="#id12">Image</a></h2>
239     <table class="docutils field-list" frame="void" rules="none">
240     <col class="field-name" />
241     <col class="field-body" />
242     <tbody valign="top">
243     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;image&quot;</td>
244     </tr>
245     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">image</td>
246     </tr>
247     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, required (image URI).</td>
248     </tr>
249     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
250     </tr>
251     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
252     </tr>
253     </tbody>
254     </table>
255     <p>An &quot;image&quot; is a simple picture:</p>
256     <pre class="literal-block">
257     .. image:: picture.png
258     </pre>
259     <p>The URI for the image source file is specified in the directive
260     argument. As with hyperlink targets, the image URI may begin on the
261     same line as the explicit markup start and target name, or it may
262     begin in an indented text block immediately following, with no
263     intervening blank lines. If there are multiple lines in the link
264     block, they are stripped of leading and trailing whitespace and joined
265     together.</p>
266     <p>Optionally, the image link block may contain a flat field list, the
267     <span class="target" id="image-options">image options</span>. For example:</p>
268     <pre class="literal-block">
269     .. image:: picture.jpeg
270     :height: 100px
271     :width: 200 px
272     :scale: 50 %
273     :alt: alternate text
274     :align: right
275     </pre>
276     <p>The following options are recognized:</p>
277     <dl class="docutils">
278     <dt><tt class="docutils literal">alt</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
279     <dd>Alternate text: a short description of the image, displayed by
280     applications that cannot display images, or spoken by applications
281     for visually impaired users.</dd>
282     <dt><tt class="docutils literal">height</tt> <span class="classifier-delimiter">:</span> <span class="classifier"><a class="reference external" href="restructuredtext.html#length-units">length</a></span></dt>
283     <dd>The desired height of the image.
284     Used to reserve space or scale the image vertically. When the &quot;scale&quot;
285     option is also specified, they are combined. For example, a height of
286     200px and a scale of 50 is equivalent to a height of 100px with no scale.</dd>
287     <dt><tt class="docutils literal">width</tt> <span class="classifier-delimiter">:</span> <span class="classifier"><a class="reference external" href="restructuredtext.html#length-units">length</a> or <a class="reference external" href="restructuredtext.html#percentage-units">percentage</a> of the current line width</span></dt>
288     <dd>The width of the image.
289     Used to reserve space or scale the image horizontally. As with &quot;height&quot;
290     above, when the &quot;scale&quot; option is also specified, they are combined.</dd>
291     <dt><tt class="docutils literal">scale</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer percentage (the &quot;%&quot; symbol is optional)</span></dt>
292     <dd><p class="first">The uniform scaling factor of the image. The default is &quot;100&nbsp;%&quot;, i.e.
293     no scaling.</p>
294     <p class="last">If no &quot;height&quot; or &quot;width&quot; options are specified, the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging
295     Library</a> (PIL) may be used to determine them, if it is installed and
296     the image file is available.</p>
297     </dd>
298     <dt><tt class="docutils literal">align</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;top&quot;, &quot;middle&quot;, &quot;bottom&quot;, &quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span></dt>
299     <dd>The alignment of the image, equivalent to the HTML <tt class="docutils literal">&lt;img&gt;</tt> tag's
300     &quot;align&quot; attribute. The values &quot;top&quot;, &quot;middle&quot;, and &quot;bottom&quot;
301     control an image's vertical alignment (relative to the text
302     baseline); they are only useful for inline images (substitutions).
303     The values &quot;left&quot;, &quot;center&quot;, and &quot;right&quot; control an image's
304     horizontal alignment, allowing the image to float and have the
305     text flow around it. The specific behavior depends upon the
306     browser or rendering software used.</dd>
307     <dt><tt class="docutils literal">target</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text (URI or reference name)</span></dt>
308     <dd>Makes the image into a hyperlink reference (&quot;clickable&quot;). The
309     option argument may be a URI (relative or absolute), or a
310     reference name with underscore suffix (e.g. <tt class="docutils literal">name_</tt>).</dd>
311     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
312     <dd>Set a &quot;classes&quot; attribute value on the image element. See the
313     <a class="reference internal" href="#class">class</a> directive below.</dd>
314     </dl>
315     </div>
316     <div class="section" id="figure">
317     <h2><a class="toc-backref" href="#id13">Figure</a></h2>
318     <table class="docutils field-list" frame="void" rules="none">
319     <col class="field-name" />
320     <col class="field-body" />
321     <tbody valign="top">
322     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;figure&quot;</td>
323     </tr>
324     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">figure, image, caption, legend</td>
325     </tr>
326     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, required (image URI).</td>
327     </tr>
328     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
329     </tr>
330     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as the figure caption and an optional
331     legend.</td>
332     </tr>
333     </tbody>
334     </table>
335     <p>A &quot;figure&quot; consists of <a class="reference internal" href="#image">image</a> data (including <a class="reference internal" href="#image-options">image options</a>), an optional
336     caption (a single paragraph), and an optional legend (arbitrary body
337     elements). For page-based output media, figures might float to a different
338     position if this helps the page layout.</p>
339     <pre class="literal-block">
340     .. figure:: picture.png
341     :scale: 50 %
342     :alt: map to buried treasure
343    
344     This is the caption of the figure (a simple paragraph).
345    
346     The legend consists of all elements after the caption. In this
347     case, the legend consists of this paragraph and the following
348     table:
349    
350     +-----------------------+-----------------------+
351     | Symbol | Meaning |
352     +=======================+=======================+
353     | .. image:: tent.png | Campground |
354     +-----------------------+-----------------------+
355     | .. image:: waves.png | Lake |
356     +-----------------------+-----------------------+
357     | .. image:: peak.png | Mountain |
358     +-----------------------+-----------------------+
359     </pre>
360     <p>There must be blank lines before the caption paragraph and before the
361     legend. To specify a legend without a caption, use an empty comment
362     (&quot;..&quot;) in place of the caption.</p>
363     <p>The &quot;figure&quot; directive supports all of the options of the &quot;image&quot;
364     directive (see <a class="reference internal" href="#image-options">image options</a> above). These options (except
365     &quot;align&quot;) are passed on to the contained image.</p>
366     <dl class="docutils">
367     <dt><tt class="docutils literal">align</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;left&quot;, &quot;center&quot;, or &quot;right&quot;</span></dt>
368     <dd>The horizontal alignment of the figure, allowing the image to
369     float and have the text flow around it. The specific behavior
370     depends upon the browser or rendering software used.</dd>
371     </dl>
372     <p>In addition, the following options are recognized:</p>
373     <dl class="docutils">
374     <dt><tt class="docutils literal">figwidth</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;image&quot;, <a class="reference external" href="restructuredtext.html#length-units">length</a>, or <a class="reference external" href="restructuredtext.html#percentage-units">percentage</a> of current line width</span></dt>
375     <dd><p class="first">The width of the figure.
376     Limits the horizontal space used by the figure.
377     A special value of &quot;image&quot; is allowed, in which case the
378     included image's actual width is used (requires the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging
379     Library</a>). If the image file is not found or the required software is
380     unavailable, this option is ignored.</p>
381     <p>Sets the &quot;width&quot; attribute of the &quot;figure&quot; doctree element.</p>
382     <p>This option does not scale the included image; use the &quot;width&quot;
383     <a class="reference internal" href="#image">image</a> option for that.</p>
384     <pre class="last literal-block">
385     +---------------------------+
386     | figure |
387     | |
388     |&lt;------ figwidth ---------&gt;|
389     | |
390     | +---------------------+ |
391     | | image | |
392     | | | |
393     | |&lt;--- width ---------&gt;| |
394     | +---------------------+ |
395     | |
396     |The figure's caption should|
397     |wrap at this width. |
398     +---------------------------+
399     </pre>
400     </dd>
401     <dt><tt class="docutils literal">figclass</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
402     <dd>Set a &quot;classes&quot; attribute value on the figure element. See the
403     <a class="reference internal" href="#class">class</a> directive below.</dd>
404     </dl>
405     </div>
406     </div>
407     <div class="section" id="body-elements">
408     <h1><a class="toc-backref" href="#id14">Body Elements</a></h1>
409     <div class="section" id="topic">
410     <h2><a class="toc-backref" href="#id15">Topic</a></h2>
411     <table class="docutils field-list" frame="void" rules="none">
412     <col class="field-name" />
413     <col class="field-body" />
414     <tbody valign="top">
415     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;topic&quot;</td>
416     </tr>
417     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">topic</td>
418     </tr>
419     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">1, required (topic title).</td>
420     </tr>
421     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
422     </tr>
423     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as the topic body.</td>
424     </tr>
425     </tbody>
426     </table>
427     <p>A topic is like a block quote with a title, or a self-contained
428     section with no subsections. Use the &quot;topic&quot; directive to indicate a
429     self-contained idea that is separate from the flow of the document.
430     Topics may occur anywhere a section or transition may occur. Body
431     elements and topics may not contain nested topics.</p>
432     <p>The directive's sole argument is interpreted as the topic title; the
433     next line must be blank. All subsequent lines make up the topic body,
434     interpreted as body elements. For example:</p>
435     <pre class="literal-block">
436     .. topic:: Topic Title
437    
438     Subsequent indented lines comprise
439     the body of the topic, and are
440     interpreted as body elements.
441     </pre>
442     <p>The following option is recognized:</p>
443     <dl class="docutils">
444     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
445     <dd>Set a &quot;classes&quot; attribute value on the topic element. See the
446     <a class="reference internal" href="#class">class</a> directive below.</dd>
447     </dl>
448     </div>
449     <div class="section" id="sidebar">
450     <h2><a class="toc-backref" href="#id16">Sidebar</a></h2>
451     <table class="docutils field-list" frame="void" rules="none">
452     <col class="field-name" />
453     <col class="field-body" />
454     <tbody valign="top">
455     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;sidebar&quot;</td>
456     </tr>
457     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">sidebar</td>
458     </tr>
459     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, required (sidebar title).</td>
460     </tr>
461     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
462     </tr>
463     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as the sidebar body.</td>
464     </tr>
465     </tbody>
466     </table>
467     <p>Sidebars are like miniature, parallel documents that occur inside
468     other documents, providing related or reference material. A sidebar
469     is typically offset by a border and &quot;floats&quot; to the side of the page;
470     the document's main text may flow around it. Sidebars can also be
471     likened to super-footnotes; their content is outside of the flow of
472     the document's main text.</p>
473     <p>Sidebars may occur anywhere a section or transition may occur. Body
474     elements (including sidebars) may not contain nested sidebars.</p>
475     <p>The directive's sole argument is interpreted as the sidebar title,
476     which may be followed by a subtitle option (see below); the next line
477     must be blank. All subsequent lines make up the sidebar body,
478     interpreted as body elements. For example:</p>
479     <pre class="literal-block">
480     .. sidebar:: Sidebar Title
481     :subtitle: Optional Sidebar Subtitle
482    
483     Subsequent indented lines comprise
484     the body of the sidebar, and are
485     interpreted as body elements.
486     </pre>
487     <p>The following options are recognized:</p>
488     <dl class="docutils">
489     <dt><tt class="docutils literal">subtitle</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
490     <dd>The sidebar's subtitle.</dd>
491     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
492     <dd>Set a &quot;classes&quot; attribute value on the sidebar element. See the
493     <a class="reference internal" href="#class">class</a> directive below.</dd>
494     </dl>
495     </div>
496     <div class="section" id="line-block">
497     <h2><a class="toc-backref" href="#id17">Line Block</a></h2>
498     <div class="admonition-deprecated admonition">
499     <p class="first admonition-title">Deprecated</p>
500     <p class="last">The &quot;line-block&quot; directive is deprecated. Use the <a class="reference external" href="restructuredtext.html#line-blocks">line block
501     syntax</a> instead.</p>
502     </div>
503     <table class="docutils field-list" frame="void" rules="none">
504     <col class="field-name" />
505     <col class="field-body" />
506     <tbody valign="top">
507     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;line-block&quot;</td>
508     </tr>
509     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">line_block</td>
510     </tr>
511     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
512     </tr>
513     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
514     </tr>
515     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Becomes the body of the line block.</td>
516     </tr>
517     </tbody>
518     </table>
519     <p>The &quot;line-block&quot; directive constructs an element where line breaks and
520     initial indentation is significant and inline markup is supported. It
521     is equivalent to a <a class="reference internal" href="#parsed-literal-block">parsed literal block</a> with different rendering:
522     typically in an ordinary serif typeface instead of a
523     typewriter/monospaced face, and not automatically indented. (Have the
524     line-block directive begin a block quote to get an indented line
525     block.) Line blocks are useful for address blocks and verse (poetry,
526     song lyrics), where the structure of lines is significant. For
527     example, here's a classic:</p>
528     <pre class="literal-block">
529     &quot;To Ma Own Beloved Lassie: A Poem on her 17th Birthday&quot;, by
530     Ewan McTeagle (for Lassie O'Shea):
531    
532     .. line-block::
533    
534     Lend us a couple of bob till Thursday.
535     I'm absolutely skint.
536     But I'm expecting a postal order and I can pay you back
537     as soon as it comes.
538     Love, Ewan.
539     </pre>
540     <p>The following option is recognized:</p>
541     <dl class="docutils">
542     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
543     <dd>Set a &quot;classes&quot; attribute value on the line_block element. See the
544     <a class="reference internal" href="#class">class</a> directive below.</dd>
545     </dl>
546     </div>
547     <div class="section" id="parsed-literal-block">
548     <span id="parsed-literal"></span><h2><a class="toc-backref" href="#id18">Parsed Literal Block</a></h2>
549     <table class="docutils field-list" frame="void" rules="none">
550     <col class="field-name" />
551     <col class="field-body" />
552     <tbody valign="top">
553     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;parsed-literal&quot;</td>
554     </tr>
555     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">literal_block</td>
556     </tr>
557     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
558     </tr>
559     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
560     </tr>
561     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Becomes the body of the literal block.</td>
562     </tr>
563     </tbody>
564     </table>
565     <p>Unlike an ordinary literal block, the &quot;parsed-literal&quot; directive
566     constructs a literal block where the text is parsed for inline markup.
567     It is equivalent to a <a class="reference internal" href="#line-block">line block</a> with different rendering:
568     typically in a typewriter/monospaced typeface, like an ordinary
569     literal block. Parsed literal blocks are useful for adding hyperlinks
570     to code examples.</p>
571     <p>However, care must be taken with the text, because inline markup is
572     recognized and there is no protection from parsing. Backslash-escapes
573     may be necessary to prevent unintended parsing. And because the
574     markup characters are removed by the parser, care must also be taken
575     with vertical alignment. Parsed &quot;ASCII art&quot; is tricky, and extra
576     whitespace may be necessary.</p>
577     <p>For example, all the element names in this content model are links:</p>
578     <pre class="literal-block">
579     .. parsed-literal::
580    
581     ( (title_, subtitle_?)?,
582     decoration_?,
583     (docinfo_, transition_?)?,
584     `%structure.model;`_ )
585     </pre>
586     <p>The following option is recognized:</p>
587     <dl class="docutils">
588     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
589     <dd>Set a &quot;classes&quot; attribute value on the literal_block element. See
590     the <a class="reference internal" href="#class">class</a> directive below.</dd>
591     </dl>
592     </div>
593     <div class="section" id="rubric">
594     <h2><a class="toc-backref" href="#id19">Rubric</a></h2>
595     <table class="docutils field-list" frame="void" rules="none">
596     <col class="field-name" />
597     <col class="field-body" />
598     <tbody valign="top">
599     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;rubric&quot;</td>
600     </tr>
601     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">rubric</td>
602     </tr>
603     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">1, required (rubric text).</td>
604     </tr>
605     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
606     </tr>
607     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
608     </tr>
609     </tbody>
610     </table>
611     <!-- -->
612     <blockquote>
613     <p>rubric n. 1. a title, heading, or the like, in a manuscript,
614     book, statute, etc., written or printed in red or otherwise
615     distinguished from the rest of the text. ...</p>
616     <p class="attribution">&mdash;Random House Webster's College Dictionary, 1991</p>
617     </blockquote>
618     <p>The &quot;rubric&quot; directive inserts a &quot;rubric&quot; element into the document
619     tree. A rubric is like an informal heading that doesn't correspond to
620     the document's structure.</p>
621     <p>The following option is recognized:</p>
622     <dl class="docutils">
623     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
624     <dd>Set a &quot;classes&quot; attribute value on the rubric element. See the
625     <a class="reference internal" href="#class">class</a> directive below.</dd>
626     </dl>
627     </div>
628     <div class="section" id="epigraph">
629     <h2><a class="toc-backref" href="#id20">Epigraph</a></h2>
630     <table class="docutils field-list" frame="void" rules="none">
631     <col class="field-name" />
632     <col class="field-body" />
633     <tbody valign="top">
634     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;epigraph&quot;</td>
635     </tr>
636     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">block_quote</td>
637     </tr>
638     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
639     </tr>
640     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
641     </tr>
642     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as the body of the block quote.</td>
643     </tr>
644     </tbody>
645     </table>
646     <p>An epigraph is an apposite (suitable, apt, or pertinent) short
647     inscription, often a quotation or poem, at the beginning of a document
648     or section.</p>
649     <p>The &quot;epigraph&quot; directive produces an &quot;epigraph&quot;-class block quote.
650     For example, this input:</p>
651     <pre class="literal-block">
652     .. epigraph::
653    
654     No matter where you go, there you are.
655    
656     -- Buckaroo Banzai
657     </pre>
658     <p>becomes this document tree fragment:</p>
659     <pre class="literal-block">
660     &lt;block_quote classes=&quot;epigraph&quot;&gt;
661     &lt;paragraph&gt;
662     No matter where you go, there you are.
663     &lt;attribution&gt;
664     Buckaroo Banzai
665     </pre>
666     </div>
667     <div class="section" id="highlights">
668     <h2><a class="toc-backref" href="#id21">Highlights</a></h2>
669     <table class="docutils field-list" frame="void" rules="none">
670     <col class="field-name" />
671     <col class="field-body" />
672     <tbody valign="top">
673     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;highlights&quot;</td>
674     </tr>
675     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">block_quote</td>
676     </tr>
677     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
678     </tr>
679     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
680     </tr>
681     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as the body of the block quote.</td>
682     </tr>
683     </tbody>
684     </table>
685     <p>Highlights summarize the main points of a document or section, often
686     consisting of a list.</p>
687     <p>The &quot;highlights&quot; directive produces a &quot;highlights&quot;-class block quote.
688     See <a class="reference internal" href="#epigraph">Epigraph</a> above for an analogous example.</p>
689     </div>
690     <div class="section" id="pull-quote">
691     <h2><a class="toc-backref" href="#id22">Pull-Quote</a></h2>
692     <table class="docutils field-list" frame="void" rules="none">
693     <col class="field-name" />
694     <col class="field-body" />
695     <tbody valign="top">
696     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;pull-quote&quot;</td>
697     </tr>
698     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">block_quote</td>
699     </tr>
700     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
701     </tr>
702     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
703     </tr>
704     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as the body of the block quote.</td>
705     </tr>
706     </tbody>
707     </table>
708     <p>A pull-quote is a small selection of text &quot;pulled out and quoted&quot;,
709     typically in a larger typeface. Pull-quotes are used to attract
710     attention, especially in long articles.</p>
711     <p>The &quot;pull-quote&quot; directive produces a &quot;pull-quote&quot;-class block quote.
712     See <a class="reference internal" href="#epigraph">Epigraph</a> above for an analogous example.</p>
713     </div>
714     <div class="section" id="compound-paragraph">
715     <span id="compound"></span><h2><a class="toc-backref" href="#id23">Compound Paragraph</a></h2>
716     <table class="docutils field-list" frame="void" rules="none">
717     <col class="field-name" />
718     <col class="field-body" />
719     <tbody valign="top">
720     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;compound&quot;</td>
721     </tr>
722     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">compound</td>
723     </tr>
724     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
725     </tr>
726     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
727     </tr>
728     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as body elements.</td>
729     </tr>
730     </tbody>
731     </table>
732     <p>(New in Docutils 0.3.6)</p>
733     <p>The &quot;compound&quot; directive is used to create a compound paragraph, which
734     is a single logical paragraph containing multiple physical body
735     elements such as simple paragraphs, literal blocks, tables, lists,
736     etc., instead of directly containing text and inline elements. For
737     example:</p>
738     <pre class="literal-block">
739     .. compound::
740    
741     The 'rm' command is very dangerous. If you are logged
742     in as root and enter ::
743    
744     cd /
745     rm -rf *
746    
747     you will erase the entire contents of your file system.
748     </pre>
749     <p>In the example above, a literal block is &quot;embedded&quot; within a sentence
750     that begins in one physical paragraph and ends in another.</p>
751     <div class="note">
752     <p class="first admonition-title">Note</p>
753     <p>The &quot;compound&quot; directive is <em>not</em> a generic block-level container
754     like HTML's <tt class="docutils literal">&lt;div&gt;</tt> element. Do not use it only to group a
755     sequence of elements, or you may get unexpected results.</p>
756     <p class="last">If you need a generic block-level container, please use the
757     <a class="reference internal" href="#container">container</a> directive, described below.</p>
758     </div>
759     <p>Compound paragraphs are typically rendered as multiple distinct text
760     blocks, with the possibility of variations to emphasize their logical
761     unity:</p>
762     <ul class="simple">
763     <li>If paragraphs are rendered with a first-line indent, only the first
764     physical paragraph of a compound paragraph should have that indent
765     -- second and further physical paragraphs should omit the indents;</li>
766     <li>vertical spacing between physical elements may be reduced;</li>
767     <li>and so on.</li>
768     </ul>
769     <p>The following option is recognized:</p>
770     <dl class="docutils">
771     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
772     <dd>Set a &quot;classes&quot; attribute value on the compound element. See the
773     <a class="reference internal" href="#class">class</a> directive below.</dd>
774     </dl>
775     </div>
776     <div class="section" id="container">
777     <h2><a class="toc-backref" href="#id24">Container</a></h2>
778     <table class="docutils field-list" frame="void" rules="none">
779     <col class="field-name" />
780     <col class="field-body" />
781     <tbody valign="top">
782     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;container&quot;</td>
783     </tr>
784     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">container</td>
785     </tr>
786     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One or more, optional (class names).</td>
787     </tr>
788     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
789     </tr>
790     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as body elements.</td>
791     </tr>
792     </tbody>
793     </table>
794     <p>(New in Docutils 0.3.10)</p>
795     <p>The &quot;container&quot; directive surrounds its contents (arbitrary body
796     elements) with a generic block-level &quot;container&quot; element. Combined
797     with the optional &quot;<a class="reference internal" href="#classes">classes</a>&quot; attribute argument(s), this is an
798     extension mechanism for users &amp; applications. For example:</p>
799     <pre class="literal-block">
800     .. container:: custom
801    
802     This paragraph might be rendered in a custom way.
803     </pre>
804     <p>Parsing the above results in the following pseudo-XML:</p>
805     <pre class="literal-block">
806     &lt;container classes=&quot;custom&quot;&gt;
807     &lt;paragraph&gt;
808     This paragraph might be rendered in a custom way.
809     </pre>
810     <p>The &quot;container&quot; directive is the equivalent of HTML's <tt class="docutils literal">&lt;div&gt;</tt>
811     element. It may be used to group a sequence of elements for user- or
812     application-specific purposes.</p>
813     </div>
814     </div>
815     <div class="section" id="tables">
816     <h1><a class="toc-backref" href="#id25">Tables</a></h1>
817     <p>Formal tables need more structure than the reStructuredText syntax
818     supplies. Tables may be given titles with the <a class="reference internal" href="#table">table</a> directive.
819     Sometimes reStructuredText tables are inconvenient to write, or table
820     data in a standard format is readily available. The <a class="reference internal" href="#csv-table">csv-table</a>
821     directive supports CSV data.</p>
822     <div class="section" id="table">
823     <h2><a class="toc-backref" href="#id26">Table</a></h2>
824     <table class="docutils field-list" frame="void" rules="none">
825     <col class="field-name" />
826     <col class="field-body" />
827     <tbody valign="top">
828     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;table&quot;</td>
829     </tr>
830     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">table</td>
831     </tr>
832     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">1, optional (table title).</td>
833     </tr>
834     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
835     </tr>
836     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">A normal reStructuredText table.</td>
837     </tr>
838     </tbody>
839     </table>
840     <p>(New in Docutils 0.3.1)</p>
841     <p>The &quot;table&quot; directive is used to create a titled table, to associate a
842     title with a table:</p>
843     <pre class="literal-block">
844     .. table:: Truth table for &quot;not&quot;
845    
846     ===== =====
847     A not A
848     ===== =====
849     False True
850     True False
851     ===== =====
852     </pre>
853     <p>The following option is recognized:</p>
854     <dl class="docutils">
855     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
856     <dd>Set a &quot;classes&quot; attribute value on the table element. See the
857     <a class="reference internal" href="#class">class</a> directive below.</dd>
858     </dl>
859     </div>
860     <div class="section" id="id1">
861     <span id="csv-table"></span><h2><a class="toc-backref" href="#id27">CSV Table</a></h2>
862     <table class="docutils field-list" frame="void" rules="none">
863     <col class="field-name" />
864     <col class="field-body" />
865     <tbody valign="top">
866     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;csv-table&quot;</td>
867     </tr>
868     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">table</td>
869     </tr>
870     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">1, optional (table title).</td>
871     </tr>
872     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
873     </tr>
874     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">A CSV (comma-separated values) table.</td>
875     </tr>
876     </tbody>
877     </table>
878     <div class="warning">
879     <p class="first admonition-title">Warning</p>
880     <p class="last">The &quot;csv-table&quot; directive's &quot;:file:&quot; and &quot;:url:&quot; options represent
881     a potential security holes. They can be disabled with the
882     &quot;<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>&quot; runtime setting.</p>
883     </div>
884     <p>(New in Docutils 0.3.4)</p>
885     <p>The &quot;csv-table&quot; directive is used to create a table from CSV
886     (comma-separated values) data. CSV is a common data format generated
887     by spreadsheet applications and commercial databases. The data may be
888     internal (an integral part of the document) or external (a separate
889     file).</p>
890     <p>Example:</p>
891     <pre class="literal-block">
892     .. csv-table:: Frozen Delights!
893     :header: &quot;Treat&quot;, &quot;Quantity&quot;, &quot;Description&quot;
894     :widths: 15, 10, 30
895    
896     &quot;Albatross&quot;, 2.99, &quot;On a stick!&quot;
897     &quot;Crunchy Frog&quot;, 1.49, &quot;If we took the bones out, it wouldn't be
898     crunchy, now would it?&quot;
899     &quot;Gannet Ripple&quot;, 1.99, &quot;On a stick!&quot;
900     </pre>
901     <p>Block markup and inline markup within cells is supported. Line ends
902     are recognized within cells.</p>
903     <p>Working limitations:</p>
904     <ul class="simple">
905     <li>Whitespace delimiters are supported only for external CSV files.</li>
906     <li>There is no support for checking that the number of columns in each
907     row is the same. However, this directive supports CSV generators
908     that do not insert &quot;empty&quot; entries at the end of short rows, by
909     automatically adding empty entries.<!-- Add "strict" option to verify input? -->
910     </li>
911     </ul>
912     <p>The following options are recognized:</p>
913     <dl class="docutils">
914     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
915     <dd>Set a &quot;classes&quot; attribute value on the table element. See the
916     <a class="reference internal" href="#class">class</a> directive below.</dd>
917     <dt><tt class="docutils literal">widths</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer [, integer...]</span></dt>
918     <dd>A comma- or space-separated list of relative column widths. The
919     default is equal-width columns (100%/#columns).</dd>
920     <dt><tt class="docutils literal"><span class="pre">header-rows</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
921     <dd>The number of rows of CSV data to use in the table header.
922     Defaults to 0.</dd>
923     <dt><tt class="docutils literal"><span class="pre">stub-columns</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
924     <dd>The number of table columns to use as stubs (row titles, on the
925     left). Defaults to 0.</dd>
926     <dt><tt class="docutils literal">header</tt> <span class="classifier-delimiter">:</span> <span class="classifier">CSV data</span></dt>
927     <dd>Supplemental data for the table header, added independently of and
928     before any <tt class="docutils literal"><span class="pre">header-rows</span></tt> from the main CSV data. Must use the
929     same CSV format as the main CSV data.</dd>
930     <dt><tt class="docutils literal">file</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (newlines removed)</span></dt>
931     <dd>The local filesystem path to a CSV data file.</dd>
932     <dt><tt class="docutils literal">url</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (whitespace removed)</span></dt>
933     <dd>An Internet URL reference to a CSV data file.</dd>
934     <dt><tt class="docutils literal">encoding</tt> <span class="classifier-delimiter">:</span> <span class="classifier">name of text encoding</span></dt>
935     <dd>The text encoding of the external CSV data (file or URL).
936     Defaults to the document's encoding (if specified).</dd>
937     <dt><tt class="docutils literal">delim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">char | &quot;tab&quot; | &quot;space&quot;</span></dt>
938     <dd>A one-character string used to separate fields. Defaults to <tt class="docutils literal">,</tt>
939     (comma). May be specified as a Unicode code point; see the
940     <a class="reference internal" href="#unicode">unicode</a> directive for syntax details.</dd>
941     <dt><tt class="docutils literal">quote</tt> <span class="classifier-delimiter">:</span> <span class="classifier">char</span></dt>
942     <dd>A one-character string used to quote elements containing the
943     delimiter or which start with the quote character. Defaults to
944     <tt class="docutils literal">&quot;</tt> (quote). May be specified as a Unicode code point; see the
945     <a class="reference internal" href="#unicode">unicode</a> directive for syntax details.</dd>
946     <dt><tt class="docutils literal">keepspace</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
947     <dd>Treat whitespace immediately following the delimiter as
948     significant. The default is to ignore such whitespace.</dd>
949     <dt><tt class="docutils literal">escape</tt> <span class="classifier-delimiter">:</span> <span class="classifier">char</span></dt>
950     <dd>A one-character string used to escape the delimiter or quote
951     characters. May be specified as a Unicode code point; see the
952     <a class="reference internal" href="#unicode">unicode</a> directive for syntax details. Used when the delimiter is
953     used in an unquoted field, or when quote characters are used
954     within a field. The default is to double-up the character,
955     e.g. &quot;He said, &quot;&quot;Hi!&quot;&quot;&quot;<!-- Add another possible value, "double", to explicitly indicate
956     the default case? -->
957     </dd>
958     </dl>
959     </div>
960     <div class="section" id="list-table">
961     <h2><a class="toc-backref" href="#id28">List Table</a></h2>
962     <table class="docutils field-list" frame="void" rules="none">
963     <col class="field-name" />
964     <col class="field-body" />
965     <tbody valign="top">
966     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;list-table&quot;</td>
967     </tr>
968     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">table</td>
969     </tr>
970     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">1, optional (table title).</td>
971     </tr>
972     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
973     </tr>
974     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">A uniform two-level bullet list.</td>
975     </tr>
976     </tbody>
977     </table>
978     <p>(New in Docutils 0.3.8. This is an initial implementation; <a class="reference external" href="../../dev/rst/alternatives.html#list-driven-tables">further
979     ideas</a> may be implemented in the future.)</p>
980     <p>The &quot;list-table&quot; directive is used to create a table from data in a
981     uniform two-level bullet list. &quot;Uniform&quot; means that each sublist
982     (second-level list) must contain the same number of list items.</p>
983     <p>Example:</p>
984     <pre class="literal-block">
985     .. list-table:: Frozen Delights!
986     :widths: 15 10 30
987     :header-rows: 1
988    
989     * - Treat
990     - Quantity
991     - Description
992     * - Albatross
993     - 2.99
994     - On a stick!
995     * - Crunchy Frog
996     - 1.49
997     - If we took the bones out, it wouldn't be
998     crunchy, now would it?
999     * - Gannet Ripple
1000     - 1.99
1001     - On a stick!
1002     </pre>
1003     <p>The following options are recognized:</p>
1004     <dl class="docutils">
1005     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
1006     <dd>Set a &quot;classes&quot; attribute value on the table element. See the
1007     <a class="reference internal" href="#class">class</a> directive below.</dd>
1008     <dt><tt class="docutils literal">widths</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer [integer...]</span></dt>
1009     <dd>A comma- or space-separated list of relative column widths. The
1010     default is equal-width columns (100%/#columns).</dd>
1011     <dt><tt class="docutils literal"><span class="pre">header-rows</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1012     <dd>The number of rows of list data to use in the table header.
1013     Defaults to 0.</dd>
1014     <dt><tt class="docutils literal"><span class="pre">stub-columns</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1015     <dd>The number of table columns to use as stubs (row titles, on the
1016     left). Defaults to 0.</dd>
1017     </dl>
1018     </div>
1019     </div>
1020     <div class="section" id="document-parts">
1021     <h1><a class="toc-backref" href="#id29">Document Parts</a></h1>
1022     <div class="section" id="table-of-contents">
1023     <span id="id3"></span><h2><a class="toc-backref" href="#id30">Table of Contents</a></h2>
1024     <table class="docutils field-list" frame="void" rules="none">
1025     <col class="field-name" />
1026     <col class="field-body" />
1027     <tbody valign="top">
1028     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;contents&quot;</td>
1029     </tr>
1030     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">pending, topic</td>
1031     </tr>
1032     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, optional: title.</td>
1033     </tr>
1034     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
1035     </tr>
1036     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1037     </tr>
1038     </tbody>
1039     </table>
1040     <p>The &quot;contents&quot; directive generates a table of contents (TOC) in a
1041     <a class="reference internal" href="#topic">topic</a>. Topics, and therefore tables of contents, may occur anywhere
1042     a section or transition may occur. Body elements and topics may not
1043     contain tables of contents.</p>
1044     <p>Here's the directive in its simplest form:</p>
1045     <pre class="literal-block">
1046     .. contents::
1047     </pre>
1048     <p>Language-dependent boilerplate text will be used for the title. The
1049     English default title text is &quot;Contents&quot;.</p>
1050     <p>An explicit title may be specified:</p>
1051     <pre class="literal-block">
1052     .. contents:: Table of Contents
1053     </pre>
1054     <p>The title may span lines, although it is not recommended:</p>
1055     <pre class="literal-block">
1056     .. contents:: Here's a very long Table of
1057     Contents title
1058     </pre>
1059     <p>Options may be specified for the directive, using a field list:</p>
1060     <pre class="literal-block">
1061     .. contents:: Table of Contents
1062     :depth: 2
1063     </pre>
1064     <p>If the default title is to be used, the options field list may begin
1065     on the same line as the directive marker:</p>
1066     <pre class="literal-block">
1067     .. contents:: :depth: 2
1068     </pre>
1069     <p>The following options are recognized:</p>
1070     <dl class="docutils">
1071     <dt><tt class="docutils literal">depth</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1072     <dd>The number of section levels that are collected in the table of
1073     contents. The default is unlimited depth.</dd>
1074     <dt><tt class="docutils literal">local</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag (empty)</span></dt>
1075     <dd>Generate a local table of contents. Entries will only include
1076     subsections of the section in which the directive is given. If no
1077     explicit title is given, the table of contents will not be titled.</dd>
1078     <dt><tt class="docutils literal">backlinks</tt> <span class="classifier-delimiter">:</span> <span class="classifier">&quot;entry&quot; or &quot;top&quot; or &quot;none&quot;</span></dt>
1079     <dd>Generate links from section headers back to the table of contents
1080     entries, the table of contents itself, or generate no backlinks.</dd>
1081     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
1082     <dd>Set a &quot;classes&quot; attribute value on the topic element. See the
1083     <a class="reference internal" href="#class">class</a> directive below.</dd>
1084     </dl>
1085     </div>
1086     <div class="section" id="automatic-section-numbering">
1087     <span id="section-autonumbering"></span><span id="sectnum"></span><h2><a class="toc-backref" href="#id31">Automatic Section Numbering</a></h2>
1088     <table class="docutils field-list" frame="void" rules="none">
1089     <col class="field-name" />
1090     <col class="field-body" />
1091     <tbody valign="top">
1092     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;sectnum&quot; or &quot;section-autonumbering&quot; (synonyms)</td>
1093     </tr>
1094     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">pending, generated</td>
1095     </tr>
1096     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
1097     </tr>
1098     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
1099     </tr>
1100     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1101     </tr>
1102     </tbody>
1103     </table>
1104     <p>The &quot;sectnum&quot; (or &quot;section-autonumbering&quot;) directive automatically numbers
1105     sections and subsections in a document (if not disabled by the
1106     <tt class="docutils literal"><span class="pre">--no-section-numbering</span></tt> command line option or the <a class="reference external" href="../../user/config.html#sectnum-xform">sectnum_xform</a>
1107     configuration setting).</p>
1108     <p>Section numbers are of the &quot;multiple enumeration&quot; form, where each
1109     level has a number, separated by periods. For example, the title of section
1110     1, subsection 2, subsubsection 3 would have &quot;1.2.3&quot; prefixed.</p>
1111     <p>The &quot;sectnum&quot; directive does its work in two passes: the initial parse
1112     and a transform. During the initial parse, a &quot;pending&quot; element is
1113     generated which acts as a placeholder, storing any options internally.
1114     At a later stage in the processing, the &quot;pending&quot; element triggers a
1115     transform, which adds section numbers to titles. Section numbers are
1116     enclosed in a &quot;generated&quot; element, and titles have their &quot;auto&quot;
1117     attribute set to &quot;1&quot;.</p>
1118     <p>The following options are recognized:</p>
1119     <dl class="docutils">
1120     <dt><tt class="docutils literal">depth</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1121     <dd>The number of section levels that are numbered by this directive.
1122     The default is unlimited depth.</dd>
1123     <dt><tt class="docutils literal">prefix</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
1124     <dd>An arbitrary string that is prefixed to the automatically
1125     generated section numbers. It may be something like &quot;3.2.&quot;, which
1126     will produce &quot;3.2.1&quot;, &quot;3.2.2&quot;, &quot;3.2.2.1&quot;, and so on. Note that
1127     any separating punctuation (in the example, a period, &quot;.&quot;) must be
1128     explicitly provided. The default is no prefix.</dd>
1129     <dt><tt class="docutils literal">suffix</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
1130     <dd>An arbitrary string that is appended to the automatically
1131     generated section numbers. The default is no suffix.</dd>
1132     <dt><tt class="docutils literal">start</tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1133     <dd>The value that will be used for the first section number.
1134     Combined with <tt class="docutils literal">prefix</tt>, this may be used to force the right
1135     numbering for a document split over several source files. The
1136     default is 1.</dd>
1137     </dl>
1138     </div>
1139     <div class="section" id="document-header-footer">
1140     <span id="footer"></span><span id="header"></span><h2><a class="toc-backref" href="#id32">Document Header &amp; Footer</a></h2>
1141     <table class="docutils field-list" frame="void" rules="none">
1142     <col class="field-name" />
1143     <col class="field-body" />
1144     <tbody valign="top">
1145     <tr class="field"><th class="field-name">Directive Types:</th><td class="field-body">&quot;header&quot; and &quot;footer&quot;</td>
1146     </tr>
1147     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">decoration, header, footer</td>
1148     </tr>
1149     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
1150     </tr>
1151     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1152     </tr>
1153     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as body elements.</td>
1154     </tr>
1155     </tbody>
1156     </table>
1157     <p>(New in Docutils 0.3.8)</p>
1158     <p>The &quot;header&quot; and &quot;footer&quot; directives create document decorations,
1159     useful for page navigation, notes, time/datestamp, etc. For example:</p>
1160     <pre class="literal-block">
1161     .. header:: This space for rent.
1162     </pre>
1163     <p>This will add a paragraph to the document header, which will appear at
1164     the top of the generated web page or at the top of every printed page.</p>
1165     <p>These directives may be used multiple times, cumulatively. There is
1166     currently support for only one header and footer.</p>
1167     <div class="note">
1168     <p class="first admonition-title">Note</p>
1169     <p>While it is possible to use the &quot;header&quot; and &quot;footer&quot; directives to
1170     create navigational elements for web pages, you should be aware
1171     that Docutils is meant to be used for <em>document</em> processing, and
1172     that a navigation bar is not typically part of a document.</p>
1173     <p class="last">Thus, you may soon find Docutils' abilities to be insufficient for
1174     these purposes. At that time, you should consider using a
1175     templating system (like <a class="reference external" href="http://ht2html.sourceforge.net/">ht2html</a>) rather than the &quot;header&quot; and
1176     &quot;footer&quot; directives.</p>
1177     </div>
1178     <p>In addition to the use of these directives to populate header and
1179     footer content, content may also be added automatically by the
1180     processing system. For example, if certain runtime settings are
1181     enabled, the document footer is populated with processing information
1182     such as a datestamp, a link to <a class="reference external" href="http://docutils.sourceforge.net">the Docutils website</a>, etc.</p>
1183     </div>
1184     </div>
1185     <div class="section" id="references">
1186     <h1><a class="toc-backref" href="#id33">References</a></h1>
1187     <div class="section" id="target-footnotes">
1188     <span id="target-notes"></span><h2><a class="toc-backref" href="#id34">Target Footnotes</a></h2>
1189     <table class="docutils field-list" frame="void" rules="none">
1190     <col class="field-name" />
1191     <col class="field-body" />
1192     <tbody valign="top">
1193     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;target-notes&quot;</td>
1194     </tr>
1195     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">pending, footnote, footnote_reference</td>
1196     </tr>
1197     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
1198     </tr>
1199     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
1200     </tr>
1201     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1202     </tr>
1203     </tbody>
1204     </table>
1205     <p>The &quot;target-notes&quot; directive creates a footnote for each external
1206     target in the text, and corresponding footnote references after each
1207     reference. For every explicit target (of the form, <tt class="docutils literal">.. _target name:
1208     URL</tt>) in the text, a footnote will be generated containing the
1209     visible URL as content.</p>
1210     <p>The following option is recognized:</p>
1211     <dl class="docutils">
1212     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
1213     <dd>Set a &quot;classes&quot; attribute value on all footnote_reference elements.
1214     See the <a class="reference internal" href="#class">class</a> directive below.</dd>
1215     </dl>
1216     </div>
1217     <div class="section" id="footnotes">
1218     <h2><a class="toc-backref" href="#id35">Footnotes</a></h2>
1219     <p><strong>NOT IMPLEMENTED YET</strong></p>
1220     <table class="docutils field-list" frame="void" rules="none">
1221     <col class="field-name" />
1222     <col class="field-body" />
1223     <tbody valign="top">
1224     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;footnotes&quot;</td>
1225     </tr>
1226     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">pending, topic</td>
1227     </tr>
1228     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None?</td>
1229     </tr>
1230     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible?</td>
1231     </tr>
1232     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1233     </tr>
1234     </tbody>
1235     </table>
1236     <p>&#64;&#64;&#64;</p>
1237     </div>
1238     <div class="section" id="citations">
1239     <h2><a class="toc-backref" href="#id36">Citations</a></h2>
1240     <p><strong>NOT IMPLEMENTED YET</strong></p>
1241     <table class="docutils field-list" frame="void" rules="none">
1242     <col class="field-name" />
1243     <col class="field-body" />
1244     <tbody valign="top">
1245     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;citations&quot;</td>
1246     </tr>
1247     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">pending, topic</td>
1248     </tr>
1249     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None?</td>
1250     </tr>
1251     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible?</td>
1252     </tr>
1253     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1254     </tr>
1255     </tbody>
1256     </table>
1257     <p>&#64;&#64;&#64;</p>
1258     </div>
1259     </div>
1260     <div class="section" id="html-specific">
1261     <h1><a class="toc-backref" href="#id37">HTML-Specific</a></h1>
1262     <div class="section" id="meta">
1263     <h2><a class="toc-backref" href="#id38">Meta</a></h2>
1264     <table class="docutils field-list" frame="void" rules="none">
1265     <col class="field-name" />
1266     <col class="field-body" />
1267     <tbody valign="top">
1268     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;meta&quot;</td>
1269     </tr>
1270     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">meta (non-standard)</td>
1271     </tr>
1272     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
1273     </tr>
1274     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1275     </tr>
1276     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Must contain a flat field list.</td>
1277     </tr>
1278     </tbody>
1279     </table>
1280     <p>The &quot;meta&quot; directive is used to specify HTML metadata stored in HTML
1281     META tags. &quot;Metadata&quot; is data about data, in this case data about web
1282     pages. Metadata is used to describe and classify web pages in the
1283     World Wide Web, in a form that is easy for search engines to extract
1284     and collate.</p>
1285     <p>Within the directive block, a flat field list provides the syntax for
1286     metadata. The field name becomes the contents of the &quot;name&quot; attribute
1287     of the META tag, and the field body (interpreted as a single string
1288     without inline markup) becomes the contents of the &quot;content&quot;
1289     attribute. For example:</p>
1290     <pre class="literal-block">
1291     .. meta::
1292     :description: The reStructuredText plaintext markup language
1293     :keywords: plaintext, markup language
1294     </pre>
1295     <p>This would be converted to the following HTML:</p>
1296     <pre class="literal-block">
1297     &lt;meta name=&quot;description&quot;
1298     content=&quot;The reStructuredText plaintext markup language&quot;&gt;
1299     &lt;meta name=&quot;keywords&quot; content=&quot;plaintext, markup language&quot;&gt;
1300     </pre>
1301     <p>Support for other META attributes (&quot;http-equiv&quot;, &quot;scheme&quot;, &quot;lang&quot;,
1302     &quot;dir&quot;) are provided through field arguments, which must be of the form
1303     &quot;attr=value&quot;:</p>
1304     <pre class="literal-block">
1305     .. meta::
1306     :description lang=en: An amusing story
1307     :description lang=fr: Une histoire amusante
1308     </pre>
1309     <p>And their HTML equivalents:</p>
1310     <pre class="literal-block">
1311     &lt;meta name=&quot;description&quot; lang=&quot;en&quot; content=&quot;An amusing story&quot;&gt;
1312     &lt;meta name=&quot;description&quot; lang=&quot;fr&quot; content=&quot;Une histoire amusante&quot;&gt;
1313     </pre>
1314     <p>Some META tags use an &quot;http-equiv&quot; attribute instead of the &quot;name&quot;
1315     attribute. To specify &quot;http-equiv&quot; META tags, simply omit the name:</p>
1316     <pre class="literal-block">
1317     .. meta::
1318     :http-equiv=Content-Type: text/html; charset=ISO-8859-1
1319     </pre>
1320     <p>HTML equivalent:</p>
1321     <pre class="literal-block">
1322     &lt;meta http-equiv=&quot;Content-Type&quot;
1323     content=&quot;text/html; charset=ISO-8859-1&quot;&gt;
1324     </pre>
1325     </div>
1326     <div class="section" id="imagemap">
1327     <h2><a class="toc-backref" href="#id39">Imagemap</a></h2>
1328     <p><strong>NOT IMPLEMENTED YET</strong></p>
1329     <p>Non-standard element: imagemap.</p>
1330     </div>
1331     </div>
1332     <div class="section" id="directives-for-substitution-definitions">
1333     <h1><a class="toc-backref" href="#id40">Directives for Substitution Definitions</a></h1>
1334     <p>The directives in this section may only be used in substitution
1335     definitions. They may not be used directly, in standalone context.
1336     The <a class="reference internal" href="#image">image</a> directive may be used both in substitution definitions
1337     and in the standalone context.</p>
1338     <div class="section" id="replacement-text">
1339     <span id="replace"></span><h2><a class="toc-backref" href="#id41">Replacement Text</a></h2>
1340     <table class="docutils field-list" frame="void" rules="none">
1341     <col class="field-name" />
1342     <col class="field-body" />
1343     <tbody valign="top">
1344     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;replace&quot;</td>
1345     </tr>
1346     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">Text &amp; inline elements</td>
1347     </tr>
1348     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
1349     </tr>
1350     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1351     </tr>
1352     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">A single paragraph; may contain inline markup.</td>
1353     </tr>
1354     </tbody>
1355     </table>
1356     <p>The &quot;replace&quot; directive is used to indicate replacement text for a
1357     substitution reference. It may be used within substitution
1358     definitions only. For example, this directive can be used to expand
1359     abbreviations:</p>
1360     <pre class="literal-block">
1361     .. |reST| replace:: reStructuredText
1362    
1363     Yes, |reST| is a long word, so I can't blame anyone for wanting to
1364     abbreviate it.
1365     </pre>
1366     <p>As reStructuredText doesn't support nested inline markup, the only way
1367     to create a reference with styled text is to use substitutions with
1368     the &quot;replace&quot; directive:</p>
1369     <pre class="literal-block">
1370     I recommend you try |Python|_.
1371    
1372     .. |Python| replace:: Python, *the* best language around
1373     .. _Python: http://www.python.org/
1374     </pre>
1375     </div>
1376     <div class="section" id="unicode-character-codes">
1377     <span id="unicode"></span><h2><a class="toc-backref" href="#id42">Unicode Character Codes</a></h2>
1378     <table class="docutils field-list" frame="void" rules="none">
1379     <col class="field-name" />
1380     <col class="field-body" />
1381     <tbody valign="top">
1382     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;unicode&quot;</td>
1383     </tr>
1384     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">Text</td>
1385     </tr>
1386     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One or more, required (Unicode character codes,
1387     optional text, and comments).</td>
1388     </tr>
1389     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
1390     </tr>
1391     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1392     </tr>
1393     </tbody>
1394     </table>
1395     <p>The &quot;unicode&quot; directive converts Unicode character codes (numerical
1396     values) to characters, and may be used in substitution definitions
1397     only.</p>
1398     <p>The arguments, separated by spaces, can be:</p>
1399     <ul class="simple">
1400     <li><strong>character codes</strong> as<ul>
1401     <li>decimal numbers or</li>
1402     <li>hexadecimal numbers, prefixed by <tt class="docutils literal">0x</tt>, <tt class="docutils literal">x</tt>, <tt class="docutils literal">\x</tt>, <tt class="docutils literal">U+</tt>,
1403     <tt class="docutils literal">u</tt>, or <tt class="docutils literal">\u</tt> or as XML-style hexadecimal character entities,
1404     e.g. <tt class="docutils literal">&amp;#x1a2b;</tt></li>
1405     </ul>
1406     </li>
1407     <li><strong>text</strong>, which is used as-is.</li>
1408     </ul>
1409     <p>Text following &quot; .. &quot; is a comment and is ignored. The spaces between
1410     the arguments are ignored and thus do not appear in the output.
1411     Hexadecimal codes are case-insensitive.</p>
1412     <p>For example, the following text:</p>
1413     <pre class="literal-block">
1414     Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1415     all rights reserved.
1416    
1417     .. |copy| unicode:: 0xA9 .. copyright sign
1418     .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1419     .. with trademark sign
1420     .. |---| unicode:: U+02014 .. em dash
1421     :trim:
1422     </pre>
1423     <p>results in:</p>
1424     <blockquote>
1425     Copyright © 2003, BogusMegaCorp™—all rights reserved.</blockquote>
1426     <p>The following options are recognized:</p>
1427     <dl class="docutils">
1428     <dt><tt class="docutils literal">ltrim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
1429     <dd>Whitespace to the left of the substitution reference is removed.</dd>
1430     <dt><tt class="docutils literal">rtrim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
1431     <dd>Whitespace to the right of the substitution reference is removed.</dd>
1432     <dt><tt class="docutils literal">trim</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag</span></dt>
1433     <dd>Equivalent to <tt class="docutils literal">ltrim</tt> plus <tt class="docutils literal">rtrim</tt>; whitespace on both sides
1434     of the substitution reference is removed.</dd>
1435     </dl>
1436     </div>
1437     <div class="section" id="date">
1438     <h2><a class="toc-backref" href="#id43">Date</a></h2>
1439     <table class="docutils field-list" frame="void" rules="none">
1440     <col class="field-name" />
1441     <col class="field-body" />
1442     <tbody valign="top">
1443     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;date&quot;</td>
1444     </tr>
1445     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">Text</td>
1446     </tr>
1447     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, optional (date format).</td>
1448     </tr>
1449     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1450     </tr>
1451     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1452     </tr>
1453     </tbody>
1454     </table>
1455     <p>The &quot;date&quot; directive generates the current local date and inserts it
1456     into the document as text. This directive may be used in substitution
1457     definitions only.</p>
1458     <p>The optional directive content is interpreted as the desired date
1459     format, using the same codes as Python's time.strftime function. The
1460     default format is &quot;%Y-%m-%d&quot; (ISO 8601 date), but time fields can also
1461     be used. Examples:</p>
1462     <pre class="literal-block">
1463     .. |date| date::
1464     .. |time| date:: %H:%M
1465    
1466     Today's date is |date|.
1467    
1468     This document was generated on |date| at |time|.
1469     </pre>
1470     </div>
1471     </div>
1472     <div class="section" id="miscellaneous">
1473     <h1><a class="toc-backref" href="#id44">Miscellaneous</a></h1>
1474     <div class="section" id="including-an-external-document-fragment">
1475     <span id="include"></span><h2><a class="toc-backref" href="#id45">Including an External Document Fragment</a></h2>
1476     <table class="docutils field-list" frame="void" rules="none">
1477     <col class="field-name" />
1478     <col class="field-body" />
1479     <tbody valign="top">
1480     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;include&quot;</td>
1481     </tr>
1482     <tr class="field"><th class="field-name">Doctree Elements:</th><td class="field-body">depend on data being included</td>
1483     </tr>
1484     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, required (path to the file to include).</td>
1485     </tr>
1486     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
1487     </tr>
1488     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1489     </tr>
1490     </tbody>
1491     </table>
1492     <div class="warning">
1493     <p class="first admonition-title">Warning</p>
1494     <p class="last">The &quot;include&quot; directive represents a potential security hole. It
1495     can be disabled with the &quot;<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>&quot; runtime setting.</p>
1496     </div>
1497     <p>The &quot;include&quot; directive reads a reStructuredText-formatted text file
1498     and parses it in the current document's context at the point of the
1499     directive. The directive argument is the path to the file to be
1500     included, relative to the document containing the directive. For
1501     example:</p>
1502     <pre class="literal-block">
1503     This first example will be parsed at the document level, and can
1504     thus contain any construct, including section headers.
1505    
1506     .. include:: inclusion.txt
1507    
1508     Back in the main document.
1509    
1510     This second example will be parsed in a block quote context.
1511     Therefore it may only contain body elements. It may not
1512     contain section headers.
1513    
1514     .. include:: inclusion.txt
1515     </pre>
1516     <p>If an included document fragment contains section structure, the title
1517     adornments must match those of the master document.</p>
1518     <p>Standard data files intended for inclusion in reStructuredText
1519     documents are distributed with the Docutils source code, located in
1520     the &quot;docutils&quot; package in the <tt class="docutils literal">docutils/parsers/rst/include</tt>
1521     directory. To access these files, use the special syntax for standard
1522     &quot;include&quot; data files, angle brackets around the file name:</p>
1523     <pre class="literal-block">
1524     .. include:: &lt;isonum.txt&gt;
1525     </pre>
1526     <p>The current set of standard &quot;include&quot; data files consists of sets of
1527     substitution definitions. See <a class="reference external" href="substitutions.html">reStructuredText Standard Substitution
1528     Definition Sets</a> for details of the available standard data files.</p>
1529     <p>The following options are recognized:</p>
1530     <dl class="docutils">
1531     <dt><tt class="docutils literal"><span class="pre">start-line</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1532     <dd>Only the content starting from this line will be included.
1533     (As usual in Python, the first line has index 0 and negative values
1534     count from the end.)</dd>
1535     <dt><tt class="docutils literal"><span class="pre">end-line</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1536     <dd>Only the content up to (but excluding) this line will be included.</dd>
1537     <dt><tt class="docutils literal"><span class="pre">start-after</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">text to find in the external data file</span></dt>
1538     <dd>Only the content after the first occurrence of the specified text
1539     will be included.</dd>
1540     <dt><tt class="docutils literal"><span class="pre">end-before</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">text to find in the external data file</span></dt>
1541     <dd>Only the content before the first occurrence of the specified text
1542     (but after any <tt class="docutils literal">after</tt> text) will be included.</dd>
1543     <dt><tt class="docutils literal">literal</tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag (empty)</span></dt>
1544     <dd>The entire included text is inserted into the document as a single
1545     literal block (useful for program listings).</dd>
1546     <dt><tt class="docutils literal">encoding</tt> <span class="classifier-delimiter">:</span> <span class="classifier">name of text encoding</span></dt>
1547     <dd>The text encoding of the external data file. Defaults to the
1548     document's <a class="reference external" href="../../user/config.html#input-encoding">input_encoding</a>.</dd>
1549     <dt><tt class="docutils literal"><span class="pre">tab-width</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
1550     <dd>Number of spaces for hard tab expansion.
1551     A negative value prevents expansion of hard tabs. Defaults to the
1552     <a class="reference external" href="../../user/config.html#tab-width">tab_width</a> configuration setting.</dd>
1553     </dl>
1554     <p>Combining <tt class="docutils literal"><span class="pre">start/end-line</span></tt> and <tt class="docutils literal"><span class="pre">start-after/end-before</span></tt> is possible. The
1555     text markers will be searched in the specified lines (further limiting the
1556     included content).</p>
1557     </div>
1558     <div class="section" id="raw-data-pass-through">
1559     <span id="raw"></span><h2><a class="toc-backref" href="#id46">Raw Data Pass-Through</a></h2>
1560     <table class="docutils field-list" frame="void" rules="none">
1561     <col class="field-name" />
1562     <col class="field-body" />
1563     <tbody valign="top">
1564     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;raw&quot;</td>
1565     </tr>
1566     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">raw</td>
1567     </tr>
1568     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One or more, required (output format types).</td>
1569     </tr>
1570     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible.</td>
1571     </tr>
1572     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Stored verbatim, uninterpreted. None (empty) if a
1573     &quot;file&quot; or &quot;url&quot; option given.</td>
1574     </tr>
1575     </tbody>
1576     </table>
1577     <div class="warning">
1578     <p class="first admonition-title">Warning</p>
1579     <p class="last">The &quot;raw&quot; directive represents a potential security hole. It can
1580     be disabled with the &quot;<a class="reference external" href="../../user/config.html#raw-enabled">raw_enabled</a>&quot; or &quot;<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>&quot;
1581     runtime settings.</p>
1582     </div>
1583     <div class="caution">
1584     <p class="first admonition-title">Caution!</p>
1585     <p>The &quot;raw&quot; directive is a stop-gap measure allowing the author to
1586     bypass reStructuredText's markup. It is a &quot;power-user&quot; feature
1587     that should not be overused or abused. The use of &quot;raw&quot; ties
1588     documents to specific output formats and makes them less portable.</p>
1589     <p class="last">If you often need to use the &quot;raw&quot; directive or a &quot;raw&quot;-derived
1590     interpreted text role, that is a sign either of overuse/abuse or
1591     that functionality may be missing from reStructuredText. Please
1592     describe your situation in a message to the <a class="reference external" href="../../user/mailing-lists.html#docutils-users">Docutils-users</a> mailing
1593     list.</p>
1594     </div>
1595     <p>The &quot;raw&quot; directive indicates non-reStructuredText data that is to be
1596     passed untouched to the Writer. The names of the output formats are
1597     given in the directive arguments. The interpretation of the raw data
1598     is up to the Writer. A Writer may ignore any raw output not matching
1599     its format.</p>
1600     <p>For example, the following input would be passed untouched by an HTML
1601     Writer:</p>
1602     <pre class="literal-block">
1603     .. raw:: html
1604    
1605     &lt;hr width=50 size=10&gt;
1606     </pre>
1607     <p>A LaTeX Writer could insert the following raw content into its
1608     output stream:</p>
1609     <pre class="literal-block">
1610     .. raw:: latex
1611    
1612     \setlength{\parindent}{0pt}
1613     </pre>
1614     <p>Raw data can also be read from an external file, specified in a
1615     directive option. In this case, the content block must be empty. For
1616     example:</p>
1617     <pre class="literal-block">
1618     .. raw:: html
1619     :file: inclusion.html
1620     </pre>
1621     <p>The following options are recognized:</p>
1622     <dl class="docutils">
1623     <dt><tt class="docutils literal">file</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (newlines removed)</span></dt>
1624     <dd>The local filesystem path of a raw data file to be included.</dd>
1625     <dt><tt class="docutils literal">url</tt> <span class="classifier-delimiter">:</span> <span class="classifier">string (whitespace removed)</span></dt>
1626     <dd>An Internet URL reference to a raw data file to be included.</dd>
1627     <dt><tt class="docutils literal">encoding</tt> <span class="classifier-delimiter">:</span> <span class="classifier">name of text encoding</span></dt>
1628     <dd>The text encoding of the external raw data (file or URL).
1629     Defaults to the document's encoding (if specified).</dd>
1630     </dl>
1631     </div>
1632     <div class="section" id="class">
1633     <span id="classes"></span><h2><a class="toc-backref" href="#id47">Class</a></h2>
1634     <table class="docutils field-list" frame="void" rules="none">
1635     <col class="field-name" />
1636     <col class="field-body" />
1637     <tbody valign="top">
1638     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;class&quot;</td>
1639     </tr>
1640     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">pending</td>
1641     </tr>
1642     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One or more, required (class names / attribute
1643     values).</td>
1644     </tr>
1645     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1646     </tr>
1647     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Optional. If present, it is interpreted as body
1648     elements.</td>
1649     </tr>
1650     </tbody>
1651     </table>
1652     <p>The &quot;class&quot; directive sets the &quot;classes&quot; attribute value on its content
1653     or on the first immediately following non-comment element <a class="footnote-reference" href="#id7" id="id5">[1]</a>. For
1654     details of the &quot;classes&quot; attribute, see <a class="reference external" href="../doctree.html#classes">its entry</a> in <a class="reference external" href="../doctree.html">The Docutils
1655     Document Tree</a>.</p>
1656     <p>The directive argument consists of one or more space-separated class
1657     names. The names are transformed to conform to the regular expression
1658     <tt class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></tt> by converting</p>
1659     <ul class="simple">
1660     <li>alphabetic characters to lowercase,</li>
1661     <li>accented characters to the base character,</li>
1662     <li>non-alphanumeric characters to hyphens,</li>
1663     <li>consecutive hyphens into one hyphen.</li>
1664     </ul>
1665     <p>For example &quot;Rot-Gelb.Blau Grün:+2008&quot; becomes &quot;rot-gelb-blau grun-2008&quot;.
1666     (For the <a class="reference internal" href="#rationale">rationale</a>, see below.)</p>
1667     <p>Examples:</p>
1668     <pre class="literal-block">
1669     .. class:: special
1670    
1671     This is a &quot;special&quot; paragraph.
1672    
1673     .. class:: exceptional remarkable
1674    
1675     An Exceptional Section
1676     ======================
1677    
1678     This is an ordinary paragraph.
1679    
1680     .. class:: multiple
1681    
1682     First paragraph.
1683    
1684     Second paragraph.
1685     </pre>
1686     <p>The text above is parsed and transformed into this doctree fragment:</p>
1687     <pre class="literal-block">
1688     &lt;paragraph classes=&quot;special&quot;&gt;
1689     This is a &quot;special&quot; paragraph.
1690     &lt;section classes=&quot;exceptional remarkable&quot;&gt;
1691     &lt;title&gt;
1692     An Exceptional Section
1693     &lt;paragraph&gt;
1694     This is an ordinary paragraph.
1695     &lt;paragraph classes=&quot;multiple&quot;&gt;
1696     First paragraph.
1697     &lt;paragraph classes=&quot;multiple&quot;&gt;
1698     Second paragraph.
1699     </pre>
1700     <table class="docutils footnote" frame="void" id="id7" rules="none">
1701     <colgroup><col class="label" /><col /></colgroup>
1702     <tbody valign="top">
1703     <tr><td class="label"><a class="fn-backref" href="#id5">[1]</a></td><td><p class="first">To set a &quot;classes&quot; attribute value on a block quote, the
1704     &quot;class&quot; directive must be followed by an empty comment:</p>
1705     <pre class="literal-block">
1706     .. class:: highlights
1707     ..
1708    
1709     Block quote text.
1710     </pre>
1711     <p class="last">An empty comment is required to terminate the directive to allow
1712     the indented text to be parsed as a block quote. Without the empty
1713     comment, the indented text would be interpreted as the &quot;class&quot;
1714     directive's content, and the classes would be applied to each
1715     element (paragraph, in this case) individually, instead of to the
1716     block quote as a whole.</p>
1717     </td></tr>
1718     </tbody>
1719     </table>
1720     <div class="topic" id="rationale">
1721     <p class="topic-title first">Rationale for &quot;classes&quot; Attribute Value Conversion</p>
1722     <p>Docutils identifiers are converted to conform to the regular
1723     expression <tt class="docutils literal"><span class="pre">[a-z](-?[a-z0-9]+)*</span></tt>. For HTML + CSS compatibility,
1724     identifiers (the &quot;classes&quot; and &quot;id&quot; attributes) should have no
1725     underscores, colons, or periods. Hyphens may be used.</p>
1726     <ul>
1727     <li><p class="first">The <a class="reference external" href="http://www.w3.org/TR/html401/">HTML 4.01 spec</a> defines identifiers based on SGML tokens:</p>
1728     <blockquote>
1729     <p>ID and NAME tokens must begin with a letter ([A-Za-z]) and
1730     may be followed by any number of letters, digits ([0-9]),
1731     hyphens (&quot;-&quot;), underscores (&quot;_&quot;), colons (&quot;:&quot;), and periods
1732     (&quot;.&quot;).</p>
1733     </blockquote>
1734     </li>
1735     <li><p class="first">The <a class="reference external" href="http://www.w3.org/TR/REC-CSS1">CSS1 spec</a> defines identifiers based on the &quot;name&quot; token
1736     (&quot;flex&quot; tokenizer notation below; &quot;latin1&quot; and &quot;escape&quot; 8-bit
1737     characters have been replaced with XML entities):</p>
1738     <pre class="literal-block">
1739     unicode \\[0-9a-f]{1,4}
1740     latin1 [&amp;iexcl;-&amp;yuml;]
1741     escape {unicode}|\\[ -~&amp;iexcl;-&amp;yuml;]
1742     nmchar [-A-Za-z0-9]|{latin1}|{escape}
1743     name {nmchar}+
1744     </pre>
1745     </li>
1746     </ul>
1747     <p>The CSS rule does not include underscores (&quot;_&quot;), colons (&quot;:&quot;), or
1748     periods (&quot;.&quot;), therefore &quot;classes&quot; and &quot;id&quot; attributes should not
1749     contain these characters. Combined with HTML's requirements (the
1750     first character must be a letter; no &quot;unicode&quot;, &quot;latin1&quot;, or
1751     &quot;escape&quot; characters), this results in the regular expression
1752     <tt class="docutils literal"><span class="pre">[A-Za-z][-A-Za-z0-9]*</span></tt>. Docutils adds a normalisation by
1753     downcasing and merge of consecutive hyphens.</p>
1754     </div>
1755     </div>
1756     <div class="section" id="custom-interpreted-text-roles">
1757     <span id="role"></span><h2><a class="toc-backref" href="#id48">Custom Interpreted Text Roles</a></h2>
1758     <table class="docutils field-list" frame="void" rules="none">
1759     <col class="field-name" />
1760     <col class="field-body" />
1761     <tbody valign="top">
1762     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;role&quot;</td>
1763     </tr>
1764     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">None; affects subsequent parsing.</td>
1765     </tr>
1766     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">Two; one required (new role name), one optional
1767     (base role name, in parentheses).</td>
1768     </tr>
1769     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">Possible (depends on base role).</td>
1770     </tr>
1771     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">depends on base role.</td>
1772     </tr>
1773     </tbody>
1774     </table>
1775     <p>(New in Docutils 0.3.2)</p>
1776     <p>The &quot;role&quot; directive dynamically creates a custom interpreted text
1777     role and registers it with the parser. This means that after
1778     declaring a role like this:</p>
1779     <pre class="literal-block">
1780     .. role:: custom
1781     </pre>
1782     <p>the document may use the new &quot;custom&quot; role:</p>
1783     <pre class="literal-block">
1784     An example of using :custom:`interpreted text`
1785     </pre>
1786     <p>This will be parsed into the following document tree fragment:</p>
1787     <pre class="literal-block">
1788     &lt;paragraph&gt;
1789     An example of using
1790     &lt;inline classes=&quot;custom&quot;&gt;
1791     interpreted text
1792     </pre>
1793     <p>The role must be declared in a document before it can be used.</p>
1794     <p>The new role may be based on an existing role, specified as a second
1795     argument in parentheses (whitespace optional):</p>
1796     <pre class="literal-block">
1797     .. role:: custom(emphasis)
1798    
1799     :custom:`text`
1800     </pre>
1801     <p>The parsed result is as follows:</p>
1802     <pre class="literal-block">
1803     &lt;paragraph&gt;
1804     &lt;emphasis classes=&quot;custom&quot;&gt;
1805     text
1806     </pre>
1807     <p>If no base role is explicitly specified, a generic custom role is
1808     automatically used. Subsequent interpreted text will produce an
1809     &quot;inline&quot; element with a &quot;classes&quot; attribute, as in the first example
1810     above.</p>
1811     <p>With most roles, the &quot;:class:&quot; option can be used to set a &quot;classes&quot;
1812     attribute that is different from the role name. For example:</p>
1813     <pre class="literal-block">
1814     .. role:: custom
1815     :class: special
1816    
1817     :custom:`interpreted text`
1818     </pre>
1819     <p>This is the parsed result:</p>
1820     <pre class="literal-block">
1821     &lt;paragraph&gt;
1822     &lt;inline classes=&quot;special&quot;&gt;
1823     interpreted text
1824     </pre>
1825     <p id="role-class">The following option is recognized by the &quot;role&quot; directive for most
1826     base roles:</p>
1827     <dl class="docutils">
1828     <dt><tt class="docutils literal">class</tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
1829     <dd>Set the &quot;classes&quot; attribute value on the element produced
1830     (<tt class="docutils literal">inline</tt>, or element associated with a base class) when the
1831     custom interpreted text role is used. If no directive options are
1832     specified, a &quot;class&quot; option with the directive argument (role
1833     name) as the value is implied. See the <a class="reference internal" href="#class">class</a> directive above.</dd>
1834     </dl>
1835     <p>Specific base roles may support other options and/or directive
1836     content. See the <a class="reference external" href="roles.html">reStructuredText Interpreted Text Roles</a> document
1837     for details.</p>
1838     </div>
1839     <div class="section" id="setting-the-default-interpreted-text-role">
1840     <span id="default-role"></span><h2><a class="toc-backref" href="#id49">Setting the Default Interpreted Text Role</a></h2>
1841     <table class="docutils field-list" frame="void" rules="none">
1842     <col class="field-name" />
1843     <col class="field-body" />
1844     <tbody valign="top">
1845     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;default-role&quot;</td>
1846     </tr>
1847     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">None; affects subsequent parsing.</td>
1848     </tr>
1849     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">One, optional (new default role name).</td>
1850     </tr>
1851     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1852     </tr>
1853     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1854     </tr>
1855     </tbody>
1856     </table>
1857     <p>(New in Docutils 0.3.10)</p>
1858     <p>The &quot;default-role&quot; directive sets the default interpreted text role,
1859     the role that is used for interpreted text without an explicit role.
1860     For example, after setting the default role like this:</p>
1861     <pre class="literal-block">
1862     .. default-role:: subscript
1863     </pre>
1864     <p>any subsequent use of implicit-role interpreted text in the document
1865     will use the &quot;subscript&quot; role:</p>
1866     <pre class="literal-block">
1867     An example of a `default` role.
1868     </pre>
1869     <p>This will be parsed into the following document tree fragment:</p>
1870     <pre class="literal-block">
1871     &lt;paragraph&gt;
1872     An example of a
1873     &lt;subscript&gt;
1874     default
1875     role.
1876     </pre>
1877     <p>Custom roles may be used (see the &quot;<a class="reference internal" href="#role">role</a>&quot; directive above), but it
1878     must have been declared in a document before it can be set as the
1879     default role. See the <a class="reference external" href="roles.html">reStructuredText Interpreted Text Roles</a>
1880     document for details of built-in roles.</p>
1881     <p>The directive may be used without an argument to restore the initial
1882     default interpreted text role, which is application-dependent. The
1883     initial default interpreted text role of the standard reStructuredText
1884     parser is &quot;title-reference&quot;.</p>
1885     </div>
1886     <div class="section" id="metadata-document-title">
1887     <span id="title"></span><h2><a class="toc-backref" href="#id50">Metadata Document Title</a></h2>
1888     <table class="docutils field-list" frame="void" rules="none">
1889     <col class="field-name" />
1890     <col class="field-body" />
1891     <tbody valign="top">
1892     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;title&quot;</td>
1893     </tr>
1894     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">None.</td>
1895     </tr>
1896     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">1, required (the title text).</td>
1897     </tr>
1898     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1899     </tr>
1900     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">None.</td>
1901     </tr>
1902     </tbody>
1903     </table>
1904     <p>The &quot;title&quot; directive specifies the document title as metadata, which
1905     does not become part of the document body. It overrides a
1906     document-supplied title. For example, in HTML output the metadata
1907     document title appears in the title bar of the browser window.</p>
1908     </div>
1909     <div class="section" id="restructuredtext-test-directive">
1910     <h2><a class="toc-backref" href="#id51">Restructuredtext-Test-Directive</a></h2>
1911     <table class="docutils field-list" frame="void" rules="none">
1912     <col class="field-name" />
1913     <col class="field-body" />
1914     <tbody valign="top">
1915     <tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">&quot;restructuredtext-test-directive&quot;</td>
1916     </tr>
1917     <tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">system_warning</td>
1918     </tr>
1919     <tr class="field"><th class="field-name">Directive Arguments:</th><td class="field-body">None.</td>
1920     </tr>
1921     <tr class="field"><th class="field-name">Directive Options:</th><td class="field-body">None.</td>
1922     </tr>
1923     <tr class="field"><th class="field-name">Directive Content:</th><td class="field-body">Interpreted as a literal block.</td>
1924     </tr>
1925     </tbody>
1926     </table>
1927     <p>This directive is provided for test purposes only. (Nobody is
1928     expected to type in a name <em>that</em> long!) It is converted into a
1929     level-1 (info) system message showing the directive data, possibly
1930     followed by a literal block containing the rest of the directive
1931     block.</p>
1932     <!-- Local Variables:
1933     mode: indented-text
1934     indent-tabs-mode: nil
1935     sentence-end-double-space: t
1936     fill-column: 70
1937     End: -->
1938     </div>
1939     </div>
1940     </div>
1941     <div class="footer">
1942     <hr class="footer" />
1943     <a class="reference external" href="directives.txt">View document source</a>.
1944     Generated on: 2010-06-17 02:42 UTC.
1945     Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
1946    
1947     </div>
1948     </body>
1949     </html>