<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>reStructuredText Directives</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2004-02-17 15:33:59 -0600 (Tue, 17 Feb 2004)" />
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="restructuredtext-directives">
<h1 class="title">reStructuredText Directives</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>1.1</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2004-02-17 15:33:59 -0600 (Tue, 17 Feb 2004)</td></tr>
</tbody>
</table>
<p>This document describes the directives implemented in the reference
reStructuredText parser.</p>
<p>Directives have the following syntax:</p>
<pre class="literal-block">+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block |
| |
+-------------------------------+
</pre>
<p>Directives begin with an explicit markup start (two periods and a
space), followed by the directive type and two colons (collectively,
the "directive marker"). The directive block begins immediately after
the directive marker, and includes all subsequent indented lines. The
directive block is divided into arguments, options (a field list), and
content (in that order), any of which may appear. See the <a class="reference" href="./reStructuredText.html#directives">Directives</a>
section in the <a class="reference" href="./reStructuredText.html">reStructuredText Markup Specification</a> for syntax
details.</p>
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#admonitions" id="id1" name="id1">Admonitions</a></li>
<li><a class="reference" href="#images" id="id2" name="id2">Images</a><ul>
<li><a class="reference" href="#image" id="id3" name="id3">Image</a></li>
<li><a class="reference" href="#figure" id="id4" name="id4">Figure</a></li>
</ul>
</li>
<li><a class="reference" href="#body-elements" id="id5" name="id5">Body Elements</a><ul>
<li><a class="reference" href="#topic" id="id6" name="id6">Topic</a></li>
<li><a class="reference" href="#line-block" id="id7" name="id7">Line Block</a></li>
<li><a class="reference" href="#parsed-literal-block" id="id8" name="id8">Parsed Literal Block</a></li>
</ul>
</li>
<li><a class="reference" href="#document-parts" id="id9" name="id9">Document Parts</a><ul>
<li><a class="reference" href="#table-of-contents" id="id10" name="id10">Table of Contents</a></li>
<li><a class="reference" href="#automatic-section-numbering" id="id11" name="id11">Automatic Section Numbering</a></li>
</ul>
</li>
<li><a class="reference" href="#references" id="id12" name="id12">References</a><ul>
<li><a class="reference" href="#target-footnotes" id="id13" name="id13">Target Footnotes</a></li>
<li><a class="reference" href="#footnotes" id="id14" name="id14">Footnotes</a></li>
<li><a class="reference" href="#citations" id="id15" name="id15">Citations</a></li>
</ul>
</li>
<li><a class="reference" href="#html-specific" id="id16" name="id16">HTML-Specific</a><ul>
<li><a class="reference" href="#meta" id="id17" name="id17">Meta</a></li>
<li><a class="reference" href="#imagemap" id="id18" name="id18">Imagemap</a></li>
</ul>
</li>
<li><a class="reference" href="#miscellaneous" id="id19" name="id19">Miscellaneous</a><ul>
<li><a class="reference" href="#including-an-external-document-fragment" id="id20" name="id20">Including an External Document Fragment</a></li>
<li><a class="reference" href="#raw-data-pass-through" id="id21" name="id21">Raw Data Pass-Through</a></li>
<li><a class="reference" href="#replacement-text" id="id22" name="id22">Replacement Text</a></li>
<li><a class="reference" href="#restructuredtext-test-directive" id="id23" name="id23">Restructuredtext-Test-Directive</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="admonitions">
<h1><a class="toc-backref" href="#id1" name="admonitions">Admonitions</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2">Directive Types:</th></tr>
<tr><td> </td><td class="field-body">"attention", "caution", "danger", "error", "hint",
"important", "note", "tip", "warning"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">attention, caution, danger, error, hint, important,
note, tip, warning</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Interpreted as body elements.</td>
</tr>
</tbody>
</table>
<p>Admonitions are specially marked "topics" that can appear anywhere an
ordinary body element can. They contain arbitrary body elements.
Typically, an admonition is rendered as an offset block in a document,
sometimes outlined or shaded, with a title matching the admonition
type. For example:</p>
<pre class="literal-block">.. DANGER::
Beware killer rabbits!
</pre>
<p>This directive might be rendered something like this:</p>
<pre class="literal-block">+------------------------+
| !DANGER! |
| |
| Beware killer rabbits! |
+------------------------+
</pre>
<p>The following admonition directives have been implemented:</p>
<ul class="simple">
<li>attention</li>
<li>caution</li>
<li>danger</li>
<li>error</li>
<li>hint</li>
<li>important</li>
<li>note</li>
<li>tip</li>
<li>warning</li>
</ul>
<p>Any text immediately following the directive indicator (on the same
line and/or indented on following lines) is interpreted as a directive
block and is parsed for normal body elements. For example, the
following "note" admonition directive contains one paragraph and a
bullet list consisting of two list items:</p>
<pre class="literal-block">.. note:: This is a note admonition.
This is the second line of the first paragraph.
- The note contains all indented body elements
following.
- It includes this bullet list.
</pre>
</div>
<div class="section" id="images">
<h1><a class="toc-backref" href="#id2" name="images">Images</a></h1>
<p>There are two image directives: "image" and "figure".</p>
<div class="section" id="image">
<h2><a class="toc-backref" href="#id3" name="image">Image</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"image"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">image</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">One, required (image URI).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>An "image" is a simple picture:</p>
<pre class="literal-block">.. image:: picture.png
</pre>
<p>The URI for the image source file is specified in the directive
argument. As with hyperlink targets, the image URI may begin on the
same line as the explicit markup start and target name, or it may
begin in an indented text block immediately following, with no
intervening blank lines. If there are multiple lines in the link
block, they are stripped of leading and trailing whitespace and joined
together.</p>
<p>Optionally, the image link block may end with a flat field list, the
<span class="target" id="image-options">image options</span>. For example:</p>
<pre class="literal-block">.. image:: picture.jpeg
:height: 100
:width: 200
:scale: 50
:alt: alternate text
:align: right
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">alt</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">text</span></dt>
<dd>Alternate text: a short description of the image, displayed by
applications that cannot display images, or spoken by applications
for visually impaired users.</dd>
<dt><tt class="docutils literal"><span class="pre">height</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The height of the image in pixels, used to reserve space or scale
the image vertically.</dd>
<dt><tt class="docutils literal"><span class="pre">width</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The width of the image in pixels, used to reserve space or scale
the image horizontally.</dd>
<dt><tt class="docutils literal"><span class="pre">scale</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The uniform scaling factor of the image, a percentage (but no "%"
symbol is required or allowed). "100" means full-size.</dd>
<dt><tt class="docutils literal"><span class="pre">align</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">"top", "middle", "bottom", "left", "center", or "right"</span></dt>
<dd>The alignment of the image, equivalent to the HTML <tt class="docutils literal"><span class="pre"><img></span></tt> tag's
"align" attribute. The values "top", "middle", and "bottom"
control an image's vertical alignment (relative to the text
baseline); they are only useful for inline images (substitutions).
The values "left", "center", and "right" control an image's
horizontal alignment, allowing the image to float and have the
text flow around it. The specific behavior depends upon the
browser or rendering software used.</dd>
</dl>
</div>
<div class="section" id="figure">
<h2><a class="toc-backref" href="#id4" name="figure">Figure</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"figure"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">figure, image, caption, legend</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">One, required (image URI).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible; same as those of the <a class="reference" href="#image">image</a> directive.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Interpreted as the figure caption and an optional
legend.</td>
</tr>
</tbody>
</table>
<p>A "figure" consists of <a class="reference" href="#image">image</a> data (including <a class="reference" href="#image-options">image options</a>), an
optional caption (a single paragraph), and an optional legend
(arbitrary body elements):</p>
<pre class="literal-block">.. figure:: picture.png
:scale: 50
:alt: map to buried treasure
This is the caption of the figure (a simple paragraph).
The legend consists of all elements after the caption. In this
case, the legend consists of this paragraph and the following
table:
+-----------------------+-----------------------+
| Symbol | Meaning |
+=======================+=======================+
| .. image:: tent.png | Campground |
+-----------------------+-----------------------+
| .. image:: waves.png | Lake |
+-----------------------+-----------------------+
| .. image:: peak.png | Mountain |
+-----------------------+-----------------------+
</pre>
<p>There must be blank lines before the caption paragraph and before the
legend. To specify a legend without a caption, use an empty comment
("..") in place of the caption.</p>
</div>
</div>
<div class="section" id="body-elements">
<h1><a class="toc-backref" href="#id5" name="body-elements">Body Elements</a></h1>
<div class="section" id="topic">
<h2><a class="toc-backref" href="#id6" name="topic">Topic</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"topic"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">topic</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">1, required (topic title).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Interpreted as the topic body.</td>
</tr>
</tbody>
</table>
<p>A topic is like a block quote with a title, or a self-contained
section with no subsections. Use the "topic" directive to indicate a
self-contained idea that is separate from the flow of the document.
Topics may occur anywhere a section or transition may occur. Body
elements (including topics) may not contain nested topics.</p>
<p>The directive's sole argument is interpreted as the topic title; the
next line must be blank. All subsequent lines make up the topic body,
interpreted as body elements. For example:</p>
<pre class="literal-block">topic:: Topic Title
Subsequent indented lines comprise
the body of the topic, and are
interpreted as body elements.
</pre>
</div>
<div class="section" id="line-block">
<h2><a class="toc-backref" href="#id7" name="line-block">Line Block</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"line-block"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">line_block</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Becomes the body of the line block.</td>
</tr>
</tbody>
</table>
<p>The "line-block" directive constructs an element where whitespace
(including linebreaks) is significant and inline markup is supported.
It is equivalent to a <a class="reference" href="#parsed-literal-block">parsed literal block</a> with different
rendering: typically in an ordinary serif typeface instead of a
typewriter/monospaced face, and not automatically indented. (Have the
line-block directive begin a block quote to get an indented line
block.) Line blocks are useful for address blocks and verse (poetry,
song lyrics), where the structure of lines is significant. For
example, here's a classic:</p>
<pre class="literal-block">"To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
Ewan McTeagle (for Lassie O'Shea):
.. line-block::
Lend us a couple of bob till Thursday.
I'm absolutely skint.
But I'm expecting a postal order and I can pay you back
as soon as it comes.
Love, Ewan.
</pre>
</div>
<div class="section" id="parsed-literal-block">
<h2><a class="toc-backref" href="#id8" name="parsed-literal-block">Parsed Literal Block</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"parsed-literal"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">literal_block</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Becomes the body of the literal block.</td>
</tr>
</tbody>
</table>
<p>Unlike an ordinary literal block, the "parsed-literal" directive
constructs a literal block where the text is parsed for inline markup.
It is equivalent to a <a class="reference" href="#line-block">line block</a> with different rendering:
typically in a typewriter/monospaced typeface, like an ordinary
literal block. Parsed literal blocks are useful for adding hyperlinks
to code examples. However, care must be taken with the text, because
inline markup is recognized; there is no protection from parsing.
Backslash-escapes may be necessary in places.</p>
<p>For example, all the element names in this content model are links:</p>
<pre class="literal-block">.. parsed-literal::
((title_,
subtitle_?)?,
docinfo_?,
decoration_?,
`%structure.model;`_)
</pre>
</div>
</div>
<div class="section" id="document-parts">
<h1><a class="toc-backref" href="#id9" name="document-parts">Document Parts</a></h1>
<div class="section" id="table-of-contents">
<h2><a class="toc-backref" href="#id10" name="table-of-contents">Table of Contents</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"contents"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">pending, topic</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">One, optional: title.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The "contents" directive inserts a table of contents (TOC) in two
passes: initial parse and transform. During the initial parse, a
"pending" element is generated which acts as a placeholder, storing
the TOC title and any options internally. At a later stage in the
processing, the "pending" element is replaced by a "topic" element, a
title and the table of contents proper.</p>
<p>The directive in its simplest form:</p>
<pre class="literal-block">.. contents::
</pre>
<p>Language-dependent boilerplate text will be used for the title. The
English default title text is "Contents".</p>
<p>An explicit title, may be specified:</p>
<pre class="literal-block">.. contents:: Table of Contents
</pre>
<p>The title may span lines, although it is not recommended:</p>
<pre class="literal-block">.. contents:: Here's a very long Table of
Contents title
</pre>
<p>Options may be specified for the directive, using a field list:</p>
<pre class="literal-block">.. contents:: Table of Contents
:depth: 2
</pre>
<p>If the default title is to be used, the options field list may begin
on the same line as the directive marker:</p>
<pre class="literal-block">.. contents:: :depth: 2
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">depth</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of section levels that are collected in the table of
contents. The default is unlimited depth.</dd>
<dt><tt class="docutils literal"><span class="pre">local</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag (empty)</span></dt>
<dd>Generate a local table of contents. Entries will only include
subsections of the section in which the directive is given. If no
explicit title is given, the table of contents will not be titled.</dd>
<dt><tt class="docutils literal"><span class="pre">backlinks</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">"entry" or "top" or "none"</span></dt>
<dd>Generate links from section headers back to the table of contents
entries, the table of contents itself, or generate no backlinks.</dd>
</dl>
</div>
<div class="section" id="automatic-section-numbering">
<h2><a class="toc-backref" href="#id11" name="automatic-section-numbering">Automatic Section Numbering</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"sectnum" or "section-autonumbering" (synonyms)</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">pending, generated</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The "sectnum" (or "section-autonumbering") directive automatically
numbers sections and subsections in a document. Section numbers are
of the "multiple enumeration" form, where each level has a number,
separated by periods. For example, the title of section 1, subsection
2, subsubsection 3 would have "1.2.3" prefixed.</p>
<p>The "sectnum" directive does its work in two passes: the initial parse
and a transform. During the initial parse, a "pending" element is
generated which acts as a placeholder, storing any options internally.
At a later stage in the processing, the "pending" element triggers a
transform, which adds section numbers to titles. Section numbers are
enclosed in a "generated" element, and titles have their "auto"
attribute set to "1".</p>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">depth</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
<dd>The number of section levels that are numbered by this directive.
The default is unlimited depth.</dd>
</dl>
</div>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id12" name="references">References</a></h1>
<div class="section" id="target-footnotes">
<h2><a class="toc-backref" href="#id13" name="target-footnotes">Target Footnotes</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"target-notes"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">pending, footnote, footnote_reference</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The "target-notes" directive creates a footnote for each external
target in the text, and corresponding footnote references after each
reference. For every explicit target (of the form, <tt class="docutils literal"><span class="pre">..</span> <span class="pre">_target</span> <span class="pre">name:</span>
<span class="pre">URL</span></tt>) in the text, a footnote will be generated containing the
visible URL as content.</p>
</div>
<div class="section" id="footnotes">
<h2><a class="toc-backref" href="#id14" name="footnotes">Footnotes</a></h2>
<p><strong>NOT IMPLEMENTED YET</strong></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"footnotes"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">pending, topic</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>@@@</p>
</div>
<div class="section" id="citations">
<h2><a class="toc-backref" href="#id15" name="citations">Citations</a></h2>
<p><strong>NOT IMPLEMENTED YET</strong></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"citations"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">pending, topic</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible?</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>@@@</p>
</div>
</div>
<div class="section" id="html-specific">
<h1><a class="toc-backref" href="#id16" name="html-specific">HTML-Specific</a></h1>
<div class="section" id="meta">
<h2><a class="toc-backref" href="#id17" name="meta">Meta</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"meta"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">meta (non-standard)</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Must contain a flat field list.</td>
</tr>
</tbody>
</table>
<p>The "meta" directive is used to specify HTML metadata stored in HTML
META tags. "Metadata" is data about data, in this case data about web
pages. Metadata is used to describe and classify web pages in the
World Wide Web, in a form that is easy for search engines to extract
and collate.</p>
<p>Within the directive block, a flat field list provides the syntax for
metadata. The field name becomes the contents of the "name" attribute
of the META tag, and the field body (interpreted as a single string
without inline markup) becomes the contents of the "content"
attribute. For example:</p>
<pre class="literal-block">.. meta::
:description: The reStructuredText plaintext markup language
:keywords: plaintext, markup language
</pre>
<p>This would be converted to the following HTML:</p>
<pre class="literal-block"><meta name="description"
content="The reStructuredText plaintext markup language">
<meta name="keywords" content="plaintext, markup language">
</pre>
<p>Support for other META attributes ("http-equiv", "scheme", "lang",
"dir") are provided through field arguments, which must be of the form
"attr=value":</p>
<pre class="literal-block">.. meta::
:description lang=en: An amusing story
:description lang=fr: Un histoire amusant
</pre>
<p>And their HTML equivalents:</p>
<pre class="literal-block"><meta name="description" lang="en" content="An amusing story">
<meta name="description" lang="fr" content="Un histoire amusant">
</pre>
<p>Some META tags use an "http-equiv" attribute instead of the "name"
attribute. To specify "http-equiv" META tags, simply omit the name:</p>
<pre class="literal-block">.. meta::
:http-equiv=Content-Type: text/html; charset=ISO-8859-1
</pre>
<p>HTML equivalent:</p>
<pre class="literal-block"><meta http-equiv="Content-Type"
content="text/html; charset=ISO-8859-1">
</pre>
</div>
<div class="section" id="imagemap">
<h2><a class="toc-backref" href="#id18" name="imagemap">Imagemap</a></h2>
<p><strong>NOT IMPLEMENTED YET</strong></p>
<p>Non-standard element: imagemap.</p>
</div>
</div>
<div class="section" id="miscellaneous">
<h1><a class="toc-backref" href="#id19" name="miscellaneous">Miscellaneous</a></h1>
<div class="section" id="including-an-external-document-fragment">
<h2><a class="toc-backref" href="#id20" name="including-an-external-document-fragment">Including an External Document Fragment</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"include"</td>
</tr>
<tr class="field"><th class="field-name">DTD Elements:</th><td class="field-body">depend on data being included</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">One, required (path to include file).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
</tbody>
</table>
<p>The "include" directive reads a reStructuredText-formatted text file
and parses it in the current document's context at the point of the
directive. For example:</p>
<pre class="literal-block">This first example will be parsed at the document level, and can
thus contain any construct, including section headers.
.. include:: inclusion.txt
This second will be parsed in a block quote context.
Therefore it may only contain body elements. It may not
contain section headers.
.. include:: inclusion.txt
</pre>
<p>If an included document fragment contains section structure, the title
adornments must match those of the master document.</p>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">literal</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">flag (empty)</span></dt>
<dd>The entire included text is inserted into the document as a single
literal block (useful for program listings).</dd>
</dl>
</div>
<div class="section" id="raw-data-pass-through">
<h2><a class="toc-backref" href="#id21" name="raw-data-pass-through">Raw Data Pass-Through</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"raw"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">pending</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">One, required (output format type).</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">Possible.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Stored verbatim, uninterpreted. None (empty) if a
"file" or "url" option given.</td>
</tr>
</tbody>
</table>
<p>The "raw" directive indicates non-reStructuredText data that is to be
passed untouched to the Writer. The name of the output format is
given in the first argument. During the initial parse, a "pending"
element is generated which acts as a placeholder, storing the format
and raw data internally. The interpretation of the code is up to the
Writer. A Writer may ignore any raw output not matching its format.</p>
<p>For example, the following input would be passed untouched by an HTML
Writer:</p>
<pre class="literal-block">.. raw:: html
<hr width=50 size=10>
</pre>
<p>A LaTeX Writer could insert the following raw content into its
output stream:</p>
<pre class="literal-block">.. raw:: latex
\documentclass[twocolumn]{article}
</pre>
<p>Raw data can also be read from an external file, specified in a
directive option. In this case, the content block must be empty. For
example:</p>
<pre class="literal-block">.. raw:: html
:file: inclusion.html
</pre>
<p>The following options are recognized:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">file</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
<dd>The local filesystem path of a raw data file to be included.</dd>
<dt><tt class="docutils literal"><span class="pre">url</span></tt> <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
<dd>An Internet URL reference to a raw data file to be included.</dd>
</dl>
</div>
<div class="section" id="replacement-text">
<h2><a class="toc-backref" href="#id22" name="replacement-text">Replacement Text</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"replace"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">pending</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">A single paragraph; may contain inline markup.</td>
</tr>
</tbody>
</table>
<p>The "replace" directive is used to indicate replacement text for a
substitution reference. It may be used within substitution
definitions only. For example, this directive can be used to expand
abbreviations:</p>
<pre class="literal-block">.. |reST| replace:: reStructuredText
Yes, |reST| is a long word, so I can't blame anyone for wanting to
abbreviate it.
</pre>
<p>As reStructuredText doesn't support nested inline markup, the only way
to create a reference with styled text is to use substitutions with
the "replace" directive:</p>
<pre class="literal-block">I recommend you try |Python|_.
.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
</pre>
</div>
<div class="section" id="restructuredtext-test-directive">
<h2><a class="toc-backref" href="#id23" name="restructuredtext-test-directive">Restructuredtext-Test-Directive</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Directive Type:</th><td class="field-body">"restructuredtext-test-directive"</td>
</tr>
<tr class="field"><th class="field-name">DTD Element:</th><td class="field-body">system_warning</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Arguments:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Options:</th></tr>
<tr><td> </td><td class="field-body">None.</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">Directive Content:</th></tr>
<tr><td> </td><td class="field-body">Interpreted as a literal block.</td>
</tr>
</tbody>
</table>
<p>This directive is provided for test purposes only. (Nobody is
expected to type in a name <em>that</em> long!) It is converted into a
level-1 (info) system message showing the directive data, possibly
followed by a literal block containing the rest of the directive
block.</p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</div>
</body>
</html>