Now, or yesterday. Or maybe even before yesterday.
Status:
This is a "work in progress"
Revision:
is managed by a version control system.
Version:
1
Copyright:
This document has been placed in the public domain. You
may do with it as you wish. You may copy, modify,
redistribute, reattribute, sell, buy, rent, lease,
destroy, or improve it, quote it at length, excerpt,
incorporate, collate, fold, staple, or mutilate it, or do
anything else to it that your or anyone else's heart
desires.
field name:
This is a "generic bibliographic field".
field name "2":
Generic bibliographic fields may contain multiple body elements.
Like this.
Dedication
For Docutils users & co-developers.
Abstract
This is a test document, containing at least one example of each
reStructuredText construct.
Lone subsections are converted to a section subtitle by a transform
activated with the --section-subtitles command line option or the
sectsubtitle-xform configuration value.
Paragraphs contain text and may contain inline markup: emphasis,
strong emphasis, inline literals, standalone hyperlinks
(http://www.python.org), external hyperlinks (Python[7]), internal
cross-references (example), external hyperlinks with embedded URIs
(Python web site), anonymous hyperlink
references[7] (a second reference[14]), footnote references (manually
numbered [1], anonymous auto-numbered [3], labeled auto-numbered
[2], or symbolic [*]), citation references (see [CIT2002]),
substitution references ( &
a trimmed heart(U+2665):♥), and inline hyperlink targets
(see Targets below for a reference back to here). Character-level
inline markup is also possible (although exceedingly ugly!) in reStructuredText. Problems are indicated by |problematic| text
(generated by processing errors; this one is intentional). Here is a
reference to the doctitle and the subtitle.
The default role for interpreted text is Title Reference. Here are
some explicit interpreted text roles: a PEP reference (PEP 287); an
RFC reference (RFC 2822); an abbreviation (abb.), an acronym
(reST), code (print "hello world"); a subscript;
a superscript and explicit roles for Docutils'
standardinlinemarkup.
Let's test wrapping and whitespace significance in inline literals:
This is an example of --inline-literal--text,--includingsome--strangely--hyphenated-words.Adjust-the-width-of-your-browser-window to see how the text is wrapped. -------------- Now note the spacing between the words of this sentence (words should be grouped in pairs).
If the --pep-references option was supplied, there should be a
live link to PEP 258 here.
Field lists map field names to field bodies, like database
records. They are often part of an extension syntax. They are
an unambiguous variant of RFC 2822 fields.
how arg1 arg2:
The field marker is a colon, the field name, and a colon.
The field body may contain one or more body elements, indented
relative to the field marker.
credits:
This paragraph has the credits class set. (This is actually not
about credits but just for ensuring that the class attribute
doesn't get stripped away.)
My theory by A. Elk. Brackets Miss, brackets. This theory goes
as follows and begins now. All brontosauruses are thin at one
end, much much thicker in the middle and then thin again at the
far end. That is my theory, it is mine, and belongs to me and I
own it, and what it is too.
—Anne Elk (Miss)
The language of a quote (like any other object) can be specified by
a class attribute:
ReStructuredText est un langage de balisage léger utilisé
notamment dans la documentation du langage Python.
>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)
This paragraph is pointed to by the explicit "example" target. A
reference can be found under Inline Markup, above. Inline
hyperlink targets are also possible.
Section headers are implicit targets, referred to by name. See
Targets, which is a subsection of Body Elements.
Explicit external targets are interpolated into references such as
"Python[7]".
Targets may be indirect and anonymous. Thus this phrase may also
refer to the Targets section.
Duplicate names in section headers or other implicit targets will
generate "info" (level-1) system messages. Duplicate names in
explicit targets will generate "warning" (level-2) system messages.
Since there are two "Duplicate Target Names" section headers, we
cannot uniquely refer to either of them by name. If we try to (like
this: `Duplicate Target Names`_), an error is generated.
An example of the "contents" directive can be seen above this section
(a local, untitled table of contents) and at the beginning of the
document (a document-wide table of contents).
Relative units allow adaption of the image to the screen or paper size.
An image occupying 50% of the line width:
A figure is an image with a caption and/or a legend. With page-based output
media, figures might float to a different position if this helps the page
layout.
Plaintext markup syntax and parser system.
re
Revised, revisited, based on 're' module.
Structured
Structure-enhanced text, structuredtext.
Text
Well it is, isn't it?
This paragraph is also part of the legend.
A left-aligned figure, 70% wide:
This paragraph might flow around the figure.
The specific behavior depends upon the style sheet and the browser or
rendering software used.
A centred figure, 40% wide:
This paragraph might flow around the figure.
The specific behavior depends upon the style sheet and the browser or
rendering software used.
A right-aligned figure:
This paragraph might flow around the figure. The specific behavior depends
upon the style sheet and the browser or rendering software used.
Tables may be given titles and additional arguments with the table
directive:
left-aligned table
A
not A
False
True
True
False
center-aligned table
A
not A
False
True
True
False
right-aligned table
A
not A
False
True
True
False
With the "widths" argument "auto" (or "class" value "colwidths-auto"),
column widths are determined by the backend (if supported by the
writer/backend).
The compound directive is used to create a "compound paragraph", which
is a single logical paragraph containing multiple physical body
elements. For example:
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.
Test the handling and display of compound paragraphs:
Compound 2, paragraph 1,
compound 2, paragraph 2,
list item 1,
list item 2,
compound 2, paragraph 3.
Compound 3, only consisting of one paragraph.
Compound 4.
This one starts with a literal block.
Compound 4, paragraph following the literal block.
Now something really perverted -- a nested compound block. This is
just to test that it works at all; the results don't have to be
meaningful.
Compound 5, block 1 (a paragraph).
Compound 6 is block 2 in compound 5.
Compound 6, another paragraph.
Compound 5, block 3 (a paragraph).
Compound 7, tests the inclusion of various block-level
elements in one logical paragraph. First a table,
Left cell, first
paragraph.
Left cell, second
paragraph.
Middle cell,
consisting of
exactly one
paragraph.
Right cell.
Paragraph 2.
Paragraph 3.
followed by a paragraph. This physical paragraph is
actually a continuation of the paragraph before the table. It is followed
by
This is a parsed literal block.
This line is indented. The next line is blank.
Inline markup is supported, e.g. emphasis, strong, literal
text, sub- and superscripts,
inline formulas: A = 2πr2,
footnotes [1], hyperlink targets, and references.
Blocks of source code can be set with the code directive. If the code
language is specified, the content is parsed and tagged by the Pygments[8]
syntax highlighter and can be formatted with a style sheet. (Code parsing
is turned off using the syntax-highlight config setting in the test
conversions in order to get identical results with/without installed
Pygments highlighter.)
print 'This is Python code.'
The :number-lines: option (with optional start value) generates line
numbers:
8 # print integers from 0 to 9:
9 for i in range(10):
10 print i
For inline code snippets, there is the code role, which can be used
directly (the code will not be parsed/tagged, as the language is not known)
or as base for special code roles, e.g. the LaTeX code in the next
paragraph.
Docutils uses LaTeX syntax for math directives and roles:
\alpha = f(x) prints α = f(x).
The :code: option of the include directive sets the included content
as a code block, here the rst file header_footer.txt with line numbers:
Use only meta keywords recognized by HTML 5.
Add HTML5-compatible meta tags for docinfo items
"authors", "date", and "copyright".
Add a viewport meta tag[17] to tell mobile browsers
to use the device-width as viewport.
Set table column widths with <style="width: ...">, not "width" argument.
Horizontal alignment of table heads with CSS.
Do not drop paragraph objects, use CSS rules to prevent unwanted vertical
space.
Put subtitles in <p> elements.
Use the new semantic tags <main>, <section>, <header>,
<footer>, <aside>, <figure>, and <figcaption>.
See minimal.css and responsive.css for styling rule examples.
Use HTML5 tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
<i>, <b>, <u>, <mark>, and <bdi> if a matching class value
is found in inline and literal elements.
Use <ins> and <del> if a matching class value
is found in inline, literal, or container elements.
(See text-level semantics and indicating edits.)
Use <img> tags for SVG images and <video> for video formats.
Embed images or defer fetching images with the image-loading[9]
configuration setting or the "loading" option of the "image" directive.
Especially with "lazy" loading, it is strongly recommended to
specify both width and height of the image to prevent content layout
shifts or use the "scale" option to let the writer insert the size
determined from the image file.
A field list is converted to a HTML definition list and given the
field-list class argument value to allow CSS styling.
With html_plain.css, the layout is similar to html4css1:
A long field name:
sticks into the field body.
The field body is pushed to the next line (you can suppress this
behaviour with the run-in class argument).
Customization:
of the field name width is possible with CSS instead
of the field-name-limit configuration setting, for
example:
dl.field-list > dd { margin-left: 6em; }
Empty:
fields:
must not lead to misalignment of the following content.
For field lists, the "compact/open", "narrow" and "run-in" styles are defined
in the style sheets plain.css and responsive.css.
compact
Feature:
No additional space between list items.
Option:
The --compact-field-lists command line option (and the
corresponding configuration setting) set the compact
class argument on all "simple" field lists, if not
overridden with open.
Use:
For lists with short field body.
open
Feature:
Additional space between list items also in "simple" lists.
(Overrides the --compact-field-lists command line
option and the corresponding configuration setting)
Use:
For "simple" lists that should keep the space between list items.
narrow
Feature:
Less indented field body.
Use:
For lists with short field names.
A long field name:
sticks into the field body and the field body starts on a
new line (if not combined with run-in).
custom field-indent
Feature:
Field body indented by custom amount.
Use:
class value starting with field-indent- followed by
a valid length, e.g. field-indent-3em.
The writer:
will convert this class value to a style attribute setting.
run-in
Feature:
Field body starts on the same line also after long field
names.
A long field name:
sticks into the field body which continues on
the same line.
The next field name:
and field body should align. Long text in the field
body is wrapped and aligns with other fields.
The following styles can be applied to individual tables via a class
argument or as document wide setting with the table-style[11] configuration
setting (or command line argument).
Numbered tables can be achieved with the "numbered" class option:
truth values
A
B
A or B
False
False
False
True
False
True
False
True
True
True
True
True
Currently, referencing to the table by number is not supported. This is a
common request and already on the TODO list.
A table with "booktabs" class value, is rendered similar to the style
from the booktabs[12] LaTeX package.
"Booktabs" style table, numbered, centre-aligned, with auto-sized columns:
Organic food in Ireland is certified by the IOFGA [‡]
In rST there are separate roles for abbreviations rsp.
acronymes. In HTML, the <acronym> tag is obsolete and authors are
advised to use <abbr> instead. The HTML5 writer uses <abbr> for Docutil's
<abbreviation> element.
ruby, rt, rp
Ruby annotations
Require inline nesting, currently not supported in rST.
Scalable vector graphics (SVG) images are the only standards-compatible
way to include vector graphics in HTML documents. However, they are not
supported by all backends/output formats (LaTeX, e.g., supports the PDF
or Postscript formats for vector graphics instead). Rendering behaviour
varies, depending on the SVG image itself, the method used to put the
image in the document, and the viewing agent.
All up-to-date HTML browsers support SVG, however not all do this fully
and in the same manner. Some older browsers, especially IE < 9, have
deficiencies or require plug-ins (i.e. don't support the <img> tag).
Older versions of webkit based browsers (chromium, safari, midori,
konqueror) support the <img> tag but don't display contained bitmap
images.
The "html4css1" writer includes SVG images as <object> elements,
the "html5" writer uses <svg> for embedded images and <img>
else. The element type influences several aspects of image behaviour:
Due to security/privacy considerations, browsers may block <object>
data from 3rd party sources.
If an image is included as <object> or <svg>,
it depends on the viewBox declaration of the root <svg> element
whether it is scaled or clipped/padded.
Images in <img> elements are always scaled.
Image with viewBox, 1.2 em high, left aligned and inline.
Image with viewBox, 5 mm x 15 mm.
Image without viewBox, 5 mm x 15 mm.
Image with embedded bitmap and viewBox, 2 em wide.
Image with embedded bitmap without viewBox.
SVG images with viewBox keep the aspect ratio unless the
preserveAspectRatio attribute is "none".
The following two images are 25% wide and 1 em high:
Image with viewBox.
Image without viewBox.
Hyperlinks and script actions attached to SVG elements are ignored in
images included as <img>. Hyperlinks in images included as
<object> are opened in the "object frame". Hyperlinks specified in
the rST source (with the :target: directive option) work in
<img> and <svg> elements but are ignored in images included as
<object> (unless the object is blocked).
Image with a link attached to the upper rectangle;
interactive clock and button aligned to the right.
2.16 Comments
Here's one:
(View the HTML source to see the comment.)