1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <title>Quick reStructuredText
</title>
7 <meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8">
9 <style type=
"text/css"><!--
10 a
.backref
{ text-decoration: none
; color: black
}
11 div
.line-block
{ display: block
}
12 div
.line-block div
.line-block
{ margin-left: 1.5em }
18 <h1>Quick
<i>re
</i><font size=
"+4"><tt>Structured
</tt></font><i>Text
</i></h1>
20 <!-- Caveat: if you're reading the HTML for the examples, -->
21 <!-- beware that it was hand-generated, not by Docutils/ReST. -->
23 <p align=
"right"><em><a href=
"http://docutils.sourceforge.net/docs/user/rst/quickref.html"
24 >http://docutils.sourceforge.net/docs/user/rst/quickref.html
</a></em>
25 <br><em>Being a cheat-sheet for reStructuredText
</em>
26 <br><em>Updated $Date$
</em>
29 <p>Copyright: This document has been placed in the public domain.
33 <p>The full details of the markup may be found on the
34 <a href=
"http://docutils.sourceforge.net/rst.html">reStructuredText
</a>
35 page. This document is just intended as a reminder.
37 <p>Links that look like
"(<a href="#details
">details</a>)" point
38 into the HTML version of the full
<a
39 href=
"../../ref/rst/restructuredtext.html">reStructuredText
40 specification
</a> document. These are relative links; if they
41 don't work, please use the
<a
42 href=
"http://docutils.sourceforge.net/docs/user/rst/quickref.html"
43 >master
"Quick reStructuredText"</a> document.
45 <h2><a name=
"contents">Contents
</a></h2>
48 <li><a href=
"#inline-markup">Inline Markup
</a></li>
49 <li><a href=
"#escaping">Escaping with Backslashes
</a></li>
50 <li><a href=
"#section-structure">Section Structure
</a></li>
51 <li><a href=
"#paragraphs">Paragraphs
</a></li>
52 <li><a href=
"#bullet-lists">Bullet Lists
</a></li>
53 <li><a href=
"#enumerated-lists">Enumerated Lists
</a></li>
54 <li><a href=
"#definition-lists">Definition Lists
</a></li>
55 <li><a href=
"#field-lists">Field Lists
</a></li>
56 <li><a href=
"#option-lists">Option Lists
</a></li>
57 <li><a href=
"#literal-blocks">Literal Blocks
</a></li>
58 <li><a href=
"#line-blocks">Line Blocks
</a></li>
59 <li><a href=
"#block-quotes">Block Quotes
</a></li>
60 <li><a href=
"#doctest-blocks">Doctest Blocks
</a></li>
61 <li><a href=
"#tables">Tables
</a></li>
62 <li><a href=
"#transitions">Transitions
</a></li>
63 <li><a href=
"#explicit-markup">Explicit Markup
</a>
65 <li><a href=
"#footnotes">Footnotes
</a></li>
66 <li><a href=
"#citations">Citations
</a></li>
67 <li><a href=
"#hyperlink-targets">Hyperlink Targets
</a>
69 <li><a href=
"#external-hyperlink-targets">External Hyperlink Targets
</a></li>
70 <li><a href=
"#internal-hyperlink-targets">Internal Hyperlink Targets
</a></li>
71 <li><a href=
"#indirect-hyperlink-targets">Indirect Hyperlink Targets
</a></li>
72 <li><a href=
"#implicit-hyperlink-targets">Implicit Hyperlink Targets
</a></li>
74 <li><a href=
"#directives">Directives
</a></li>
75 <li><a href=
"#substitution-references-and-definitions">Substitution References and Definitions
</a></li>
76 <li><a href=
"#comments">Comments
</a></li>
78 <li><a href=
"#getting-help">Getting Help
</a></li>
81 <h2><a href=
"#contents" name=
"inline-markup" class=
"backref"
82 >Inline Markup
</a></h2>
84 <p>(
<a href=
"../../ref/rst/restructuredtext.html#inline-markup">details
</a>)
86 <p>Inline markup allows words and phrases within text to have
87 character styles (like italics and boldface) and functionality
90 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
92 <tr align=
"left" bgcolor=
"#99CCFF">
99 <td nowrap
><samp>*emphasis*
</samp>
100 <td><em>emphasis
</em>
101 <td>Normally rendered as italics.
104 <td nowrap
><samp>**strong
emphasis**
</samp>
105 <td><strong>strong emphasis
</strong>
106 <td>Normally rendered as boldface.
109 <td nowrap
><samp>`interpreted
text`
</samp>
110 <td>(see note at right)
111 <td>The rendering and
<em>meaning
</em> of interpreted text is
112 domain- or application-dependent. It can be used for things
113 like index entries or explicit descriptive markup (like program
117 <td nowrap
><samp>``inline
literal``
</samp>
118 <td><code>inline
literal
</code>
119 <td>Normally rendered as monospaced text. Spaces should be
120 preserved, but line breaks will not be.
123 <td nowrap
><samp>reference_
</samp>
124 <td><a href=
"#hyperlink-targets">reference
</a>
125 <td>A simple, one-word hyperlink reference. See
<a
126 href=
"#hyperlink-targets">Hyperlink Targets
</a>.
129 <td nowrap
><samp>`phrase reference`_
</samp>
130 <td><a href=
"#hyperlink-targets">phrase reference
</a>
131 <td>A hyperlink reference with spaces or punctuation needs to be
132 quoted with backquotes. See
<a
133 href=
"#hyperlink-targets">Hyperlink Targets
</a>.
136 <td nowrap
><samp>anonymous__
</samp>
137 <td><a href=
"#hyperlink-targets">anonymous
</a>
138 <td>With two underscores instead of one, both simple and phrase
139 references may be anonymous (the reference text is not repeated
140 at the target). See
<a
141 href=
"#hyperlink-targets">Hyperlink Targets
</a>.
144 <td nowrap
><samp>_`inline internal target`
</samp>
145 <td><a name=
"inline-internal-target">inline internal target
</a>
146 <td>A crossreference target within text.
147 See
<a href=
"#hyperlink-targets">Hyperlink Targets
</a>.
150 <td nowrap
><samp>|substitution reference|
</samp>
151 <td>(see note at right)
152 <td>The result is substituted in from the
<a
153 href=
"#substitution-references-and-definitions">substitution
154 definition
</a>. It could be text, an image, a hyperlink, or a
155 combination of these and others.
158 <td nowrap
><samp>footnote reference [
1]_
</samp>
159 <td>footnote reference
<sup><a href=
"#footnotes">1</a></sup>
160 <td>See
<a href=
"#footnotes">Footnotes
</a>.
163 <td nowrap
><samp>citation reference [CIT2002]_
</samp>
164 <td>citation reference
<a href=
"#citations">[CIT2002]
</a>
165 <td>See
<a href=
"#citations">Citations
</a>.
168 <td nowrap
><samp>http://docutils.sf.net/
</samp>
169 <td><a href=
"http://docutils.sf.net/">http://docutils.sf.net/
</a>
170 <td>A standalone hyperlink.
174 <p>Asterisk, backquote, vertical bar, and underscore are inline
175 delimiter characters. Asterisk, backquote, and vertical bar act
176 like quote marks; matching characters surround the marked-up word
177 or phrase, whitespace or other quoting is required outside them,
178 and there can't be whitespace just inside them. If you want to use
179 inline delimiter characters literally,
<a href=
"#escaping">escape
180 (with backslash)
</a> or quote them (with double backquotes; i.e.
181 use inline literals).
183 <p>In detail, the reStructuredText specification says that in
184 inline markup, the following rules apply to start-strings and
185 end-strings (inline markup delimiters):
188 <li>The start-string must start a text block or be
189 immediately preceded by whitespace or any of
190 <samp>'
" ( [ {</samp> or <samp><</samp>.
191 <li>The start-string must be immediately followed by non-whitespace.
192 <li>The end-string must be immediately preceded by non-whitespace.
193 <li>The end-string must end a text block (end of document or
194 followed by a blank line) or be immediately followed by whitespace
195 or any of <samp>' " . , : ; ! ? - ) ] } / \
</samp>
196 or
<samp>></samp>.
197 <li>If a start-string is immediately preceded by one of
198 <samp>'
" ( [ {</samp> or <samp><</samp>, it must not be
199 immediately followed by the corresponding character from
200 <samp>' " ) ] }
</samp> or
<samp>></samp>.
201 <li>An end-string must be separated by at least one
202 character from the start-string.
203 <li>An
<a href=
"#escaping">unescaped
</a> backslash preceding a
204 start-string or end-string will disable markup recognition, except
205 for the end-string of inline literals.
208 <p>Also remember that inline markup may not be nested (well,
209 except that inline literals can contain any of the other inline
210 markup delimiter characters, but that doesn't count because
211 nothing is processed).
213 <h2><a href=
"#contents" name=
"escaping" class=
"backref"
214 >Escaping with Backslashes
</a></h2>
217 href=
"../../ref/rst/restructuredtext.html#escaping-mechanism">details
</a>)
219 <p>reStructuredText uses backslashes (
"\") to override the special
220 meaning given to markup characters and get the literal characters
221 themselves. To get a literal backslash, use an escaped backslash
224 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
226 <tr align=
"left" bgcolor=
"#99CCFF">
227 <th width=
"50%">Raw reStructuredText
228 <th width=
"50%">Typical result
231 <tr valign=
"top"><td>
232 <samp>*escape*
``with``
"\"</samp>
233 <td><em>escape
</em> <samp>with
</samp> ""
234 <tr valign=
"top"><td>
235 <samp>\*escape*
\``with``
"\\"</samp>
236 <td>*escape* ``with``
"\"
239 <p>In Python strings it will, of course, be necessary
240 to escape any backslash characters so that they actually
241 <em>reach
</em> reStructuredText.
242 The simplest way to do this is to use raw strings:
244 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
246 <tr align=
"left" bgcolor=
"#99CCFF">
247 <th width=
"50%">Python string
248 <th width=
"50%">Typical result
251 <tr valign=
"top"><td>
252 <samp>r
"""\*escape* \`with` "\\
""""</samp>
253 <td>*escape* `with`
"\"
254 <tr valign=
"top"><td>
255 <samp> """\\*escape* \\`with` "\\\\
""""</samp>
256 <td>*escape* `with`
"\"
257 <tr valign=
"top"><td>
258 <samp> """\*escape* \`with` "\\
""""</samp>
259 <td><em>escape
</em> with
""
262 <h2><a href=
"#contents" name=
"section-structure" class=
"backref"
263 >Section Structure
</a></h2>
265 <p>(
<a href=
"../../ref/rst/restructuredtext.html#sections">details
</a>)
267 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
269 <tr align=
"left" bgcolor=
"#99CCFF">
270 <th width=
"50%">Plain text
271 <th width=
"50%">Typical result
277 <br><samp>Title
</samp>
278 <br><samp>=====
</samp>
279 <br><samp>Subtitle
</samp>
280 <br><samp>--------
</samp>
281 <br><samp>Titles
are
underlined
(or
over-
</samp>
282 <br><samp>and
underlined)
with
a
printing
</samp>
283 <br><samp>nonalphanumeric
7-bit
ASCII
</samp>
284 <br><samp>character.
Recommended
choices
</samp>
285 <br><samp>are
"``= - ` : ' " ~
^
_
*
+
#
< >``
".</samp>
286 <br><samp>The underline/overline must be at</samp>
287 <br><samp>least as long as the title text.</samp>
289 <br><samp>A lone top-level (sub)section</samp>
290 <br><samp>is lifted up to be the document's</samp>
291 <br><samp>(sub)title.</samp>
294 <font size="+
2"><strong>Title</strong></font>
295 <p><font size="+
1"><strong>Subtitle</strong></font>
296 <p>Titles are underlined (or over-
297 and underlined) with a printing
298 nonalphanumeric 7-bit ASCII
299 character. Recommended choices
300 are "<samp>= - ` : '
" ~ ^ _ * + # < ></samp>".
301 The underline/overline must be at
302 least as long as the title text.
303 <p>A lone top-level (sub)section is
304 lifted up to be the document's
308 <h2><a href=
"#contents" name=
"paragraphs" class=
"backref"
311 <p>(
<a href=
"../../ref/rst/restructuredtext.html#paragraphs">details
</a>)
313 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
315 <tr align=
"left" bgcolor=
"#99CCFF">
316 <th width=
"50%">Plain text
317 <th width=
"50%">Typical result
322 <p><samp>This
is
a
paragraph.
</samp>
324 <p><samp>Paragraphs
line
up
at
their
left
</samp>
325 <br><samp>edges,
and
are
normally
separated
</samp>
326 <br><samp>by
blank
lines.
</samp>
329 <p>This is a paragraph.
331 <p>Paragraphs line up at their left edges, and are normally
332 separated by blank lines.
336 <h2><a href=
"#contents" name=
"bullet-lists" class=
"backref"
337 >Bullet Lists
</a></h2>
339 <p>(
<a href=
"../../ref/rst/restructuredtext.html#bullet-lists">details
</a>)
341 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
343 <tr align=
"left" bgcolor=
"#99CCFF">
344 <th width=
"50%">Plain text
345 <th width=
"50%">Typical result
350 <samp>Bullet
lists:
</samp>
352 <p><samp>-
This
is
item
1</samp>
353 <br><samp>-
This
is
item
2</samp>
355 <p><samp>-
Bullets
are
"-",
"*" or
"+".
</samp>
356 <br><samp> Continuing
text
must
be
aligned
</samp>
357 <br><samp> after
the
bullet
and
whitespace.
</samp>
359 <p><samp>Note
that
a
blank
line
is
required
</samp>
360 <br><samp>before
the
first
item
and
after
the
</samp>
361 <br><samp>last,
but
is
optional
between
items.
</samp>
366 <li>Bullets are
"-",
"*" or
"+".
367 Continuing text must be aligned
368 after the bullet and whitespace.
370 <p>Note that a blank line is required before the first
371 item and after the last, but is optional between items.
374 <h2><a href=
"#contents" name=
"enumerated-lists" class=
"backref"
375 >Enumerated Lists
</a></h2>
377 <p>(
<a href=
"../../ref/rst/restructuredtext.html#enumerated-lists">details
</a>)
379 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
381 <tr align=
"left" bgcolor=
"#99CCFF">
382 <th width=
"50%">Plain text
383 <th width=
"50%">Typical result
388 <samp>Enumerated
lists:
</samp>
390 <p><samp>3.
This
is
the
first
item
</samp>
391 <br><samp>4.
This
is
the
second
item
</samp>
392 <br><samp>5.
Enumerators
are
arabic
numbers,
</samp>
393 <br><samp> single
letters,
or
roman
numerals
</samp>
394 <br><samp>6.
List
items
should
be
sequentially
</samp>
395 <br><samp> numbered,
but
need
not
start
at
1</samp>
396 <br><samp> (although
not
all
formatters
will
</samp>
397 <br><samp> honour
the
first
index).
</samp>
398 <br><samp>#.
This
item
is
auto-enumerated
</samp>
399 <td>Enumerated lists:
401 <li value=
"3">This is the first item
402 <li>This is the second item
403 <li>Enumerators are arabic numbers, single letters,
405 <li>List items should be sequentially numbered,
406 but need not start at
1 (although not all
407 formatters will honour the first index).
408 <li>This item is auto-enumerated
412 <h2><a href=
"#contents" name=
"definition-lists" class=
"backref"
413 >Definition Lists
</a></h2>
415 <p>(
<a href=
"../../ref/rst/restructuredtext.html#definition-lists">details
</a>)
417 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
419 <tr align=
"left" bgcolor=
"#99CCFF">
420 <th width=
"50%">Plain text
421 <th width=
"50%">Typical result
426 <samp>Definition
lists:
</samp>
428 <br><samp>what
</samp>
429 <br><samp> Definition
lists
associate
a
term
with
</samp>
430 <br><samp> a
definition.
</samp>
433 <br><samp> The
term
is
a
one-line
phrase,
and
the
</samp>
434 <br><samp> definition
is
one
or
more
paragraphs
or
</samp>
435 <br><samp> body
elements,
indented
relative
to
the
</samp>
436 <br><samp> term.
Blank
lines
are
not
allowed
</samp>
437 <br><samp> between
term
and
definition.
</samp>
438 <td>Definition lists:
440 <dt><strong>what
</strong>
441 <dd>Definition lists associate a term with
444 <dt><strong>how
</strong>
445 <dd>The term is a one-line phrase, and the
446 definition is one or more paragraphs or
447 body elements, indented relative to the
448 term. Blank lines are not allowed
449 between term and definition.
453 <h2><a href=
"#contents" name=
"field-lists" class=
"backref"
454 >Field Lists
</a></h2>
456 <p>(
<a href=
"../../ref/rst/restructuredtext.html#field-lists">details
</a>)
458 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
460 <tr align=
"left" bgcolor=
"#99CCFF">
461 <th width=
"50%">Plain text
462 <th width=
"50%">Typical result
467 <samp>:Authors:
</samp>
468 <br><samp> Tony
J.
(Tibs)
Ibbs,
</samp>
469 <br><samp> David
Goodger
</samp>
471 <p><samp> (and
sundry
other
good-natured
folks)
</samp>
473 <p><samp>:Version:
1.0 of
2001/
08/
08</samp>
474 <br><samp>:Dedication:
To
my
father.
</samp>
478 <td><strong>Authors:
</strong>
479 <td>Tony J. (Tibs) Ibbs,
481 <tr><td><td>(and sundry other good-natured folks)
482 <tr><td><strong>Version:
</strong><td>1.0 of
2001/
08/
08
483 <tr><td><strong>Dedication:
</strong><td>To my father.
487 <p>Field lists are used as part of an extension syntax, such as
488 options for
<a href=
"#directives">directives
</a>, or database-like
489 records meant for further processing. Field lists may also be
490 used as generic two-column table constructs in documents.
492 <h2><a href=
"#contents" name=
"option-lists" class=
"backref"
493 >Option Lists
</a></h2>
495 <p>(
<a href=
"../../ref/rst/restructuredtext.html#option-lists">details
</a>)
497 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
499 <tr align=
"left" bgcolor=
"#99CCFF">
500 <th width=
"50%">Plain text
501 <th width=
"50%">Typical result
507 -a
command-line
option
"a"
508 <br>-b
file
options
can
have
arguments
509 <br> and
long
descriptions
510 <br>--long
options
can
be
long
also
511 <br>--input=file
long
options
can
also
have
512 <br> arguments
513 <br>/V
DOS/VMS-style
options
too
517 <table border=
"0" width=
"100%">
520 <td width=
"30%"><samp>-a
</samp>
521 <td>command-line option
"a"
523 <td><samp>-b
<i>file
</i></samp>
524 <td>options can have arguments and long descriptions
526 <td><samp>--long
</samp>
527 <td>options can be long also
529 <td><samp>--input=
<i>file
</i></samp>
530 <td>long options can also have arguments
533 <td>DOS/VMS-style options too
537 <p>There must be at least two spaces between the option and the
540 <h2><a href=
"#contents" name=
"literal-blocks" class=
"backref"
541 >Literal Blocks
</a></h2>
543 <p>(
<a href=
"../../ref/rst/restructuredtext.html#literal-blocks">details
</a>)
545 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
547 <tr align=
"left" bgcolor=
"#99CCFF">
548 <th width=
"50%">Plain text
549 <th width=
"50%">Typical result
554 <samp>A
paragraph
containing
only
two
colons
</samp>
555 <br><samp>indicates
that
the
following
indented
</samp>
556 <br><samp>or
quoted
text
is
a
literal
block.
</samp>
560 <br><samp> Whitespace,
newlines,
blank
lines,
and
</samp>
561 <br><samp> all
kinds
of
markup
(like
*this*
or
</samp>
562 <br><samp> \this)
is
preserved
by
literal
blocks.
</samp>
564 <br><samp> The
paragraph
containing
only
'::'
</samp>
565 <br><samp> will
be
omitted
from
the
result.
</samp>
567 <br><samp>The
``::``
may
be
tacked
onto
the
very
</samp>
568 <br><samp>end
of
any
paragraph.
The
``::``
will
be
</samp>
569 <br><samp>omitted
if
it
is
preceded
by
whitespace.
</samp>
570 <br><samp>The
``::``
will
be
converted
to
a
single
</samp>
571 <br><samp>colon
if
preceded
by
text,
like
this::
</samp>
573 <br><samp> It's
very
convenient
to
use
this
form.
</samp>
575 <br><samp>Literal
blocks
end
when
text
returns
to
</samp>
576 <br><samp>the
preceding
paragraph's
indentation.
</samp>
577 <br><samp>This
means
that
something
like
this
</samp>
578 <br><samp>is
possible::
</samp>
580 <br><samp> We
start
here
</samp>
581 <br><samp> and
continue
here
</samp>
582 <br><samp> and
end
here.
</samp>
584 <br><samp>Per-line
quoting
can
also
be
used
on
</samp>
585 <br><samp>unindented
literal
blocks::
</samp>
587 <br><samp>> Useful
for
quotes
from
email
and
</samp>
588 <br><samp>> for
Haskell
literate
programming.
</samp>
591 <p>A paragraph containing only two colons
592 indicates that the following indented or quoted
593 text is a literal block.
596 Whitespace, newlines, blank lines, and
597 all kinds of markup (like *this* or
598 \this) is preserved by literal blocks.
600 The paragraph containing only '::'
601 will be omitted from the result.
</pre>
603 <p>The
<samp>::
</samp> may be tacked onto the very
604 end of any paragraph. The
<samp>::
</samp> will be
605 omitted if it is preceded by whitespace.
606 The
<samp>::
</samp> will be converted to a single
607 colon if preceded by text, like this:
610 It's very convenient to use this form.
</pre>
612 <p>Literal blocks end when text returns to
613 the preceding paragraph's indentation.
614 This means that something like this is possible:
621 <p>Per-line quoting can also be used on
622 unindented literal blocks:
625 > Useful for quotes from email and
626 > for Haskell literate programming.
</pre>
629 <h2><a href=
"#contents" name=
"line-blocks" class=
"backref"
630 >Line Blocks
</a></h2>
632 <p>(
<a href=
"../../ref/rst/restructuredtext.html#line-blocks">details
</a>)
634 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
636 <tr align=
"left" bgcolor=
"#99CCFF">
637 <th width=
"50%">Plain text
638 <th width=
"50%">Typical result
643 <samp>|
Line
blocks
are
useful
for
addresses,
</samp>
644 <br><samp>|
verse,
and
adornment-free
lists.
</samp>
646 <br><samp>|
Each
new
line
begins
with
a
</samp>
647 <br><samp>|
vertical
bar
(
"|").
</samp>
648 <br><samp>|
Line
breaks
and
initial
indents
</samp>
649 <br><samp>|
are
preserved.
</samp>
650 <br><samp>|
Continuation
lines
are
wrapped
</samp>
651 <br><samp> portions
of
long
lines;
they
begin
</samp>
652 <br><samp> with
spaces
in
place
of
vertical
bars.
</samp>
655 <div class=
"line-block">
656 <div class=
"line">Line blocks are useful for addresses,
</div>
657 <div class=
"line">verse, and adornment-free lists.
</div>
658 <div class=
"line"><br /></div>
659 <div class=
"line">Each new line begins with a
</div>
660 <div class=
"line">vertical bar (
"|").
</div>
661 <div class=
"line-block">
662 <div class=
"line">Line breaks and initial indents
</div>
663 <div class=
"line">are preserved.
</div>
665 <div class=
"line">Continuation lines are wrapped portions
666 of long lines; they begin
667 with spaces in place of vertical bars.
</div>
671 <h2><a href=
"#contents" name=
"block-quotes" class=
"backref"
672 >Block Quotes
</a></h2>
674 <p>(
<a href=
"../../ref/rst/restructuredtext.html#block-quotes">details
</a>)
676 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
678 <tr align=
"left" bgcolor=
"#99CCFF">
679 <th width=
"50%">Plain text
680 <th width=
"50%">Typical result
685 <samp>Block
quotes
are
just:
</samp>
687 <p><samp> Indented
paragraphs,
</samp>
689 <p><samp> and
they
may
nest.
</samp>
691 Block quotes are just:
693 <p>Indented paragraphs,
695 <p>and they may nest.
700 <p>Use
<a href=
"#comments">empty comments
</a> to separate indentation
701 contexts, such as block quotes and directive contents.
</p>
703 <h2><a href=
"#contents" name=
"doctest-blocks" class=
"backref"
704 >Doctest Blocks
</a></h2>
706 <p>(
<a href=
"../../ref/rst/restructuredtext.html#doctest-blocks">details
</a>)
708 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
710 <tr align=
"left" bgcolor=
"#99CCFF">
711 <th width=
"50%">Plain text
712 <th width=
"50%">Typical result
717 <p><samp>Doctest
blocks
are
interactive
718 <br>Python
sessions.
They
begin
with
719 <br>"``>>>``" and
end
with
a
blank
line.
</samp>
721 <p><samp>>>> print
"This is a doctest block."
722 <br>This
is
a
doctest
block.
</samp>
725 <p>Doctest blocks are interactive
726 Python sessions. They begin with
727 "<samp>>>></samp>" and end with a blank line.
729 <p><samp>>>> print
"This is a doctest block."
730 <br>This
is
a
doctest
block.
</samp>
734 href="http://www.python.org/doc/current/lib/module-doctest.html
">doctest</a>
735 module searches a module's docstrings for text that looks like an
736 interactive Python session, then executes all such sessions to
737 verify they still work exactly as shown." (From the doctest docs.)
739 <h2><a href=
"#contents" name=
"tables" class=
"backref"
742 <p>(
<a href=
"../../ref/rst/restructuredtext.html#tables">details
</a>)
744 <p>There are two syntaxes for tables in reStructuredText. Grid
745 tables are complete but cumbersome to create. Simple tables are
746 easy to create but limited (no row spans, etc.).
</p>
748 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
750 <tr align=
"left" bgcolor=
"#99CCFF">
751 <th width=
"50%">Plain text
752 <th width=
"50%">Typical result
757 <p><samp>Grid table:
</samp></p>
759 <p><samp>+------------+------------+-----------+
</samp>
760 <br><samp>|
Header
1 |
Header
2 |
Header
3 |
</samp>
761 <br><samp>+============+============+===========+
</samp>
762 <br><samp>|
body
row
1 |
column
2 |
column
3 |
</samp>
763 <br><samp>+------------+------------+-----------+
</samp>
764 <br><samp>|
body
row
2 |
Cells
may
span
columns.|
</samp>
765 <br><samp>+------------+------------+-----------+
</samp>
766 <br><samp>|
body
row
3 |
Cells
may
|
-
Cells
|
</samp>
767 <br><samp>+------------+
span
rows.
|
-
contain
|
</samp>
768 <br><samp>|
body
row
4 |
|
-
blocks.
|
</samp>
769 <br><samp>+------------+------------+-----------+
</samp></p>
773 <thead valign=
"bottom">
788 <td colspan=
"2">Cells may span columns.
792 <td rowspan=
"2">Cells may
<br>span rows.
806 <p><samp>Simple table:
</samp></p>
808 <p><samp>=====
=====
======
</samp>
809 <br><samp> Inputs
Output
</samp>
810 <br><samp>------------
------
</samp>
811 <br><samp> A
B
A
or
B
</samp>
812 <br><samp>=====
=====
======
</samp>
813 <br><samp>False
False
False
</samp>
814 <br><samp>True
False
True
</samp>
815 <br><samp>False
True
True
</samp>
816 <br><samp>True
True
True
</samp>
817 <br><samp>=====
=====
======
</samp></p>
827 <thead valign=
"bottom">
829 <th colspan=
"2">Inputs
856 <h2><a href=
"#contents" name=
"transitions" class=
"backref"
857 >Transitions
</a></h2>
859 <p>(
<a href=
"../../ref/rst/restructuredtext.html#transitions">details
</a>)
861 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
863 <tr align=
"left" bgcolor=
"#99CCFF">
864 <th width=
"50%">Plain text
865 <th width=
"50%">Typical result
871 A
transition
marker
is
a
horizontal
line
872 <br>of
4 or
more
repeated
punctuation
873 <br>characters.
</samp>
875 <p><samp>------------
</samp>
877 <p><samp>A
transition
should
not
begin
or
end
a
878 <br>section
or
document,
nor
should
two
879 <br>transitions
be
immediately
adjacent.
</samp>
882 <p>A transition marker is a horizontal line
883 of
4 or more repeated punctuation
888 <p>A transition should not begin or end a
889 section or document, nor should two
890 transitions be immediately adjacent.
893 <p>Transitions are commonly seen in novels and short fiction, as a
894 gap spanning one or more lines, marking text divisions or
895 signaling changes in subject, time, point of view, or emphasis.
897 <h2><a href=
"#contents" name=
"explicit-markup" class=
"backref"
898 >Explicit Markup
</a></h2>
900 <p>Explicit markup blocks are used for constructs which float
901 (footnotes), have no direct paper-document representation
902 (hyperlink targets, comments), or require specialized processing
903 (directives). They all begin with two periods and whitespace, the
904 "explicit markup start".
906 <h3><a href=
"#contents" name=
"footnotes" class=
"backref"
909 <p>(
<a href=
"../../ref/rst/restructuredtext.html#footnotes">details
</a>)
911 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
913 <tr align=
"left" bgcolor=
"#99CCFF">
914 <th width=
"50%">Plain text
915 <th width=
"50%">Typical result
921 <samp>Footnote
references,
like
[
5]_.
</samp>
922 <br><samp>Note
that
footnotes
may
get
</samp>
923 <br><samp>rearranged,
e.g.,
to
the
bottom
of
</samp>
924 <br><samp>the
"page".
</samp>
926 <p><samp>..
[
5]
A
numerical
footnote.
Note
</samp>
927 <br><samp> there's
no
colon
after
the
``]``.
</samp>
930 Footnote references, like
<sup><a href=
"#5">5</a></sup>.
931 Note that footnotes may get rearranged, e.g., to the bottom of
935 <tr><td colspan=
"2"><hr>
936 <!-- <tr><td colspan="2">Footnotes: -->
937 <tr><td><a name=
"5"><strong>[
5]
</strong></a><td> A numerical footnote.
938 Note there's no colon after the
<samp>]
</samp>.
943 <samp>Autonumbered
footnotes
are
</samp>
944 <br><samp>possible,
like
using
[#]_
and
[#]_.
</samp>
945 <p><samp>..
[#]
This
is
the
first
one.
</samp>
946 <br><samp>..
[#]
This
is
the
second
one.
</samp>
948 <p><samp>They
may
be
assigned
'autonumber
</samp>
949 <br><samp>labels'
-
for
instance,
950 <br>[#fourth]_
and
[#third]_.
</samp>
952 <p><samp>..
[#third]
a.k.a.
third_
</samp>
953 <p><samp>..
[#fourth]
a.k.a.
fourth_
</samp>
955 Autonumbered footnotes are possible, like using
<sup><a
956 href=
"#auto1">1</a></sup> and
<sup><a href=
"#auto2">2</a></sup>.
958 <p>They may be assigned 'autonumber labels' - for instance,
959 <sup><a href=
"#fourth">4</a></sup> and
<sup><a
960 href=
"#third">3</a></sup>.
963 <tr><td colspan=
"2"><hr>
964 <!-- <tr><td colspan="2">Footnotes: -->
965 <tr><td><a name=
"auto1"><strong>[
1]
</strong></a><td> This is the first one.
966 <tr><td><a name=
"auto2"><strong>[
2]
</strong></a><td> This is the second one.
967 <tr><td><a name=
"third"><strong>[
3]
</strong></a><td> a.k.a.
<a href=
"#third">third
</a>
968 <tr><td><a name=
"fourth"><strong>[
4]
</strong></a><td> a.k.a.
<a href=
"#fourth">fourth
</a>
973 <samp>Auto-symbol
footnotes
are
also
</samp>
974 <br><samp>possible,
like
this:
[*]_
and
[*]_.
</samp>
975 <p><samp>..
[*]
This
is
the
first
one.
</samp>
976 <br><samp>..
[*]
This
is
the
second
one.
</samp>
979 Auto-symbol footnotes are also
980 possible, like this:
<sup><a href=
"#symbol1">*
</a></sup>
981 and
<sup><a href=
"#symbol2">†</a></sup>.
984 <tr><td colspan=
"2"><hr>
985 <!-- <tr><td colspan="2">Footnotes: -->
986 <tr><td><a name=
"symbol1"><strong>[*]
</strong></a><td> This is the first symbol footnote
987 <tr><td><a name=
"symbol2"><strong>[
†]
</strong></a><td> This is the second one.
992 <p>The numbering of auto-numbered footnotes is determined by the
993 order of the footnotes, not of the references. For auto-numbered
994 footnote references without autonumber labels
995 (
"<samp>[#]_</samp>"), the references and footnotes must be in the
996 same relative order. Similarly for auto-symbol footnotes
997 (
"<samp>[*]_</samp>").
999 <h3><a href=
"#contents" name=
"citations" class=
"backref"
1002 <p>(
<a href=
"../../ref/rst/restructuredtext.html#citations">details
</a>)
1004 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1006 <tr align=
"left" bgcolor=
"#99CCFF">
1007 <th width=
"50%">Plain text
1008 <th width=
"50%">Typical result
1014 <samp>Citation
references,
like
[CIT2002]_.
</samp>
1015 <br><samp>Note
that
citations
may
get
</samp>
1016 <br><samp>rearranged,
e.g.,
to
the
bottom
of
</samp>
1017 <br><samp>the
"page".
</samp>
1019 <p><samp>..
[CIT2002]
A
citation
</samp>
1020 <br><samp> (as
often
used
in
journals).
</samp>
1022 <p><samp>Citation
labels
contain
alphanumerics,
</samp>
1023 <br><samp>underlines,
hyphens
and
fullstops.
</samp>
1024 <br><samp>Case
is
not
significant.
</samp>
1026 <p><samp>Given
a
citation
like
[this]_,
one
</samp>
1027 <br><samp>can
also
refer
to
it
like
this_.
</samp>
1029 <p><samp>..
[this]
here.
</samp>
1032 Citation references, like
<a href=
"#cit2002">[CIT2002]
</a>.
1033 Note that citations may get rearranged, e.g., to the bottom of
1036 <p>Citation labels contain alphanumerics, underlines, hyphens
1037 and fullstops. Case is not significant.
1039 <p>Given a citation like
<a href=
"#this">[this]
</a>, one
1040 can also refer to it like
<a href=
"#this">this
</a>.
1043 <tr><td colspan=
"2"><hr>
1044 <!-- <tr><td colspan="2">Citations: -->
1045 <tr><td><a name=
"cit2002"><strong>[CIT2002]
</strong></a><td> A citation
1046 (as often used in journals).
1047 <tr><td><a name=
"this"><strong>[this]
</strong></a><td> here.
1052 <h3><a href=
"#contents" name=
"hyperlink-targets" class=
"backref"
1053 >Hyperlink Targets
</a></h3>
1055 <p>(
<a href=
"../../ref/rst/restructuredtext.html#hyperlink-targets">details
</a>)
1057 <h4><a href=
"#contents" name=
"external-hyperlink-targets" class=
"backref"
1058 >External Hyperlink Targets
</a></h4>
1060 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1062 <tr align=
"left" bgcolor=
"#99CCFF">
1063 <th width=
"50%">Plain text
1064 <th width=
"50%">Typical result
1070 <samp>External
hyperlinks,
like
Python_.
</samp>
1072 <p><samp>..
_Python:
http://www.python.org/
</samp>
1074 <table width=
"100%">
1075 <tr bgcolor=
"#99CCFF"><td><em>Fold-in form
</em>
1076 <tr><td>External hyperlinks, like
1077 <a href=
"http://www.python.org/">Python
</a>.
1081 <table width=
"100%">
1082 <tr bgcolor=
"#99CCFF"><td><em>Call-out form
</em>
1083 <tr><td>External hyperlinks, like
1084 <a href=
"#labPython"><i>Python
</i></a>.
1087 <tr><td colspan=
"2"><hr>
1088 <tr><td><a name=
"labPython"><i>Python:
</i></a>
1089 <td> <a href=
"http://www.python.org/">http://www.python.org/
</a>
1094 <p>"<em>Fold-in</em>" is the representation typically used in HTML
1095 documents (think of the indirect hyperlink being
"folded in" like
1096 ingredients into a cake), and
"<em>call-out</em>" is more suitable for
1097 printed documents, where the link needs to be presented explicitly, for
1098 example as a footnote. You can force usage of the call-out form by
1100 "<a href="../../ref/rst/directives.html#target-notes
">target-notes</a>"
1103 <p>reStructuredText also provides for
<b>embedded URIs
</b> (
<a
1104 href=
"../../ref/rst/restructuredtext.html#embedded-uris">details
</a>),
1105 a convenience at the expense of readability. A hyperlink
1106 reference may directly embed a target URI inline, within angle
1107 brackets. The following is exactly equivalent to the example above:
1109 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1111 <tr align=
"left" bgcolor=
"#99CCFF">
1112 <th width=
"50%">Plain text
1113 <th width=
"50%">Typical result
1119 <samp>External
hyperlinks,
like
`Python
1120 <br><http://www.python.org/
>`_.
</samp>
1121 <td>External hyperlinks, like
1122 <a href=
"http://www.python.org/">Python
</a>.
1125 <h4><a href=
"#contents" name=
"internal-hyperlink-targets" class=
"backref"
1126 >Internal Hyperlink Targets
</a></h4>
1128 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1130 <tr align=
"left" bgcolor=
"#99CCFF">
1131 <th width=
"50%">Plain text
1132 <th width=
"50%">Typical result
1137 <td rowspan=
"2"><samp>Internal
crossreferences,
like
example_.
</samp>
1139 <p><samp>..
_example:
</samp>
1141 <p><samp>This
is
an
example
crossreference
target.
</samp>
1143 <table width=
"100%">
1144 <tr bgcolor=
"#99CCFF"><td><em>Fold-in form
</em>
1145 <!-- Note that some browsers may not like an "a" tag that -->
1146 <!-- does not have any content, so we could arbitrarily -->
1147 <!-- use the first word as content - *or* just trust to -->
1149 <tr><td>Internal crossreferences, like
<a href=
"#example-foldin">example
</a>
1150 <p><a name=
"example-foldin">This
</a> is an example
1151 crossreference target.
1155 <table width=
"100%">
1156 <tr><td bgcolor=
"#99CCFF"><em>Call-out form
</em>
1157 <tr><td>Internal crossreferences, like
<a href=
"#example-callout">example
</a>
1159 <p><a name=
"example-callout"><i>example:
</i></a>
1160 <br>This is an example crossreference target.
1165 <h4><a href=
"#contents" name=
"indirect-hyperlink-targets" class=
"backref"
1166 >Indirect Hyperlink Targets
</a></h4>
1168 <p>(
<a href=
"../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details
</a>)
1170 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1172 <tr align=
"left" bgcolor=
"#99CCFF">
1173 <th width=
"50%">Plain text
1174 <th width=
"50%">Typical result
1180 <samp>Python_
is
`my
favourite
1181 <br>programming
language`__.
</samp>
1183 <p><samp>..
_Python:
http://www.python.org/
</samp>
1185 <p><samp>__
Python_
</samp>
1188 <p><a href=
"http://www.python.org/">Python
</a> is
1189 <a href=
"http://www.python.org/">my favourite
1190 programming language
</a>.
1194 <p>The second hyperlink target (the line beginning with
1195 "<samp>__</samp>") is both an indirect hyperlink target
1196 (
<i>indirectly
</i> pointing at the Python website via the
1197 "<samp>Python_</samp>" reference) and an
<b>anonymous hyperlink
1198 target
</b>. In the text, a double-underscore suffix is used to
1199 indicate an
<b>anonymous hyperlink reference
</b>. In an anonymous
1200 hyperlink target, the reference text is not repeated. This is
1201 useful for references with long text or throw-away references, but
1202 the target should be kept close to the reference to prevent them
1205 <h4><a href=
"#contents" name=
"implicit-hyperlink-targets" class=
"backref"
1206 >Implicit Hyperlink Targets
</a></h4>
1208 <p>(
<a href=
"../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details
</a>)
1210 <p>Section titles, footnotes, and citations automatically generate
1211 hyperlink targets (the title text or footnote/citation label is
1212 used as the hyperlink name).
1214 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1215 <thead><tr align=
"left" bgcolor=
"#99CCFF">
1216 <th width=
"50%">Plain text
1217 <th width=
"50%">Typical result
1223 <samp>Titles
are
targets,
too
</samp>
1224 <br><samp>=======================
</samp>
1225 <br><samp>Implicit
references,
like
`Titles
are
</samp>
1226 <br><samp>targets,
too`_.
</samp>
1228 <font size=
"+2"><strong><a name=
"title">Titles are targets, too
</a></strong></font>
1229 <p>Implicit references, like
<a href=
"#title">Titles are
1233 <h3><a href=
"#contents" name=
"directives" class=
"backref"
1234 >Directives
</a></h3>
1236 <p>(
<a href=
"../../ref/rst/restructuredtext.html#directives">details
</a>)
1238 <p>Directives are a general-purpose extension mechanism, a way of
1239 adding support for new constructs without adding new syntax. For
1240 a description of all standard directives, see
<a
1241 href=
"../../ref/rst/directives.html" >reStructuredText
1244 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1246 <tr align=
"left" bgcolor=
"#99CCFF">
1247 <th width=
"50%">Plain text
1248 <th width=
"50%">Typical result
1252 <td><samp>For
instance:
</samp>
1254 <p><samp>..
image::
images/ball1.gif
</samp>
1258 <p><img src=
"images/ball1.gif" alt=
"ball1">
1261 <h3><a href=
"#contents" name=
"substitution-references-and-definitions"
1262 class=
"backref" >Substitution References and Definitions
</a></h3>
1264 <p>(
<a href=
"../../ref/rst/restructuredtext.html#substitution-definitions">details
</a>)
1266 <p>Substitutions are like inline directives, allowing graphics and
1267 arbitrary constructs within text.
1269 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1271 <tr align=
"left" bgcolor=
"#99CCFF">
1272 <th width=
"50%">Plain text
1273 <th width=
"50%">Typical result
1278 The
|biohazard|
symbol
must
be
1279 used
on
containers
used
to
1280 dispose
of
medical
waste.
</samp>
1283 ..
|biohazard|
image::
biohazard.png
</samp>
1287 <p>The
<img src=
"images/biohazard.png" align=
"bottom" alt=
"biohazard"> symbol
1288 must be used on containers used to dispose of medical waste.
1292 <h3><a href=
"#contents" name=
"comments" class=
"backref"
1295 <p>(
<a href=
"../../ref/rst/restructuredtext.html#comments">details
</a>)
1297 <p>Any text which begins with an explicit markup start but doesn't
1298 use the syntax of any of the constructs above, is a comment.
1300 <p><table border=
"1" width=
"100%" bgcolor=
"#ffffcc" cellpadding=
"3">
1302 <tr align=
"left" bgcolor=
"#99CCFF">
1303 <th width=
"50%">Plain text
1304 <th width=
"50%">Typical result
1308 <td><samp>..
This
text
will
not
be
shown
</samp>
1309 <br><samp> (but,
for
instance,
in
HTML
might
be
</samp>
1310 <br><samp> rendered
as
an
HTML
comment)
</samp>
1313 <!-- This text will not be shown -->
1314 <!-- (but, for instance in HTML might be -->
1315 <!-- rendered as an HTML comment) -->
1319 <samp>An
"empty comment" does
not
</samp>
1320 <br><samp>consume
following
blocks.
</samp>
1321 <br><samp>(An
empty
comment
is
".." with
</samp>
1322 <br><samp>blank
lines
before
and
after.)
</samp>
1324 <p><samp> So
this
block
is
not
"lost",
</samp>
1325 <br><samp> despite
its
indentation.
</samp>
1327 An
"empty comment" does not
1328 consume following blocks.
1329 (An empty comment is
".." with
1330 blank lines before and after.)
1332 So this block is not
"lost",
1333 despite its indentation.
1337 <h2><a href=
"#contents" name=
"getting-help" class=
"backref"
1338 >Getting Help
</a></h2>
1340 <p>Users who have questions or need assistance with Docutils or
1341 reStructuredText should
<a
1342 href=
"mailto:docutils-users@lists.sourceforge.net" >post a
1343 message
</a> to the
<a
1344 href=
"http://lists.sourceforge.net/lists/listinfo/docutils-users"
1345 >Docutils-Users mailing list
</a>. The
<a
1346 href=
"http://docutils.sourceforge.net/" >Docutils project web
1347 site
</a> has more information.
1352 <a href=
"http://www.tibsnjoan.co.uk/">Tibs
</a>
1353 (
<a href=
"mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk
</tt></a>)
1355 (
<a href=
"mailto:goodger@python.org">goodger@python.org
</a>)
1357 <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 -->