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=us-ascii">
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: 2005-09-05 22:44:51 +0200 (Mon, 05 Sep 2005) $</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
<h2><a href="#contents" name="doctest-blocks" class="backref"
701
>Doctest Blocks</a></h2>
703
<p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>)
705
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
707
<tr align="left" bgcolor="#99CCFF">
708
<th width="50%">Plain text
709
<th width="50%">Typical result
714
<p><samp>Doctest blocks are interactive
715
<br>Python sessions. They begin with
716
<br>"``>>>``" and end with a blank line.</samp>
718
<p><samp>>>> print "This is a doctest block."
719
<br>This is a doctest block.</samp>
722
<p>Doctest blocks are interactive
723
Python sessions. They begin with
724
"<samp>>>></samp>" and end with a blank line.
726
<p><samp>>>> print "This is a doctest block."
727
<br>This is a doctest block.</samp>
731
href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a>
732
module searches a module's docstrings for text that looks like an
733
interactive Python session, then executes all such sessions to
734
verify they still work exactly as shown." (From the doctest docs.)
736
<h2><a href="#contents" name="tables" class="backref"
739
<p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>)
741
<p>There are two syntaxes for tables in reStructuredText. Grid
742
tables are complete but cumbersome to create. Simple tables are
743
easy to create but limited (no row spans, etc.).</p>
745
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
747
<tr align="left" bgcolor="#99CCFF">
748
<th width="50%">Plain text
749
<th width="50%">Typical result
754
<p><samp>Grid table:</samp></p>
756
<p><samp>+------------+------------+-----------+</samp>
757
<br><samp>| Header 1 | Header 2 | Header 3 |</samp>
758
<br><samp>+============+============+===========+</samp>
759
<br><samp>| body row 1 | column 2 | column 3 |</samp>
760
<br><samp>+------------+------------+-----------+</samp>
761
<br><samp>| body row 2 | Cells may span columns.|</samp>
762
<br><samp>+------------+------------+-----------+</samp>
763
<br><samp>| body row 3 | Cells may | - Cells |</samp>
764
<br><samp>+------------+ span rows. | - contain |</samp>
765
<br><samp>| body row 4 | | - blocks. |</samp>
766
<br><samp>+------------+------------+-----------+</samp></p>
770
<thead valign="bottom">
785
<td colspan="2">Cells may span columns.
789
<td rowspan="2">Cells may<br>span rows.
803
<p><samp>Simple table:</samp></p>
805
<p><samp>===== ===== ======</samp>
806
<br><samp> Inputs Output</samp>
807
<br><samp>------------ ------</samp>
808
<br><samp> A B A or B</samp>
809
<br><samp>===== ===== ======</samp>
810
<br><samp>False False False</samp>
811
<br><samp>True False True</samp>
812
<br><samp>False True True</samp>
813
<br><samp>True True True</samp>
814
<br><samp>===== ===== ======</samp></p>
824
<thead valign="bottom">
826
<th colspan="2">Inputs
853
<h2><a href="#contents" name="transitions" class="backref"
854
>Transitions</a></h2>
856
<p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>)
858
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
860
<tr align="left" bgcolor="#99CCFF">
861
<th width="50%">Plain text
862
<th width="50%">Typical result
868
A transition marker is a horizontal line
869
<br>of 4 or more repeated punctuation
870
<br>characters.</samp>
872
<p><samp>------------</samp>
874
<p><samp>A transition should not begin or end a
875
<br>section or document, nor should two
876
<br>transitions be immediately adjacent.</samp>
879
<p>A transition marker is a horizontal line
880
of 4 or more repeated punctuation
885
<p>A transition should not begin or end a
886
section or document, nor should two
887
transitions be immediately adjacent.
890
<p>Transitions are commonly seen in novels and short fiction, as a
891
gap spanning one or more lines, marking text divisions or
892
signaling changes in subject, time, point of view, or emphasis.
894
<h2><a href="#contents" name="explicit-markup" class="backref"
895
>Explicit Markup</a></h2>
897
<p>Explicit markup blocks are used for constructs which float
898
(footnotes), have no direct paper-document representation
899
(hyperlink targets, comments), or require specialized processing
900
(directives). They all begin with two periods and whitespace, the
901
"explicit markup start".
903
<h3><a href="#contents" name="footnotes" class="backref"
906
<p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>)
908
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
910
<tr align="left" bgcolor="#99CCFF">
911
<th width="50%">Plain text
912
<th width="50%">Typical result
918
<samp>Footnote references, like [5]_.</samp>
919
<br><samp>Note that footnotes may get</samp>
920
<br><samp>rearranged, e.g., to the bottom of</samp>
921
<br><samp>the "page".</samp>
923
<p><samp>.. [5] A numerical footnote. Note</samp>
924
<br><samp> there's no colon after the ``]``.</samp>
927
Footnote references, like <sup><a href="#5">5</a></sup>.
928
Note that footnotes may get rearranged, e.g., to the bottom of
932
<tr><td colspan="2"><hr>
933
<!-- <tr><td colspan="2">Footnotes: -->
934
<tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote.
935
Note there's no colon after the <samp>]</samp>.
940
<samp>Autonumbered footnotes are</samp>
941
<br><samp>possible, like using [#]_ and [#]_.</samp>
942
<p><samp>.. [#] This is the first one.</samp>
943
<br><samp>.. [#] This is the second one.</samp>
945
<p><samp>They may be assigned 'autonumber</samp>
946
<br><samp>labels' - for instance,
947
<br>[#fourth]_ and [#third]_.</samp>
949
<p><samp>.. [#third] a.k.a. third_</samp>
950
<p><samp>.. [#fourth] a.k.a. fourth_</samp>
952
Autonumbered footnotes are possible, like using <sup><a
953
href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>.
955
<p>They may be assigned 'autonumber labels' - for instance,
956
<sup><a href="#fourth">4</a></sup> and <sup><a
957
href="#third">3</a></sup>.
960
<tr><td colspan="2"><hr>
961
<!-- <tr><td colspan="2">Footnotes: -->
962
<tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one.
963
<tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one.
964
<tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a>
965
<tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a>
970
<samp>Auto-symbol footnotes are also</samp>
971
<br><samp>possible, like this: [*]_ and [*]_.</samp>
972
<p><samp>.. [*] This is the first one.</samp>
973
<br><samp>.. [*] This is the second one.</samp>
976
Auto-symbol footnotes are also
977
possible, like this: <sup><a href="#symbol1">*</a></sup>
978
and <sup><a href="#symbol2">†</a></sup>.
981
<tr><td colspan="2"><hr>
982
<!-- <tr><td colspan="2">Footnotes: -->
983
<tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote
984
<tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one.
989
<p>The numbering of auto-numbered footnotes is determined by the
990
order of the footnotes, not of the references. For auto-numbered
991
footnote references without autonumber labels
992
("<samp>[#]_</samp>"), the references and footnotes must be in the
993
same relative order. Similarly for auto-symbol footnotes
994
("<samp>[*]_</samp>").
996
<h3><a href="#contents" name="citations" class="backref"
999
<p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>)
1001
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1003
<tr align="left" bgcolor="#99CCFF">
1004
<th width="50%">Plain text
1005
<th width="50%">Typical result
1011
<samp>Citation references, like [CIT2002]_.</samp>
1012
<br><samp>Note that citations may get</samp>
1013
<br><samp>rearranged, e.g., to the bottom of</samp>
1014
<br><samp>the "page".</samp>
1016
<p><samp>.. [CIT2002] A citation</samp>
1017
<br><samp> (as often used in journals).</samp>
1019
<p><samp>Citation labels contain alphanumerics,</samp>
1020
<br><samp>underlines, hyphens and fullstops.</samp>
1021
<br><samp>Case is not significant.</samp>
1023
<p><samp>Given a citation like [this]_, one</samp>
1024
<br><samp>can also refer to it like this_.</samp>
1026
<p><samp>.. [this] here.</samp>
1029
Citation references, like <a href="#cit2002">[CIT2002]</a>.
1030
Note that citations may get rearranged, e.g., to the bottom of
1033
<p>Citation labels contain alphanumerics, underlines, hyphens
1034
and fullstops. Case is not significant.
1036
<p>Given a citation like <a href="#this">[this]</a>, one
1037
can also refer to it like <a href="#this">this</a>.
1040
<tr><td colspan="2"><hr>
1041
<!-- <tr><td colspan="2">Citations: -->
1042
<tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation
1043
(as often used in journals).
1044
<tr><td><a name="this"><strong>[this]</strong></a><td> here.
1049
<h3><a href="#contents" name="hyperlink-targets" class="backref"
1050
>Hyperlink Targets</a></h3>
1052
<p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>)
1054
<h4><a href="#contents" name="external-hyperlink-targets" class="backref"
1055
>External Hyperlink Targets</a></h4>
1057
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1059
<tr align="left" bgcolor="#99CCFF">
1060
<th width="50%">Plain text
1061
<th width="50%">Typical result
1067
<samp>External hyperlinks, like Python_.</samp>
1069
<p><samp>.. _Python: http://www.python.org/</samp>
1071
<table width="100%">
1072
<tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
1073
<tr><td>External hyperlinks, like
1074
<a href="http://www.python.org/">Python</a>.
1078
<table width="100%">
1079
<tr bgcolor="#99CCFF"><td><em>Call-out form</em>
1080
<tr><td>External hyperlinks, like
1081
<a href="#labPython"><i>Python</i></a>.
1084
<tr><td colspan="2"><hr>
1085
<tr><td><a name="labPython"><i>Python:</i></a>
1086
<td> <a href="http://www.python.org/">http://www.python.org/</a>
1091
<p>"<em>Fold-in</em>" is the representation typically used in HTML
1092
documents (think of the indirect hyperlink being "folded in" like
1093
ingredients into a cake), and "<em>call-out</em>" is more suitable for
1094
printed documents, where the link needs to be presented explicitly, for
1095
example as a footnote. You can force usage of the call-out form by
1097
"<a href="../../ref/rst/directives.html#target-notes">target-notes</a>"
1100
<p>reStructuredText also provides for <b>embedded URIs</b> (<a
1101
href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>),
1102
a convenience at the expense of readability. A hyperlink
1103
reference may directly embed a target URI inline, within angle
1104
brackets. The following is exactly equivalent to the example above:
1106
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1108
<tr align="left" bgcolor="#99CCFF">
1109
<th width="50%">Plain text
1110
<th width="50%">Typical result
1116
<samp>External hyperlinks, like `Python
1117
<br><http://www.python.org/>`_.</samp>
1118
<td>External hyperlinks, like
1119
<a href="http://www.python.org/">Python</a>.
1122
<h4><a href="#contents" name="internal-hyperlink-targets" class="backref"
1123
>Internal Hyperlink Targets</a></h4>
1125
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1127
<tr align="left" bgcolor="#99CCFF">
1128
<th width="50%">Plain text
1129
<th width="50%">Typical result
1134
<td rowspan="2"><samp>Internal crossreferences, like example_.</samp>
1136
<p><samp>.. _example:</samp>
1138
<p><samp>This is an example crossreference target.</samp>
1140
<table width="100%">
1141
<tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
1142
<!-- Note that some browsers may not like an "a" tag that -->
1143
<!-- does not have any content, so we could arbitrarily -->
1144
<!-- use the first word as content - *or* just trust to -->
1146
<tr><td>Internal crossreferences, like <a href="#example-foldin">example</a>
1147
<p><a name="example-foldin">This</a> is an example
1148
crossreference target.
1152
<table width="100%">
1153
<tr><td bgcolor="#99CCFF"><em>Call-out form</em>
1154
<tr><td>Internal crossreferences, like <a href="#example-callout">example</a>
1156
<p><a name="example-callout"><i>example:</i></a>
1157
<br>This is an example crossreference target.
1162
<h4><a href="#contents" name="indirect-hyperlink-targets" class="backref"
1163
>Indirect Hyperlink Targets</a></h4>
1165
<p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>)
1167
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1169
<tr align="left" bgcolor="#99CCFF">
1170
<th width="50%">Plain text
1171
<th width="50%">Typical result
1177
<samp>Python_ is `my favourite
1178
<br>programming language`__.</samp>
1180
<p><samp>.. _Python: http://www.python.org/</samp>
1182
<p><samp>__ Python_</samp>
1185
<p><a href="http://www.python.org/">Python</a> is
1186
<a href="http://www.python.org/">my favourite
1187
programming language</a>.
1191
<p>The second hyperlink target (the line beginning with
1192
"<samp>__</samp>") is both an indirect hyperlink target
1193
(<i>indirectly</i> pointing at the Python website via the
1194
"<samp>Python_</samp>" reference) and an <b>anonymous hyperlink
1195
target</b>. In the text, a double-underscore suffix is used to
1196
indicate an <b>anonymous hyperlink reference</b>. In an anonymous
1197
hyperlink target, the reference text is not repeated. This is
1198
useful for references with long text or throw-away references, but
1199
the target should be kept close to the reference to prevent them
1202
<h4><a href="#contents" name="implicit-hyperlink-targets" class="backref"
1203
>Implicit Hyperlink Targets</a></h4>
1205
<p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>)
1207
<p>Section titles, footnotes, and citations automatically generate
1208
hyperlink targets (the title text or footnote/citation label is
1209
used as the hyperlink name).
1211
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1212
<thead><tr align="left" bgcolor="#99CCFF">
1213
<th width="50%">Plain text
1214
<th width="50%">Typical result
1220
<samp>Titles are targets, too</samp>
1221
<br><samp>=======================</samp>
1222
<br><samp>Implict references, like `Titles are</samp>
1223
<br><samp>targets, too`_.</samp>
1225
<font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font>
1226
<p>Implict references, like <a href="#title">Titles are
1230
<h3><a href="#contents" name="directives" class="backref"
1231
>Directives</a></h3>
1233
<p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>)
1235
<p>Directives are a general-purpose extension mechanism, a way of
1236
adding support for new constructs without adding new syntax. For
1237
a description of all standard directives, see <a
1238
href="../../ref/rst/directives.html" >reStructuredText
1241
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1243
<tr align="left" bgcolor="#99CCFF">
1244
<th width="50%">Plain text
1245
<th width="50%">Typical result
1249
<td><samp>For instance:</samp>
1251
<p><samp>.. image:: images/ball1.gif</samp>
1255
<p><img src="images/ball1.gif" alt="ball1">
1258
<h3><a href="#contents" name="substitution-references-and-definitions"
1259
class="backref" >Substitution References and Definitions</a></h3>
1261
<p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>)
1263
<p>Substitutions are like inline directives, allowing graphics and
1264
arbitrary constructs within text.
1266
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1268
<tr align="left" bgcolor="#99CCFF">
1269
<th width="50%">Plain text
1270
<th width="50%">Typical result
1275
The |biohazard| symbol must be
1276
used on containers used to
1277
dispose of medical waste.</samp>
1280
.. |biohazard| image:: biohazard.png</samp>
1284
<p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol
1285
must be used on containers used to dispose of medical waste.
1289
<h3><a href="#contents" name="comments" class="backref"
1292
<p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>)
1294
<p>Any text which begins with an explicit markup start but doesn't
1295
use the syntax of any of the constructs above, is a comment.
1297
<p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
1299
<tr align="left" bgcolor="#99CCFF">
1300
<th width="50%">Plain text
1301
<th width="50%">Typical result
1305
<td><samp>.. This text will not be shown</samp>
1306
<br><samp> (but, for instance, in HTML might be</samp>
1307
<br><samp> rendered as an HTML comment)</samp>
1310
<!-- This text will not be shown -->
1311
<!-- (but, for instance in HTML might be -->
1312
<!-- rendered as an HTML comment) -->
1316
<samp>An empty "comment" does not</samp>
1317
<br><samp>"consume" following blocks.</samp>
1319
<p><samp> So this block is not "lost",</samp>
1320
<br><samp> despite its indentation.</samp>
1322
An empty "comment" does not
1323
"consume" following blocks.
1325
So this block is not "lost",
1326
despite its indentation.
1330
<h2><a href="#contents" name="getting-help" class="backref"
1331
>Getting Help</a></h2>
1333
<p>Users who have questions or need assistance with Docutils or
1334
reStructuredText should <a
1335
href="mailto:docutils-users@lists.sourceforge.net" >post a
1336
message</a> to the <a
1337
href="http://lists.sourceforge.net/lists/listinfo/docutils-users"
1338
>Docutils-Users mailing list</a>. The <a
1339
href="http://docutils.sourceforge.net/" >Docutils project web
1340
site</a> has more information.
1345
<a href="http://www.tibsnjoan.co.uk/">Tibs</a>
1346
(<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>)
1348
(<a href="mailto:goodger@python.org">goodger@python.org</a>)
1350
<!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 -->
added
removed
docs/user/rst/quickref.html
