=============================
reStructuredText Directives
=============================
:Author: David Goodger
:Author: Mark Nodine (for prest-specific implementation)
:Contact: goodger@python.org mnodine@alum.mit.edu
:Revision: $Revision: 762 $
:Date: $Date: 2006-01-27 11:47:47 -0600 (Fri, 27 Jan 2006) $
:Copyright: This document has been placed in the public domain.
.. contents::
This document describes the directives implemented in the reference
reStructuredText parser.
Directives have the following syntax::
+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block |
| |
+-------------------------------+
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 Directives_
section in the `reStructuredText Markup Specification`_ for syntax
details.
Descriptions below list "doctree elements" (document tree element
names; XML DTD generic identifiers) corresponding to individual
directives. For details on the hierarchy of elements, please see `The
Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
type definition. For directive implementation details, see `Creating
reStructuredText Directives`_.
.. _Directives: ./reStructuredText.html#directives
.. _reStructuredText Markup Specification: ./reStructuredText.html
.. _The Docutils Document Tree: ../doctree.html
.. _Docutils Generic DTD: ../docutils.dtd
.. _Creating reStructuredText Directives:
tripextend.html
-------------
Admonitions
-------------
.. _attention:
.. _caution:
.. _danger:
.. _error:
.. _hint:
.. _important:
.. _note:
.. _tip:
.. _warning:
Specific Admonitions
====================
:Directive Types: "attention", "caution", "danger", "error", "hint",
"important", "note", "tip", "warning", "admonition"
:Doctree Elements: attention, caution, danger, error, hint, important,
note, tip, warning, admonition, title
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: Interpreted as body elements.
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::
.. DANGER::
Beware killer rabbits!
This directive might be rendered something like this::
+------------------------+
| !DANGER! |
| |
| Beware killer rabbits! |
+------------------------+
The following admonition directives have been implemented:
- attention
- caution
- danger
- error
- hint
- important
- note
- tip
- warning
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::
.. 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.
.. _admonition:
Generic Admonition
==================
:Directive Type: "admonition"
:Doctree Elements: admonition, title
:Directive Arguments: One, required (admonition title)
:Directive Options: Possible.
:Directive Content: Interpreted as body elements.
This is a generic, titled admonition. The title may be anything the
author desires.
The author-supplied title is also used as a "classes" attribute value
after being converted into a valid identifier form (down-cased;
non-alphanumeric characters converted to single hyphens; "admonition-"
prefixed). For example, this admonition::
.. admonition:: And, by the way...
You can make up your own admonition too.
becomes the following document tree (pseudo-XML)::
<document source="test data">
<admonition classes="admonition-and-by-the-way">
<title>
And, by the way...
<paragraph>
You can make up your own admonition too.
The following option is recognized:
``class`` : text
Override the computed "classes" attribute value. See the class_
directive below.
--------
Images
--------
There are two image directives: "image" and "figure".
Image
=====
:Directive Type: "image"
:Doctree Element: image
:Directive Arguments: One, required (image URI).
:Directive Options: Possible.
:Directive Content: None.
An "image" is a simple picture::
.. image:: picture.png
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.
Optionally, the image link block may contain a flat field list, the
_`image options`. For example::
.. image:: picture.jpeg
:height: 100
:width: 200
:scale: 50
:alt: alternate text
:align: right
The following options are recognized:
``alt`` : text
Alternate text: a short description of the image, displayed by
applications that cannot display images, or spoken by applications
for visually impaired users.
``height`` : integer
The height of the image in pixels, used to reserve space or scale
the image vertically.
``width`` : integer
The width of the image in pixels, used to reserve space or scale
the image horizontally.
``scale`` : integer
The uniform scaling factor of the image, a percentage (but no "%"
symbol is required or allowed). "100" means full-size.
``align`` : "top", "middle", "bottom", "left", "center", or "right"
The alignment of the image, equivalent to the HTML ``<img>`` 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.
``target`` : text (URI or reference name)
Makes the image into a hyperlink reference ("clickable"). The
option argument may be a URI (relative or absolute), or a
reference name with underscore suffix (e.g. ``name_``).
``class`` : text
Set a "classes" attribute value on the image element. See the
class_ directive below.
``usemap`` : text
Specifies the name of a map to be used with HTML's ``<usemap>``
tag so that clicking on the image can traverse a URI.
Figure
======
:Directive Type: "figure"
:Doctree Elements: figure, image, caption, legend
:Directive Arguments: One, required (image URI).
:Directive Options: Possible.
:Directive Content: Interpreted as the figure caption and an optional
legend.
A "figure" consists of image_ data (including `image options`_), an
optional caption (a single paragraph), and an optional legend
(arbitrary body elements)::
.. 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 |
+-----------------------+-----------------------+
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.
The "figure" directive supports all of the options of the "image"
directive (see `image options`_ above). In addition, the following
options are recognized:
``figwidth`` : integer or "image"
The width of the figure in pixels, to limit the horizontal space
used. A special value of "image" is allowed, in which case the
included image's actual width is used (requires PIL [#PIL]_). If
the image file is not found or the required software is
unavailable, this option is ignored.
Sets the "width" attribute of the "figure" doctree element.
This option does not scale the included image; use the "width"
`image`_ option for that. ::
+---------------------------+
| figure |
| |
|<------ figwidth --------->|
| |
| +---------------------+ |
| | image | |
| | | |
| |<--- width --------->| |
| +---------------------+ |
| |
|The figure's caption should|
|wrap at this width. |
+---------------------------+
``figclass`` : text
Set a "classes" attribute value on the figure element. See the
class_ directive below.
``align`` : "left", "center", or "right"
The horizontal alignment of the figure, allowing the image to
float and have the text flow around it. The specific behavior
depends upon the browser or rendering software used.
.. [#PIL] `Python Imaging Library`_.
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
---------------
Body Elements
---------------
Topic
=====
:Directive Type: "topic"
:Doctree Element: topic
:Directive Arguments: 1, required (topic title).
:Directive Options: Possible.
:Directive Content: Interpreted as the topic body.
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 and topics may not contain nested topics.
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::
.. topic:: Topic Title
Subsequent indented lines comprise
the body of the topic, and are
interpreted as body elements.
The following option is recognized:
``class`` : text
Set a "classes" attribute value on the topic element. See the
class_ directive below.
Sidebar
=======
:Directive Type: "sidebar"
:Doctree Element: sidebar
:Directive Arguments: One, required (sidebar title).
:Directive Options: Possible.
:Directive Content: Interpreted as the sidebar body.
Sidebars are like miniature, parallel documents that occur inside
other documents, providing related or reference material. A sidebar
is typically offset by a border and "floats" to the side of the page;
the document's main text may flow around it. Sidebars can also be
likened to super-footnotes; their content is outside of the flow of
the document's main text.
Sidebars may occur anywhere a section or transition may occur. Body
elements (including sidebars) may not contain nested sidebars.
The directive's sole argument is interpreted as the sidebar title,
which may be followed by a subtitle option (see below); the next line
must be blank. All subsequent lines make up the sidebar body,
interpreted as body elements. For example::
.. sidebar:: Sidebar Title
:subtitle: Optional Sidebar Subtitle
Subsequent indented lines comprise
the body of the sidebar, and are
interpreted as body elements.
The following options are recognized:
``subtitle`` : text
The sidebar's subtitle.
``class`` : text
Set a "classes" attribute value on the sidebar element. See the
class_ directive below.
Line Block
==========
.. admonition:: Deprecated
The "line-block" directive is deprecated. Use the `line block
syntax`_ instead.
.. _line block syntax: restructuredtext.html#line-blocks
:Directive Type: "line-block"
:Doctree Element: line_block
:Directive Arguments: None.
:Directive Options: Possible.
:Directive Content: Becomes the body of the line block.
The "line-block" directive constructs an element where line breaks and
initial indentation is significant and inline markup is supported. It
is equivalent to a `parsed literal block`_ 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::
"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.
The following option is recognized:
``class`` : text
Set a "classes" attribute value on the line_block element. See the
class_ directive below.
.. _parsed-literal:
Parsed Literal Block
====================
:Directive Type: "parsed-literal"
:Doctree Element: literal_block
:Directive Arguments: None.
:Directive Options: Possible.
:Directive Content: Becomes the body of the literal block.
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 `line block`_ 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 and there is no protection from parsing. Backslash-escapes
may be necessary to prevent unintended parsing. And because the
markup characters are removed by the parser, care must also be taken
with vertical alignment. Parsed "ASCII art" is tricky, and extra
whitespace may be necessary.
For example, all the element names in this content model are links::
.. parsed-literal::
( (title_, subtitle_?)?,
decoration_?,
(docinfo_, transition_?)?,
`%structure.model;`_ )
The following option is recognized:
``class`` : text
Set a "classes" attribute value on the literal_block element. See
the class_ directive below.
Rubric
======
:Directive Type: "rubric"
:Doctree Element: rubric
:Directive Arguments: 1, required (rubric text).
:Directive Options: Possible.
:Directive Content: None.
..
rubric n. 1. a title, heading, or the like, in a manuscript,
book, statute, etc., written or printed in red or otherwise
distinguished from the rest of the text. ...
-- Random House Webster's College Dictionary, 1991
The "rubric" directive inserts a "rubric" element into the document
tree. A rubric is like an informal heading that doesn't correspond to
the document's structure.
The following option is recognized:
``class`` : text
Set a "classes" attribute value on the rubric element. See the
class_ directive below.
.. _compound:
Compound Paragraph
==================
:Directive Type: "compound"
:Doctree Element: compound
:Directive Arguments: None.
:Directive Options: Possible.
:Directive Content: Interpreted as body elements.
(New in Docutils 0.3.6)
The "compound" directive is used to create a compound paragraph, which
is a single logical paragraph containing multiple physical body
elements such as simple paragraphs, literal blocks, tables, lists,
etc., instead of directly containing text and inline elements. For
example::
.. compound::
The 'rm' command is very dangerous. If you are logged
in as root and enter ::
cd /
rm -rf *
you will erase the entire contents of your file system.
In the example above, a literal block is "embedded" within a sentence
that begins in one physical paragraph and ends in another.
.. note::
The "compound" directive is *not* a generic block-level container
like HTML's ``<div>`` element. Do not use it only to group a
sequence of elements, or you may get unexpected results.
If you need a generic block-level container, please use the
container_ directive, described below.
Compound paragraphs are typically rendered as multiple distinct text
blocks, with the possibility of variations to emphasize their logical
unity:
* If paragraphs are rendered with a first-line indent, only the first
physical paragraph of a compound paragraph should have that indent
-- second and further physical paragraphs should omit the indents;
* vertical spacing between physical elements may be reduced;
* and so on.
The following option is recognized:
``class`` : text
Set a "classes" attribute value on the compound element. See the
class_ directive below.
.. _mathml:
.. _ascii-mathml:
Mathematical Equations
======================
:Directive Type: "ascii-mathml", "mathml"
:Doctree Element: mathml
:Directive Arguments: Possible.
:Directive Options: Possible.
:Directive Content: Possible.
This directive is used to create mathematical markup from `ASCIIMathML`_.
Unlike the ``mathml`` and ``ascii-mathml`` roles, which produce
inline-style mathematical markup, the directive produces display-style
markup unless it is used in a substitution definition, in which case
it also defaults to inline-style markup. However, the style can be
overridden by means of the directive options.
.. _AsciiMathML: ascii-mathml.xhtml
The following options are recognized:
``label`` : name
Specifies to attach a label to a mathml equation that becomes
a substitution definition of name annotated with the equation number.
``mstyle`` : field list text
The field list gives a set of key/value pairs for the `mstyle
attribute`_ of the generated mathml markup. For example, the
following directive would not use display style and would have the
math equation in green::
.. ascii-mathml:: E = mc^2
:mstyle:
:displaystyle: false
:mathcolor: green
.. _mstyle attribute: ascii-mathml.xhtml#attributes-for-mstyle
Container
=========
:Directive Type: "container"
:Doctree Element: container
:Directive Arguments: One or more, optional (class names).
:Directive Options: None.
:Directive Content: Interpreted as body elements.
(New in Docutils 0.3.10)
The "container" directive surrounds its contents (arbitrary body
elements) with a generic block-level "container" element. Combined
with the optional "class_" attribute argument(s), this is an extension
mechanism for users & applications. For example::
.. container:: custom
This paragraph might be rendered in a custom way.
Parsing the above results in the following pseudo-XML::
<container classes="custom">
<paragraph>
This paragraph might be rendered in a custom way.
The "container" directive is the equivalent of HTML's ``<div>``
element. It may be used to group a sequence of elements for user- or
application-specific purposes.
--------
Tables
--------
Formal tables need more structure than the reStructuredText syntax
supplies. Tables may be given titles with the table_ directive.
Sometimes reStructuredText tables are inconvenient to write, or table
data in a standard format is readily available. The csv-table_
directive supports CSV data.
Table
=====
:Directive Type: "table"
:Doctree Element: table
:Directive Arguments: 1, optional (table title).
:Directive Options: Possible.
:Directive Content: A normal reStructuredText table.
(New in Docutils 0.3.1)
The "table" directive is used to create a titled table, to associate a
title with a table::
.. table:: Truth table for "not"
===== =====
A not A
===== =====
False True
True False
===== =====
The following option is recognized:
``class`` : text
Set a "classes" attribute value on the table element. See the
class_ directive below.
.. _csv-table:
CSV Table
=========
:Directive Type: "csv-table"
:Doctree Element: table
:Directive Arguments: 1, optional (table title).
:Directive Options: Possible.
:Directive Content: A CSV (comma-separated values) table.
.. WARNING::
The "csv-table" directive's ":file:" and ":url:" options represent
a potential security holes. They can be disabled with the
"file_insertion_enabled" runtime setting.
(New in Docutils 0.3.4)
The "csv-table" directive is used to create a table from CSV
(comma-separated values) data. CSV is a common data format generated
by spreadsheet applications and commercial databases. The data may be
internal (an integral part of the document) or external (a separate
file).
Example::
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
Block markup and inline markup within cells is supported. Line ends
are recognized within cells.
Working limitations:
* Whitespace delimiters are supported only for external CSV files.
* There is no support for checking that the number of columns in each
row is the same. However, this directive supports CSV generators
that do not insert "empty" entries at the end of short rows, by
automatically adding empty entries.
.. Add "strict" option to verify input?
The following options are recognized:
``class`` : text
Set a "classes" attribute value on the table element. See the
class_ directive below.
``widths`` : integer [, integer...]
A comma- or space-separated list of relative column widths. The
default is equal-width columns (100%/#columns).
``header-rows`` : integer
The number of rows of CSV data to use in the table header.
Defaults to 0.
``stub-columns`` : integer
The number of table columns to use as stubs (row titles, on the
left). Defaults to 0.
``header`` : CSV data
Supplemental data for the table header, added independently of and
before any ``header-rows`` from the main CSV data. Must use the
same CSV format as the main CSV data.
``file`` : string (newlines removed)
The local filesystem path to a CSV data file.
``url`` : string (whitespace removed)
An Internet URL reference to a CSV data file.
``encoding`` : name of text encoding
The text encoding of the external CSV data (file or URL).
Defaults to the document's encoding (if specified).
``delim`` : char | "tab" | "space"
A one-character string used to separate fields. Defaults to ``,``
(comma). May be specified as a Unicode code point; see the
unicode_ directive for syntax details.
``quote`` : char
A one-character string used to quote elements containing the
delimiter or which start with the quote character. Defaults to
``"`` (quote). May be specified as a Unicode code point; see the
unicode_ directive for syntax details.
``keepspace`` : flag
Treat whitespace immediately following the delimiter as
significant. The default is to ignore such whitespace.
``escape`` : char
A one-character string used to escape the delimiter or quote
characters. May be specified as a Unicode code point; see the
unicode_ directive for syntax details. Used when the delimiter is
used in an unquoted field, or when quote characters are used
within a field. The default is to double-up the character,
e.g. "He said, ""Hi!"""
.. Add another possible value, "double", to explicitly indicate
the default case?
List Table
==========
:Directive Type: "list-table"
:Doctree Element: table
:Directive Arguments: 1, optional (table title).
:Directive Options: Possible.
:Directive Content: A uniform two-level bullet list.
(New in Docutils 0.3.8. This is an initial implementation; `further
ideas`__ may be implemented in the future.)
__ http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables
The "list-table" directive is used to create a table from data in a
uniform two-level bullet list. "Uniform" means that each sublist
(second-level list) must contain the same number of list items.
Example::
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
The following options are recognized:
``class`` : text
Set a "classes" attribute value on the table element. See the
class_ directive below.
``widths`` : integer [integer...]
A comma- or space-separated list of relative column widths. The
default is equal-width columns (100%/#columns).
``header-rows`` : integer
The number of rows of list data to use in the table header.
Defaults to 0.
``stub-columns`` : integer
The number of table columns to use as stubs (row titles, on the
left). Defaults to 0.
----------------
Document Parts
----------------
.. _contents:
Table of Contents
=================
:Directive Type: "contents"
:Doctree Elements: pending, topic
:Directive Arguments: One, optional: title.
:Directive Options: Possible.
:Directive Content: None.
The "contents" directive generates a table of contents (TOC) in a
topic_. Topics, and therefore tables of contents, may occur anywhere
a section or transition may occur. Body elements and topics may not
contain tables of contents.
Here's the directive in its simplest form::
.. contents::
Language-dependent boilerplate text will be used for the title. The
English default title text is "Contents".
An explicit title may be specified::
.. contents:: Table of Contents
The title may span lines, although it is not recommended::
.. contents:: Here's a very long Table of
Contents title
Options may be specified for the directive, using a field list::
.. contents:: Table of Contents
:depth: 2
If the default title is to be used, the options field list may begin
on the same line as the directive marker::
.. contents:: :depth: 2
The following options are recognized:
``depth`` : integer
The number of section levels that are collected in the table of
contents. The default is unlimited depth.
``local`` : flag (empty)
Generate a local table of contents. Entries will only include
subsections of the section in which the directive is given. If no
explicit title is given, the table of contents will not be titled.
``backlinks`` : "entry" or "top" or "none"
Generate links from section headers back to the table of contents
entries, the table of contents itself, or generate no backlinks.
``class`` : text
Set a "classes" attribute value on the topic element. See the
class_ directive below.
.. _sectnum:
.. _section-autonumbering:
Automatic Section Numbering
===========================
:Directive Type: "sectnum" or "section-autonumbering" (synonyms)
:Doctree Elements: pending, generated
:Directive Arguments: None.
:Directive Options: Possible.
:Directive Content: None.
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.
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".
The following options are recognized:
``depth`` : integer
The number of section levels that are numbered by this directive.
The default is unlimited depth.
``format`` : string
A space-separated list of number formats to use for each level of
hierarchy, where each of the number formats contains one of the
following:
``i``
Lowercase Roman numerals
``I``
Uppercase Roman numerals
``a``
Lowercase alphabetic
``A``
Uppercase alphabetic
``1``
Arabic numeral
Any missing format item defaults to ``1``. For example, the
string ``I A (i)`` formats top-level section numbers using uppercase
Roman numerals, the second level using uppercase alphabetic, the
third using lowercase Roman numerals in parentheses and the rest
using Arabic numerals.
``prefix`` : string
An arbitrary string that is prefixed to the automatically
generated section numbers. It may be something like "3.2.", which
will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that
any separating punctuation (in the example, a period, ".") must be
explicitly provided. The default is no prefix.
``prefix-title`` : flag
Specifies whether a prefix should also be appended to the title
for the document.
``suffix`` : string
An arbitrary string that is appended to the automatically
generated section numbers. The default is no suffix.
``start`` : integer
The value that will be used for the first section number.
Combined with ``prefix``, this may be used to force the right
numbering for a document split over several source files. The
default is 1.
.. _header:
.. _footer:
Document Header & Footer
========================
:Directive Types: "header" and "footer"
:Doctree Elements: decoration, header, footer
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: Interpreted as body elements.
(New in Docutils 0.3.8)
The "header" and "footer" directives create document decorations,
useful for page navigation, notes, time/datestamp, etc. For example::
.. header:: This space for rent.
This will add a paragraph to the document header, which will appear at
the top of the generated web page or at the top of every printed page.
These directives may be used multiple times, cumulatively. There is
currently support for only one header and footer.
.. note::
While it is possible to use the "header" and "footer" directives to
create navigational elements for web pages, you should be aware
that Docutils is meant to be used for *document* processing, and
that a navigation bar is not typically part of a document.
Thus, you may soon find Docutils' abilities to be insufficient for
these purposes. At that time, you should consider using a
templating system (like ht2html_) rather than the "header" and
"footer" directives.
.. _ht2html: http://ht2html.sourceforge.net/
In addition to the use of these directives to populate header and
footer content, content may also be added automatically by the
processing system. For example, if certain runtime settings are
enabled, the document footer is populated with processing information
such as a datestamp, a link to `the Docutils website`_, etc.
.. _the Docutils website: http://docutils.sourceforge.net
------------
References
------------
.. _target-notes:
Target Footnotes
================
:Directive Type: "target-notes"
:Doctree Elements: pending, footnote, footnote_reference
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: None.
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, ``.. _target name:
URL``) in the text, a footnote will be generated containing the
visible URL as content.
Footnotes
=========
**NOT IMPLEMENTED YET**
:Directive Type: "footnotes"
:Doctree Elements: pending, topic
:Directive Arguments: None?
:Directive Options: Possible?
:Directive Content: None.
@@@
Citations
=========
**NOT IMPLEMENTED YET**
:Directive Type: "citations"
:Doctree Elements: pending, topic
:Directive Arguments: None?
:Directive Options: Possible?
:Directive Content: None.
@@@
---------------
HTML-Specific
---------------
Meta
====
:Directive Type: "meta"
:Doctree Element: meta (non-standard)
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: Must contain a flat field list.
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.
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::
.. meta::
:description: The reStructuredText plaintext markup language
:keywords: plaintext, markup language
This would be converted to the following HTML::
<meta name="description"
content="The reStructuredText plaintext markup language">
<meta name="keywords" content="plaintext, markup language">
Support for other META attributes ("http-equiv", "scheme", "lang",
"dir") are provided through field arguments, which must be of the form
"attr=value"::
.. meta::
:description lang=en: An amusing story
:description lang=fr: Un histoire amusant
And their HTML equivalents::
<meta name="description" lang="en" content="An amusing story">
<meta name="description" lang="fr" content="Un histoire amusant">
Some META tags use an "http-equiv" attribute instead of the "name"
attribute. To specify "http-equiv" META tags, simply omit the name::
.. meta::
:http-equiv=Content-Type: text/html; charset=ISO-8859-1
HTML equivalent::
<meta http-equiv="Content-Type"
content="text/html; charset=ISO-8859-1">
Imagemap
========
**NOT IMPLEMENTED YET**
Non-standard element: imagemap.
-----------------------------------------
Directives for Substitution Definitions
-----------------------------------------
The directives in this section may only be used in substitution
definitions. They may not be used directly, in standalone context.
The `image`_ directive may be used both in substitution definitions
and in the standalone context.
.. _replace:
Replacement Text
================
:Directive Type: "replace"
:Doctree Element: Text & inline elements
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: A single paragraph; may contain inline markup.
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::
.. |reST| replace:: reStructuredText
Yes, |reST| is a long word, so I can't blame anyone for wanting to
abbreviate it.
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::
I recommend you try |Python|_.
.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
.. _unicode:
Unicode Character Codes
=======================
:Directive Type: "unicode"
:Doctree Element: Text
:Directive Arguments: One or more, required (Unicode character codes,
optional text, and comments).
:Directive Options: Possible.
:Directive Content: None.
The "unicode" directive converts Unicode character codes (numerical
values) to characters, and may be used in substitution definitions
only.
The arguments, separated by spaces, can be:
* **character codes** as
- decimal numbers or
- hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``,
``u``, or ``\u`` or as XML-style hexadecimal character entities,
e.g. ``ᨫ``
* **text**, which is used as-is.
Text following " .. " is a comment and is ignored. The spaces between
the arguments are ignored and thus do not appear in the output.
Hexadecimal codes are case-insensitive.
For example, the following text::
Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
all rights reserved.
.. |copy| unicode:: 0xA9 .. copyright sign
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
.. with trademark sign
.. |---| unicode:: U+02014 .. em dash
:trim:
results in:
Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
all rights reserved.
.. |copy| unicode:: 0xA9 .. copyright sign
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
.. with trademark sign
.. |---| unicode:: U+02014 .. em dash
:trim:
The following options are recognized:
``ltrim`` : flag
Whitespace to the left of the substitution reference is removed.
``rtrim`` : flag
Whitespace to the right of the substitution reference is removed.
``trim`` : flag
Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
of the substitution reference is removed.
-----------------------
Executable Directives
-----------------------
The directives in this section are specific to the trip implementation
of the reStructuredText parser. All of the directives in this section
involve executing code. To prevent an unknown document from running
malicious code, all of these directives will return an error and not
run the code unless trip is invoked with the define ``-D trusted``.
All these directives are implemented externally in the ``Directive``
subdirectory of the bin directory where ``trip`` is installed. To
disable them permanently, simply remove or rename the ``Directive``
subdirectory.
If
==
:Directive Type: "if"
:Doctree Elements: depend on data being included
:Directive Arguments: One, required.
:Directive Options: None.
:Directive Content: Required.
The "if" directive executes its argument as a Perl expression. If the
Perl expression evaluates to true, then the directive's content is
parsed as reStructuredText input and included in the document. If the
Perl expression evaluates to false, then the content of the directive
is omitted. This behavior can be useful for putting comments in a
reStructuredText document that should not be propagated to the output
as comments.
The "if" directive defines the following global variables:
``$SOURCE``
The name of the source file containing the perl directive.
``$LINENO``
The line number of the perl directive within ``$SOURCE``.
``TOP_FILE``
The top-level file being processed.
``@INCLUDES``
Array of reference to array of [file name, line number] pairs that
have included the current file.
``$opt_<x>`` or ``$opt{x}``
The ``<x>`` option from the command line.
The "if" directive processes the following define:
-D perl='perl-code'
Specifies some perl code that is executed prior
to evaluating the first perl directive. This
option can be used to specify variables on the
command line; for example::
-D perl='$a=1; $b=2'
defines constants ``$a`` and ``$b`` that can
be used in the perl expression.
Perl
====
:Directive Type: "perl"
:Doctree Elements: depend on data being included
:Directive Arguments: Possible
:Directive Options: Possible.
:Directive Content: Possible.
The "perl" directive executes perl code and interpolates whatever is
returned by the execution. The perl code can be placed either in
the arguments or the contents section (or both).
The "perl" directive defines the following global variables:
``$SOURCE``
The name of the source file containing the perl directive.
``$LINENO``
The line number of the perl directive within ``$SOURCE``.
``$DIRECTIVE``
The literal text of the perl directive.
``$SUBSTITUTION``
The name of a substitution definition being defined by the perl
directive, or undefined if not within a substitution definition
``@INCLUDES``
Array of reference to array of [file name, line number] pairs that
have included the current file.
``$opt_<x>`` or ``$opt{x}``
The ``<x>`` option from the command line. Changing one of these
variables has no effect upon the parser. However, you can
effectively set the ``-D x=y`` option, possibly affecting
subsequent parsing, by assigning ``y`` to ``$PARSER->{opt}{D}{x}``.
``$PARSER``
The Text::Restructured parser object to allow text parsing within a
perl directive.
``$TOP_FILE``
The top-level file being processed.
``$VERSION``
The version of prest.
The following defines are processed by the "perl" directive:
-D perl='perl-code'
Specifies some perl code that is executed prior
to evaluating the first perl directive. This
option can be used to specify variables on the
command line; for example::
-D perl='$a=1; $b=2'
defines constants ``$a`` and ``$b`` that can
be used in a perl block.
The following options are recognized:
``file`` : string
Uses the text from the file represented by the string. Both
arguments and contents must be empty if :file: is used.
``literal`` : flag (empty)
The entire returned text is inserted into the document as a single
literal block (useful for debugging).
If this option is not present, the return value is interpreted
based on its type. If you return a text string, the text is
interpreted as reStructuredText and is parsed again. If you
return an internal DOM object (or list of them), the object is
included directly into the parsed DOM structure. (This latter
option requires knowledge of trip internals, but is the only way
to create a pending DOM object for execution at transformation
time rather than parse time.)
``lenient`` : flag (empty)
Any errors encountered are returned as text instead of causing a
system message to be generated.
System
======
:Directive Type: "system"
:Doctree Elements: depend on data being included
:Directive Arguments: Required
:Directive Options: Possible.
:Directive Content: None.
The "system" directive executes its arguments as a system (shell)
command and interpolates whatever is returned by the execution.
The following options are recognized:
``literal`` : flag (empty)
The entire returned text is inserted into the document as a single
literal block (useful for debugging).
``lenient`` : flag (empty)
Any errors encountered are returned as text instead of causing a
system message to be generated.
---------------
Miscellaneous
---------------
.. _include:
Including an External Document Fragment
=======================================
:Directive Type: "include"
:Doctree Elements: depend on data being included
:Directive Arguments: One, required (path to the file to include).
:Directive Options: Possible.
:Directive Content: None.
.. WARNING::
The "include" directive represents a potential security hole. It
can be disabled with the "file_insertion_enabled_" runtime setting.
.. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
The "include" directive reads a reStructuredText-formatted text file
and parses it in the current document's context at the point of the
directive. The directive argument is the path to the file to be
included, relative to the document containing the directive. For
example::
This first example will be parsed at the document level, and can
thus contain any construct, including section headers.
.. include:: inclusion.txt
Back in the main document.
This second example will be parsed in a block quote context.
Therefore it may only contain body elements. It may not
contain section headers.
.. include:: inclusion.txt
If an included document fragment contains section structure, the title
adornments must match those of the master document.
The following options are recognized:
``literal`` : flag (empty)
The entire included text is inserted into the document as a single
literal block (useful for program listings).
``encoding`` : name of text encoding
The text encoding of the external data file. Defaults to the
document's encoding (if specified).
.. _code-block:
Including a Marked-Up Code Block
================================
:Directive Type: "code-block"
:Doctree Elements: literal-block or parsed-literal
:Directive Arguments: One, optional (source language of the code block).
:Directive Options: Possible.
:Directive Content: Possible.
The "code-block" directive formats a block of text as a code block.
This directive depends upon the availability of the "states" program,
part of the Unix "enscript" suite, to mark up the code; otherwise the
code block will be returned as a simple literal block. The argument
is optional and specifies the source language of the code block. If the code
block is read from a file, the language will usually default
correctly. The following language specifications are recognized:
ada asm awk c changelog cpp elisp fortran generic haskell html idl
java javascript mail makefile nroff objc pascal perl postscript
python scheme sh states synopsys tcl vba verilog vhdl
The ``generic`` specification has markup that defaults to nothing, but
is controllable using the ``:states-flags:`` option.
The following options are recognized:
``:file: <filename>``
Reads the code sample from a file rather than using the content block.
``:class: <name>``
Associates the name as a class of the code block.
``:color:``
Specifies that "color" markup should be done. What this actually
means is that the following interpreted-text roles are used for
parts of the code markup:
=============== ================
comment A comment in the language
function-name A function name
variable-name A variable name
keyword A reserved keyword
reference-name A reference name
string A quoted string
builtin Variable names built into language
type-name Names associated with the language's type system
=============== ================
If any of these roles is undefined before processing the macro, a
null (``inline``) definition is entered for them.
``:level: <level>``
The level of markup. ``<level>`` can be one of ``none``, ``light``,
or ``heavy`` (default ``heavy``). Ignored if ``:color:`` is specified.
``:numbered:``
Number the lines of the code block.
``:states-file:``
Specifies the name of a non-standard formatting file to be used by
the ``states`` program in doing markup. If specified, overrides the
value of the ``-D code-block-states-file`` command-line option.
``:states-flags:``
Specifies a set of additional flags to be passed to the ``states``
program when doing markup. If specified, overrides the value of the
``-D code-block-states-flags`` command-line option.
.. _raw:
Raw Data Pass-Through
=====================
:Directive Type: "raw"
:Doctree Element: raw
:Directive Arguments: One or more, required (output format types).
:Directive Options: Possible.
:Directive Content: Stored verbatim, uninterpreted. None (empty) if a
"file" or "url" option given.
.. WARNING::
The "raw" directive represents a potential security hole. It can
be disabled with the "raw_enabled" or "file_insertion_enabled"
runtime settings.
.. Caution::
The "raw" directive is a stop-gap measure allowing the author to
bypass reStructuredText's markup. It is a "power-user" feature
that should not be overused or abused. The use of "raw" ties
documents to specific output formats and makes them less portable.
If you often need to use the "raw" directive or a "raw"-derived
interpreted text role, that is a sign either of overuse/abuse or
that functionality may be missing from reStructuredText. Please
describe your situation in a message to the Docutils-users_ mailing
list.
.. _Docutils-users: ../../user/mailing-lists.html#docutils-users
The "raw" directive indicates non-reStructuredText data that is to be
passed untouched to the Writer. The names of the output formats are
given in the directive arguments. The interpretation of the raw data
is up to the Writer. A Writer may ignore any raw output not matching
its format.
For example, the following input would be passed untouched by an HTML
Writer::
.. raw:: html
<hr width=50 size=10>
A LaTeX Writer could insert the following raw content into its
output stream::
.. raw:: latex
\setlength{\parindent}{0pt}
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::
.. raw:: html
:file: inclusion.html
The following options are recognized:
``file`` : string (newlines removed)
The local filesystem path of a raw data file to be included.
``url`` : string (whitespace removed)
An Internet URL reference to a raw data file to be included.
``encoding`` : name of text encoding
The text encoding of the external raw data (file or URL).
Defaults to the document's encoding (if specified).
``head`` : flag (empty)
The raw text gets put into the head material of the document rather
than the body (if applicable).
.. _classes:
Class
=====
:Directive Type: "class"
:Doctree Element: pending
:Directive Arguments: One or more, required (class names / attribute
values).
:Directive Options: Possible.
:Directive Content: None.
The "class" directive sets the "classes" attribute value on
the first immediately following non-comment element [#]_. For
details of the "classes" attribute, see `its entry`__ in `The Docutils
Document Tree`_. The directive argument consists of one or more
space-separated class names, which are converted to lowercase and all
non-alphanumeric characters are converted to hyphens. (For the
rationale, see below.)
__ ../doctree.html#classes
Examples::
.. class:: special
This is a "special" paragraph.
.. class:: exceptional remarkable
An Exceptional Section
======================
This is an ordinary paragraph.
The text above is parsed and transformed into this doctree fragment::
<paragraph classes="special">
This is a "special" paragraph.
<section classes="exceptional remarkable">
<title>
An Exceptional Section
<paragraph>
This is an ordinary paragraph.
.. [#] To set a "classes" attribute value on a block quote, the
"class" directive must be followed by an empty comment::
.. class:: highlights
..
Block quote text.
The directive doesn't allow content, therefore an empty comment is
required to terminate the directive. Without the empty comment,
the block quote text would be interpreted as the "class"
directive's content, and the parser would complain.
The following options are recognized:
``parent`` : parent selector
Attach the class to a containing element rather than the next
element. The parent selector is an optional space-separated list
of parent elements. Each element is either a number, which
indicates how many levels to go up, or the name of an element.
For example, "entry" would attach the class to the first
containing table entry, and "row 2" would attach the class to
whatever is two levels above the first containing table row. The
default parent selector is "1".
.. topic:: Rationale for "classes" Attribute Value Conversion
Docutils identifiers are converted to conform to the regular
expression ``[a-z](-?[a-z0-9]+)*``. For CSS compatibility,
identifiers (the "classes" and "id" attributes) should have no
underscores, colons, or periods. Hyphens may be used.
- The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
ID and NAME tokens must begin with a letter ([A-Za-z]) and
may be followed by any number of letters, digits ([0-9]),
hyphens ("-"), underscores ("_"), colons (":"), and periods
(".").
- However the `CSS1 spec`_ defines identifiers based on the "name"
token, a tighter interpretation ("flex" tokenizer notation
below; "latin1" and "escape" 8-bit characters have been replaced
with entities)::
unicode \\[0-9a-f]{1,4}
latin1 [¡-ÿ]
escape {unicode}|\\[ -~¡-ÿ]
nmchar [-a-z0-9]|{latin1}|{escape}
name {nmchar}+
The CSS1 "nmchar" rule does not include underscores ("_"), colons
(":"), or periods ("."), therefore "classes" and "id" attributes
should not contain these characters. They should be replaced with
hyphens ("-"). Combined with HTML's requirements (the first
character must be a letter; no "unicode", "latin1", or "escape"
characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern.
.. _HTML 4.01 spec: http://www.w3.org/TR/html401/
.. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
.. _role:
Custom Interpreted Text Roles
=============================
:Directive Type: "role"
:Doctree Element: None; affects subsequent parsing.
:Directive Arguments: Two; one required (new role name), one optional
(base role name, in parentheses).
:Directive Options: Possible (depends on base role).
:Directive Content: depends on base role.
(New in Docutils 0.3.2)
The "role" directive dynamically creates a custom interpreted text
role and registers it with the parser. This means that after
declaring a role like this::
.. role:: custom
the document may use the new "custom" role::
An example of using :custom:`interpreted text`
This will be parsed into the following document tree fragment::
<paragraph>
An example of using
<inline classes="custom">
interpreted text
The role must be declared in a document before it can be used.
The new role may be based on an existing role, specified as a second
argument in parentheses (whitespace optional)::
.. role:: custom(emphasis)
:custom:`text`
The parsed result is as follows::
<paragraph>
<emphasis classes="custom">
text
If no base role is explicitly specified, a generic custom role is
automatically used. Subsequent interpreted text will produce an
"inline" element with a "classes" attribute, as in the first example
above.
With most roles, the ":class:" option can be used to set a "classes"
attribute that is different from the role name. For example::
.. role:: custom
:class: special
:custom:`interpreted text`
This is the parsed result::
<paragraph>
<inline classes="special">
interpreted text
.. _role class:
The following options are recognized by the "role" directive for most
base roles:
``class`` : text
Set a "class" attribute value on the element produced (``inline``,
or element associated with a base class) when the custom
interpreted text role is used. If no directive options are
specified, a "class" option with the directive argument (role
name) as the value is implied. See the class_ directive above.
``prefix`` : field list text
Specifies raw text that will be prepended to the interpreted text
depending upon the output format. A field name is the output
format (writer) name and its field value is the raw text to
be prepended for that format. A field name of ``default`` can be
used to specify text to prepend if the output format matches no other
field name.
``suffix`` : field list text
Specifies raw text that will be appended to the interpreted text
depending upon the output format. A field name is the output
format (writer) name and its field value is the raw text that will
be appended for that format. A field name of ``default`` can be
used to specify text to append if the output format matches no other
field name.
For example, red text could be accomplished in html and latex by saying::
.. role:: red
:prefix:
:html: <font color="red">
:latex: {\color{red}
:suffix:
:html: </font>
:latex: }
This text has a :red:`red` word in it.
Specific roles may support other options and/or directive content.
See the `reStructuredText Interpreted Text Roles`_ document for
details.
.. _reStructuredText Interpreted Text Roles: roles.html
.. _default-role:
Setting the Default Interpreted Text Role
=========================================
:Directive Type: "default-role"
:Doctree Element: None; affects subsequent parsing.
:Directive Arguments: One, optional (new default role name).
:Directive Options: None.
:Directive Content: None.
(New in Docutils 0.3.10)
The "default-role" directive sets the default interpreted text role,
the role that is used for interpreted text without an explicit role.
For example, after setting the default role like this::
.. default-role:: subscript
any subsequent use of implicit-role interpreted text in the document
will use the "subscript" role::
An example of a `default` role.
This will be parsed into the following document tree fragment::
<paragraph>
An example of a
<subscript>
default
role.
Custom roles may be used (see the "role_" directive above), but it
must have been declared in a document before it can be set as the
default role. See the `reStructuredText Interpreted Text Roles`_
document for details of built-in roles.
The directive may be used without an argument to restore the initial
default interpreted text role, which is application-dependent. The
initial default interpreted text role of the standard reStructuredText
parser is "title-reference".
.. _title:
Metadata Document Title
=======================
:Directive Type: "title"
:Doctree Element: None.
:Directive Arguments: 1, required (the title text).
:Directive Options: None.
:Directive Content: None.
The "title" directive specifies the document title as metadata, which
does not become part of the document body. It overrides a
document-supplied title. For example, in HTML output the metadata
document title appears in the title bar of the browser window.
Restructuredtext-Test-Directive
===============================
:Directive Type: "restructuredtext-test-directive"
:Doctree Element: system_warning
:Directive Arguments: None.
:Directive Options: None.
:Directive Content: Interpreted as a literal block.
This directive is provided for test purposes only. (Nobody is
expected to type in a name *that* 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.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: