1 |
<?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@python.org">goodger@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 & 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 |
| ".. " | directive type "::" 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 "directive marker"). 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 "doctree elements" (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">"attention", "caution", "danger", "error", "hint", |
132 |
"important", "note", "tip", "warning", "admonition"</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 "topics" 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 "note" 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">"admonition"</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 "classes" attribute value |
209 |
after being converted into a valid identifier form (down-cased; |
210 |
non-alphanumeric characters converted to single hyphens; "admonition-" |
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 |
<document source="test data"> |
220 |
<admonition classes="admonition-and-by-the-way"> |
221 |
<title> |
222 |
And, by the way... |
223 |
<paragraph> |
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 "classes" 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: "image" and "figure".</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">"image"</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 "image" 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 "scale" |
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 "height" |
290 |
above, when the "scale" 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 "%" symbol is optional)</span></dt> |
292 |
<dd><p class="first">The uniform scaling factor of the image. The default is "100 %", i.e. |
293 |
no scaling.</p> |
294 |
<p class="last">If no "height" or "width" 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">"top", "middle", "bottom", "left", "center", or "right"</span></dt> |
299 |
<dd>The alignment of the image, equivalent to the HTML <tt class="docutils literal"><img></tt> tag's |
300 |
"align" attribute. The values "top", "middle", and "bottom" |
301 |
control an image's vertical alignment (relative to the text |
302 |
baseline); they are only useful for inline images (substitutions). |
303 |
The values "left", "center", and "right" 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 ("clickable"). 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 "classes" 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">"figure"</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 "figure" 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 |
("..") in place of the caption.</p> |
363 |
<p>The "figure" directive supports all of the options of the "image" |
364 |
directive (see <a class="reference internal" href="#image-options">image options</a> above). These options (except |
365 |
"align") 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">"left", "center", or "right"</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">"image", <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 "image" 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 "width" attribute of the "figure" doctree element.</p> |
382 |
<p>This option does not scale the included image; use the "width" |
383 |
<a class="reference internal" href="#image">image</a> option for that.</p> |
384 |
<pre class="last literal-block"> |
385 |
+---------------------------+ |
386 |
| figure | |
387 |
| | |
388 |
|<------ figwidth --------->| |
389 |
| | |
390 |
| +---------------------+ | |
391 |
| | image | | |
392 |
| | | | |
393 |
| |<--- width --------->| | |
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 "classes" 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">"topic"</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 "topic" 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 "classes" 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">"sidebar"</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 "floats" 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 "classes" 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 "line-block" 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">"line-block"</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 "line-block" 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 |
"To Ma Own Beloved Lassie: A Poem on her 17th Birthday", 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 "classes" 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">"parsed-literal"</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 "parsed-literal" 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 "ASCII art" 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 "classes" 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">"rubric"</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">—Random House Webster's College Dictionary, 1991</p> |
617 |
</blockquote> |
618 |
<p>The "rubric" directive inserts a "rubric" 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 "classes" 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">"epigraph"</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 "epigraph" directive produces an "epigraph"-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 |
<block_quote classes="epigraph"> |
661 |
<paragraph> |
662 |
No matter where you go, there you are. |
663 |
<attribution> |
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">"highlights"</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 "highlights" directive produces a "highlights"-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">"pull-quote"</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 "pulled out and quoted", |
709 |
typically in a larger typeface. Pull-quotes are used to attract |
710 |
attention, especially in long articles.</p> |
711 |
<p>The "pull-quote" directive produces a "pull-quote"-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">"compound"</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 "compound" 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 "embedded" 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 "compound" directive is <em>not</em> a generic block-level container |
754 |
like HTML's <tt class="docutils literal"><div></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 "classes" 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">"container"</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 "container" directive surrounds its contents (arbitrary body |
796 |
elements) with a generic block-level "container" element. Combined |
797 |
with the optional "<a class="reference internal" href="#classes">classes</a>" attribute argument(s), this is an |
798 |
extension mechanism for users & 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 |
<container classes="custom"> |
807 |
<paragraph> |
808 |
This paragraph might be rendered in a custom way. |
809 |
</pre> |
810 |
<p>The "container" directive is the equivalent of HTML's <tt class="docutils literal"><div></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">"table"</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 "table" 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 "not" |
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 "classes" 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">"csv-table"</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 "csv-table" directive's ":file:" and ":url:" options represent |
881 |
a potential security holes. They can be disabled with the |
882 |
"<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" runtime setting.</p> |
883 |
</div> |
884 |
<p>(New in Docutils 0.3.4)</p> |
885 |
<p>The "csv-table" 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: "Treat", "Quantity", "Description" |
894 |
:widths: 15, 10, 30 |
895 |
|
896 |
"Albatross", 2.99, "On a stick!" |
897 |
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be |
898 |
crunchy, now would it?" |
899 |
"Gannet Ripple", 1.99, "On a stick!" |
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 "empty" 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 "classes" 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 | "tab" | "space"</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">"</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. "He said, ""Hi!"""<!-- 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">"list-table"</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 "list-table" directive is used to create a table from data in a |
981 |
uniform two-level bullet list. "Uniform" 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 "classes" 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">"contents"</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 "contents" 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 "Contents".</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">"entry" or "top" or "none"</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 "classes" 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">"sectnum" or "section-autonumbering" (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 "sectnum" (or "section-autonumbering") 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 "multiple enumeration" 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 "1.2.3" prefixed.</p> |
1111 |
<p>The "sectnum" directive does its work in two passes: the initial parse |
1112 |
and a transform. During the initial parse, a "pending" element is |
1113 |
generated which acts as a placeholder, storing any options internally. |
1114 |
At a later stage in the processing, the "pending" element triggers a |
1115 |
transform, which adds section numbers to titles. Section numbers are |
1116 |
enclosed in a "generated" element, and titles have their "auto" |
1117 |
attribute set to "1".</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 "3.2.", which |
1126 |
will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that |
1127 |
any separating punctuation (in the example, a period, ".") 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 & 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">"header" and "footer"</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 "header" and "footer" 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 "header" and "footer" 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 "header" and |
1176 |
"footer" 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">"target-notes"</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 "target-notes" 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 "classes" 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">"footnotes"</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>@@@</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">"citations"</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>@@@</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">"meta"</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 "meta" directive is used to specify HTML metadata stored in HTML |
1281 |
META tags. "Metadata" 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 "name" attribute |
1287 |
of the META tag, and the field body (interpreted as a single string |
1288 |
without inline markup) becomes the contents of the "content" |
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 |
<meta name="description" |
1298 |
content="The reStructuredText plaintext markup language"> |
1299 |
<meta name="keywords" content="plaintext, markup language"> |
1300 |
</pre> |
1301 |
<p>Support for other META attributes ("http-equiv", "scheme", "lang", |
1302 |
"dir") are provided through field arguments, which must be of the form |
1303 |
"attr=value":</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 |
<meta name="description" lang="en" content="An amusing story"> |
1312 |
<meta name="description" lang="fr" content="Une histoire amusante"> |
1313 |
</pre> |
1314 |
<p>Some META tags use an "http-equiv" attribute instead of the "name" |
1315 |
attribute. To specify "http-equiv" 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 |
<meta http-equiv="Content-Type" |
1323 |
content="text/html; charset=ISO-8859-1"> |
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">"replace"</td> |
1345 |
</tr> |
1346 |
<tr class="field"><th class="field-name">Doctree Element:</th><td class="field-body">Text & 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 "replace" 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 "replace" 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">"unicode"</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 "unicode" 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">&#x1a2b;</tt></li> |
1405 |
</ul> |
1406 |
</li> |
1407 |
<li><strong>text</strong>, which is used as-is.</li> |
1408 |
</ul> |
1409 |
<p>Text following " .. " 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">"date"</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 "date" 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 "%Y-%m-%d" (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">"include"</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 "include" directive represents a potential security hole. It |
1495 |
can be disabled with the "<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" runtime setting.</p> |
1496 |
</div> |
1497 |
<p>The "include" 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 "docutils" 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 |
"include" data files, angle brackets around the file name:</p> |
1523 |
<pre class="literal-block"> |
1524 |
.. include:: <isonum.txt> |
1525 |
</pre> |
1526 |
<p>The current set of standard "include" 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">"raw"</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 |
"file" or "url" 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 "raw" directive represents a potential security hole. It can |
1580 |
be disabled with the "<a class="reference external" href="../../user/config.html#raw-enabled">raw_enabled</a>" or "<a class="reference external" href="../../user/config.html#file-insertion-enabled">file_insertion_enabled</a>" |
1581 |
runtime settings.</p> |
1582 |
</div> |
1583 |
<div class="caution"> |
1584 |
<p class="first admonition-title">Caution!</p> |
1585 |
<p>The "raw" directive is a stop-gap measure allowing the author to |
1586 |
bypass reStructuredText's markup. It is a "power-user" feature |
1587 |
that should not be overused or abused. The use of "raw" ties |
1588 |
documents to specific output formats and makes them less portable.</p> |
1589 |
<p class="last">If you often need to use the "raw" directive or a "raw"-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 "raw" 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 |
<hr width=50 size=10> |
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">"class"</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 "class" directive sets the "classes" 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 "classes" 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 "Rot-Gelb.Blau GrĂ¼n:+2008" becomes "rot-gelb-blau grun-2008". |
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 "special" 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 |
<paragraph classes="special"> |
1689 |
This is a "special" paragraph. |
1690 |
<section classes="exceptional remarkable"> |
1691 |
<title> |
1692 |
An Exceptional Section |
1693 |
<paragraph> |
1694 |
This is an ordinary paragraph. |
1695 |
<paragraph classes="multiple"> |
1696 |
First paragraph. |
1697 |
<paragraph classes="multiple"> |
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 "classes" attribute value on a block quote, the |
1704 |
"class" 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 "class" |
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 "classes" 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 "classes" and "id" 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 ("-"), underscores ("_"), colons (":"), and periods |
1732 |
(".").</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 "name" token |
1736 |
("flex" tokenizer notation below; "latin1" and "escape" 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 [&iexcl;-&yuml;] |
1741 |
escape {unicode}|\\[ -~&iexcl;-&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 ("_"), colons (":"), or |
1748 |
periods ("."), therefore "classes" and "id" attributes should not |
1749 |
contain these characters. Combined with HTML's requirements (the |
1750 |
first character must be a letter; no "unicode", "latin1", or |
1751 |
"escape" 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">"role"</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 "role" 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 "custom" 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 |
<paragraph> |
1789 |
An example of using |
1790 |
<inline classes="custom"> |
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 |
<paragraph> |
1804 |
<emphasis classes="custom"> |
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 |
"inline" element with a "classes" attribute, as in the first example |
1810 |
above.</p> |
1811 |
<p>With most roles, the ":class:" option can be used to set a "classes" |
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 |
<paragraph> |
1822 |
<inline classes="special"> |
1823 |
interpreted text |
1824 |
</pre> |
1825 |
<p id="role-class">The following option is recognized by the "role" 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 "classes" 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 "class" 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">"default-role"</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 "default-role" 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 "subscript" 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 |
<paragraph> |
1872 |
An example of a |
1873 |
<subscript> |
1874 |
default |
1875 |
role. |
1876 |
</pre> |
1877 |
<p>Custom roles may be used (see the "<a class="reference internal" href="#role">role</a>" 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 "title-reference".</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">"title"</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 "title" 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">"restructuredtext-test-directive"</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> |