1
=======================================
2
reStructuredText Markup Specification
3
=======================================
5
:Contact: goodger@users.sourceforge.net
6
:Revision: $Revision: 4233 $
7
:Date: $Date: 2005-12-29 00:48:48 +0100 (Thu, 29 Dec 2005) $
8
:Copyright: This document has been placed in the public domain.
12
This document is a detailed technical specification; it is not a
13
tutorial or a primer. If this is your first exposure to
14
reStructuredText, please read `A ReStructuredText Primer`_ and the
15
`Quick reStructuredText`_ user reference first.
17
.. _A ReStructuredText Primer: ../../user/rst/quickstart.html
18
.. _Quick reStructuredText: ../../user/rst/quickref.html
21
reStructuredText_ is plaintext that uses simple and intuitive
22
constructs to indicate the structure of a document. These constructs
23
are equally easy to read in raw and processed forms. This document is
24
itself an example of reStructuredText (raw, if you are reading the
25
text file, or processed, if you are reading an HTML document, for
26
example). The reStructuredText parser is a component of Docutils_.
28
Simple, implicit markup is used to indicate special constructs, such
29
as section headings, bullet lists, and emphasis. The markup used is
30
as minimal and unobtrusive as possible. Less often-used constructs
31
and extensions to the basic reStructuredText syntax may have more
32
elaborate or explicit markup.
34
reStructuredText is applicable to documents of any length, from the
35
very small (such as inline program documentation fragments, e.g.
36
Python docstrings) to the quite large (this document).
38
The first section gives a quick overview of the syntax of the
39
reStructuredText markup by example. A complete specification is given
40
in the `Syntax Details`_ section.
42
`Literal blocks`_ (in which no markup processing is done) are used for
43
examples throughout this document, to illustrate the plaintext markup.
49
-----------------------
51
-----------------------
53
A reStructuredText document is made up of body or block-level
54
elements, and may be structured into sections. Sections_ are
55
indicated through title style (underlines & optional overlines).
56
Sections contain body elements and/or subsections. Some body elements
57
contain further elements, such as lists containing list items, which
58
in turn may contain paragraphs and other body elements. Others, such
59
as paragraphs, contain text and `inline markup`_ elements.
61
Here are examples of `body elements`_:
63
- Paragraphs_ (and `inline markup`_)::
65
Paragraphs contain text and may contain inline markup:
66
*emphasis*, **strong emphasis**, `interpreted text`, ``inline
67
literals``, standalone hyperlinks (http://www.python.org),
68
external hyperlinks (Python_), internal cross-references
69
(example_), footnote references ([1]_), citation references
70
([CIT2002]_), substitution references (|example|), and _`inline
73
Paragraphs are separated by blank lines and are left-aligned.
75
- Five types of lists:
79
- This is a bullet list.
81
- Bullets can be "-", "*", or "+".
83
2. `Enumerated lists`_::
85
1. This is an enumerated list.
87
2. Enumerators may be arabic numbers, letters, or roman
90
3. `Definition lists`_::
93
Definition lists associate a term with a definition.
96
The term is a one-line phrase, and the definition is one
97
or more paragraphs or body elements, indented relative to
102
:what: Field lists map field names to field bodies, like
103
database records. They are often part of an extension
106
:how: The field marker is a colon, the field name, and a
109
The field body may contain one or more body elements,
110
indented relative to the field marker.
112
5. `Option lists`_, for listing command-line options::
114
-a command-line option "a"
115
-b file options can have arguments
116
and long descriptions
117
--long options can be long also
118
--input=file long options can also have
120
/V DOS/VMS-style options too
122
There must be at least two spaces between the option and the
125
- `Literal blocks`_::
127
Literal blocks are either indented or line-prefix-quoted blocks,
128
and indicated with a double-colon ("::") at the end of the
129
preceding paragraph (right here -->)::
132
text = 'is left as-is'
133
spaces_and_linebreaks = 'are preserved'
134
markup_processing = None
138
Block quotes consist of indented body elements:
140
This theory, that is mine, is mine.
144
- `Doctest blocks`_::
146
>>> print 'Python-specific usage examples; begun with ">>>"'
147
Python-specific usage examples; begun with ">>>"
148
>>> print '(cut and pasted from interactive Python sessions)'
149
(cut and pasted from interactive Python sessions)
151
- Two syntaxes for tables_:
153
1. `Grid tables`_; complete, but complex and verbose::
155
+------------------------+------------+----------+
156
| Header row, column 1 | Header 2 | Header 3 |
157
+========================+============+==========+
158
| body row 1, column 1 | column 2 | column 3 |
159
+------------------------+------------+----------+
160
| body row 2 | Cells may span |
161
+------------------------+-----------------------+
163
2. `Simple tables`_; easy and compact, but limited::
165
==================== ========== ==========
166
Header row, column 1 Header 2 Header 3
167
==================== ========== ==========
168
body row 1, column 1 column 2 column 3
169
body row 2 Cells may span columns
170
==================== ======================
172
- `Explicit markup blocks`_ all begin with an explicit block marker,
173
two periods and a space:
177
.. [1] A footnote contains body elements, consistently
178
indented by at least 3 spaces.
182
.. [CIT2002] Just like a footnote, except the label is
185
- `Hyperlink targets`_::
187
.. _Python: http://www.python.org
191
The "_example" target above points to this paragraph.
195
.. image:: mylogo.png
197
- `Substitution definitions`_::
199
.. |symbol here| image:: symbol.png
203
.. Comments begin with two dots and a space. Anything may
204
follow, except for the syntax of footnotes/citations,
205
hyperlink targets, directives, or substitution definitions.
212
Descriptions below list "doctree elements" (document tree element
213
names; XML DTD generic identifiers) corresponding to syntax
214
constructs. For details on the hierarchy of elements, please see `The
215
Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
222
Spaces are recommended for indentation_, but tabs may also be used.
223
Tabs will be converted to spaces. Tab stops are at every 8th column.
225
Other whitespace characters (form feeds [chr(12)] and vertical tabs
226
[chr(11)]) are converted to single spaces before processing.
232
Blank lines are used to separate paragraphs and other elements.
233
Multiple successive blank lines are equivalent to a single blank line,
234
except within literal blocks (where all whitespace is preserved).
235
Blank lines may be omitted when the markup makes element separation
236
unambiguous, in conjunction with indentation. The first line of a
237
document is treated as if it is preceded by a blank line, and the last
238
line of a document is treated as if it is followed by a blank line.
244
Indentation is used to indicate -- and is only significant in
245
indicating -- block quotes, definitions (in definition list items),
246
and local nested content:
248
- list item content (multi-line contents of list items, and multiple
249
body elements within a list item, including nested lists),
250
- the content of literal blocks, and
251
- the content of explicit markup blocks.
253
Any text whose indentation is less than that of the current level
254
(i.e., unindented text or "dedents") ends the current level of
257
Since all indentation is significant, the level of indentation must be
258
consistent. For example, indentation is the sole markup indicator for
261
This is a top-level paragraph.
263
This paragraph belongs to a first-level block quote.
265
Paragraph 2 of the first-level block quote.
267
Multiple levels of indentation within a block quote will result in
268
more complex structures::
270
This is a top-level paragraph.
272
This paragraph belongs to a first-level block quote.
274
This paragraph belongs to a second-level block quote.
276
Another top-level paragraph.
278
This paragraph belongs to a second-level block quote.
280
This paragraph belongs to a first-level block quote. The
281
second-level block quote above is inside this first-level
284
When a paragraph or other construct consists of more than one line of
285
text, the lines must be left-aligned::
287
This is a paragraph. The lines of
288
this paragraph are aligned at the left.
290
This paragraph has problems. The
291
lines are not left-aligned. In addition
292
to potential misinterpretation, warning
293
and/or error messages will be generated
296
Several constructs begin with a marker, and the body of the construct
297
must be indented relative to the marker. For constructs using simple
298
markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_,
299
`hyperlink targets`_, directives_, and comments_), the level of
300
indentation of the body is determined by the position of the first
301
line of text, which begins on the same line as the marker. For
302
example, bullet list bodies must be indented by at least two columns
303
relative to the left edge of the bullet::
305
- This is the first line of a bullet list
306
item's paragraph. All lines must align
307
relative to the first line. [1]_
309
This indented paragraph is interpreted
312
Because it is not sufficiently indented,
313
this paragraph does not belong to the list
316
.. [1] Here's a footnote. The second line is aligned
317
with the beginning of the footnote label. The ".."
318
marker is what determines the indentation.
320
For constructs using complex markers (`field lists`_ and `option
321
lists`_), where the marker may contain arbitrary text, the indentation
322
of the first line *after* the marker determines the left edge of the
323
body. For example, field lists may have very long markers (containing
326
:Hello: This field has a short field name, so aligning the field
327
body with the first line is feasible.
329
:Number-of-African-swallows-required-to-carry-a-coconut: It would
330
be very difficult to align the field body with the left edge
331
of the first line. It may even be preferable not to begin the
332
body on the same line as the marker.
338
The character set universally available to plaintext documents, 7-bit
339
ASCII, is limited. No matter what characters are used for markup,
340
they will already have multiple meanings in written text. Therefore
341
markup characters *will* sometimes appear in text **without being
342
intended as markup**. Any serious markup system requires an escaping
343
mechanism to override the default meaning of the characters used for
344
the markup. In reStructuredText we use the backslash, commonly used
345
as an escaping character in other domains.
347
A backslash followed by any character (except whitespace characters)
348
escapes that character. The escaped character represents the
349
character itself, and is prevented from playing a role in any markup
350
interpretation. The backslash is removed from the output. A literal
351
backslash is represented by two backslashes in a row (the first
352
backslash "escapes" the second, preventing it being interpreted in an
355
Backslash-escaped whitespace characters are removed from the document.
356
This allows for character-level `inline markup`_.
358
There are two contexts in which backslashes have no special meaning:
359
literal blocks and inline literals. In these contexts, a single
360
backslash represents a literal backslash, without having to double up.
362
Please note that the reStructuredText specification and parser do not
363
address the issue of the representation or extraction of text input
364
(how and in what form the text actually *reaches* the parser).
365
Backslashes and other characters may serve a character-escaping
366
purpose in certain contexts and must be dealt with appropriately. For
367
example, Python uses backslashes in strings to escape certain
368
characters, but not others. The simplest solution when backslashes
369
appear in Python docstrings is to use raw docstrings::
371
r"""This is a raw docstring. Backslashes (\) are not touched."""
377
Simple reference names are single words consisting of alphanumerics
378
plus isolated (no two adjacent) internal hyphens, underscores, and
379
periods; no whitespace or other characters are allowed. Footnote
380
labels (Footnotes_ & `Footnote References`_), citation labels
381
(Citations_ & `Citation References`_), `interpreted text`_ roles, and
382
some `hyperlink references`_ use the simple reference name syntax.
384
Reference names using punctuation or whose names are phrases (two or
385
more space-separated words) are called "phrase-references".
386
Phrase-references are expressed by enclosing the phrase in backquotes
387
and treating the backquoted text as a reference name::
389
Want to learn about `my favorite programming language`_?
391
.. _my favorite programming language: http://www.python.org
393
Simple reference names may also optionally use backquotes.
395
Reference names are whitespace-neutral and case-insensitive. When
396
resolving reference names internally:
398
- whitespace is normalized (one or more spaces, horizontal or vertical
399
tabs, newlines, carriage returns, or form feeds, are interpreted as
402
- case is normalized (all alphabetic characters are converted to
405
For example, the following `hyperlink references`_ are equivalent::
412
Hyperlinks_, footnotes_, and citations_ all share the same namespace
413
for reference names. The labels of citations (simple reference names)
414
and manually-numbered footnotes (numbers) are entered into the same
415
database as other hyperlink names. This means that a footnote
416
(defined as "``.. [1]``") which can be referred to by a footnote
417
reference (``[1]_``), can also be referred to by a plain hyperlink
418
reference (1_). Of course, each type of reference (hyperlink,
419
footnote, citation) may be processed and rendered differently. Some
420
care should be taken to avoid reference name conflicts.
429
Doctree element: document.
431
The top-level element of a parsed reStructuredText document is the
432
"document" element. After initial parsing, the document element is a
433
simple container for a document fragment, consisting of `body
434
elements`_, transitions_, and sections_, but lacking a document title
435
or other bibliographic elements. The code that calls the parser may
436
choose to run one or more optional post-parse transforms_,
437
rearranging the document fragment into a complete document with a
438
title and possibly other metadata elements (author, date, etc.; see
439
`Bibliographic Fields`_).
441
Specifically, there is no way to indicate a document title and
442
subtitle explicitly in reStructuredText. Instead, a lone top-level
443
section title (see Sections_ below) can be treated as the document
444
title. Similarly, a lone second-level section title immediately after
445
the "document title" can become the document subtitle. The rest of
446
the sections are then lifted up a level or two. See the `DocTitle
447
transform`_ for details.
453
Doctree elements: section, title.
455
Sections are identified through their titles, which are marked up with
456
adornment: "underlines" below the title text, or underlines and
457
matching "overlines" above the title. An underline/overline is a
458
single repeated punctuation character that begins in column 1 and
459
forms a line extending at least as far as the right edge of the title
460
text. Specifically, an underline/overline character may be any
461
non-alphanumeric printable 7-bit ASCII character [#]_. When an
462
overline is used, the length and character used must match the
463
underline. Underline-only adornment styles are distinct from
464
overline-and-underline styles that use the same character. There may
465
be any number of levels of section titles, although some output
466
formats may have limits (HTML has 6 levels).
468
.. [#] The following are all valid section title adornment
471
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
473
Some characters are more suitable than others. The following are
476
= - ` : . ' " ~ ^ _ * + #
478
Rather than imposing a fixed number and order of section title
479
adornment styles, the order enforced will be the order as encountered.
480
The first style encountered will be an outermost title (like HTML H1),
481
the second style will be a subtitle, the third will be a subsubtitle,
484
Below are examples of section title styles::
521
When a title has both an underline and an overline, the title text may
522
be inset, as in the first two examples above. This is merely
523
aesthetic and not significant. Underline-only title text may *not* be
526
A blank line after a title is optional. All text blocks up to the
527
next title of the same or higher level are included in a section (or
530
All section title styles need not be used, nor need any specific
531
section title style be used. However, a document must be consistent
532
in its use of section titles: once a hierarchy of title styles is
533
established, sections must use that hierarchy.
535
Each section title automatically generates a hyperlink target pointing
536
to the section. The text of the hyperlink target (the "reference
537
name") is the same as that of the section title. See `Implicit
538
Hyperlink Targets`_ for a complete description.
540
Sections may contain `body elements`_, transitions_, and nested
547
Doctree element: transition.
549
Instead of subheads, extra space or a type ornament between
550
paragraphs may be used to mark text divisions or to signal
551
changes in subject or emphasis.
553
(The Chicago Manual of Style, 14th edition, section 1.80)
555
Transitions are commonly seen in novels and short fiction, as a gap
556
spanning one or more lines, with or without a type ornament such as a
557
row of asterisks. Transitions separate other body elements. A
558
transition should not begin or end a section or document, nor should
559
two transitions be immediately adjacent.
561
The syntax for a transition marker is a horizontal line of 4 or more
562
repeated punctuation characters. The syntax is the same as section
563
title underlines without title text. Transition markers require blank
564
lines before and after::
572
Unlike section title underlines, no hierarchy of transition markers is
573
enforced, nor do differences in transition markers accomplish
574
anything. It is recommended that a single consistent style be used.
576
The processing system is free to render transitions in output in any
577
way it likes. For example, horizontal rules (``<hr>``) in HTML output
578
would be an obvious choice.
587
Doctree element: paragraph.
589
Paragraphs consist of blocks of left-aligned text with no markup
590
indicating any other body element. Blank lines separate paragraphs
591
from each other and from other body elements. Paragraphs may contain
596
+------------------------------+
599
+------------------------------+
601
+------------------------------+
604
+------------------------------+
610
Doctree elements: bullet_list, list_item.
612
A text block which begins with a "-", "*", or "+", followed by
613
whitespace, is a bullet list item (a.k.a. "unordered" list item).
614
List item bodies must be left-aligned and indented relative to the
615
bullet; the text immediately after the bullet determines the
616
indentation. For example::
618
- This is the first bullet list item. The blank line above the
619
first list item is required; blank lines between list items
620
(such as below this paragraph) are optional.
622
- This is the first paragraph in the second item in the list.
624
This is the second paragraph in the second item in the list.
625
The blank line above this paragraph is required. The left edge
626
of this paragraph lines up with the paragraph above, both
627
indented relative to the bullet.
629
- This is a sublist. The bullet lines up with the left edge of
630
the text blocks above. A sublist is a new list so requires a
631
blank line above and below.
633
- This is the third item of the main list.
635
This paragraph is not part of the list.
637
Here are examples of **incorrectly** formatted bullet lists::
639
- This first line is fine.
640
A blank line is required between list items and paragraphs.
643
- The following line appears to be a new sublist, but it is not:
644
- This is a paragraph continuation, not a sublist (since there's
645
no blank line). This line is also incorrectly indented.
646
- Warnings may be issued by the implementation.
650
+------+-----------------------+
652
+------| (body elements)+ |
653
+-----------------------+
659
Doctree elements: enumerated_list, list_item.
661
Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists,
662
but use enumerators instead of bullets. An enumerator consists of an
663
enumeration sequence member and formatting, followed by whitespace.
664
The following enumeration sequences are recognized:
666
- arabic numerals: 1, 2, 3, ... (no upper limit).
667
- uppercase alphabet characters: A, B, C, ..., Z.
668
- lower-case alphabet characters: a, b, c, ..., z.
669
- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
670
- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).
672
In addition, the auto-enumerator, "#", may be used to automatically
673
enumerate a list. Auto-enumerated lists may begin with explicit
674
enumeration, which sets the sequence. Fully auto-enumerated lists use
675
arabic numerals and begin with 1. (Auto-enumerated lists are new in
678
The following formatting types are recognized:
680
- suffixed with a period: "1.", "A.", "a.", "I.", "i.".
681
- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)".
682
- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)".
684
While parsing an enumerated list, a new list will be started whenever:
686
- An enumerator is encountered which does not have the same format and
687
sequence type as the current list (e.g. "1.", "(a)" produces two
690
- The enumerators are not in sequence (e.g., "1.", "3." produces two
693
It is recommended that the enumerator of the first list item be
694
ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values
695
will be recognized, they may not be supported by the output format. A
696
level-1 [info] system message will be generated for any list beginning
697
with a non-ordinal-1 enumerator.
699
Lists using Roman numerals must begin with "I"/"i" or a
700
multi-character value, such as "II" or "XV". Any other
701
single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be
702
interpreted as a letter of the alphabet, not as a Roman numeral.
703
Likewise, lists using letters of the alphabet may not begin with
704
"I"/"i", since these are recognized as Roman numeral 1.
706
The second line of each enumerated list item is checked for validity.
707
This is to prevent ordinary paragraphs from being mistakenly
708
interpreted as list items, when they happen to begin with text
709
identical to enumerators. For example, this text is parsed as an
712
A. Einstein was a really
715
However, ambiguity cannot be avoided if the paragraph consists of only
716
one line. This text is parsed as an enumerated list item::
718
A. Einstein was a really smart dude.
720
If a single-line paragraph begins with text identical to an enumerator
721
("A.", "1.", "(b)", "I)", etc.), the first character will have to be
722
escaped in order to have the line parsed as an ordinary paragraph::
724
\A. Einstein was a really smart dude.
726
Examples of nested enumerated lists::
728
1. Item 1 initial text.
736
Example syntax diagram::
738
+-------+----------------------+
739
| "1. " | list item |
740
+-------| (body elements)+ |
741
+----------------------+
747
Doctree elements: definition_list, definition_list_item, term,
748
classifier, definition.
750
Each definition list item contains a term, optional classifiers, and a
751
definition. A term is a simple one-line word or phrase. Optional
752
classifiers may follow the term on the same line, each after an inline
753
" : " (space, colon, space). A definition is a block indented
754
relative to the term, and may contain multiple paragraphs and other
755
body elements. There may be no blank line between a term line and a
756
definition block (this distinguishes definition lists from `block
757
quotes`_). Blank lines are required before the first and after the
758
last definition list item, but are optional in-between. For example::
764
Definition 2, paragraph 1.
766
Definition 2, paragraph 2.
771
term 4 : classifier one : classifier two
774
Inline markup is parsed in the term line before the classifier
775
delimiter (" : ") is recognized. The delimiter will only be
776
recognized if it appears outside of any inline markup.
778
A definition list may be used in various ways, including:
780
- As a dictionary or glossary. The term is the word itself, a
781
classifier may be used to indicate the usage of the term (noun,
782
verb, etc.), and the definition follows.
784
- To describe program variables. The term is the variable name, a
785
classifier may be used to indicate the type of the variable (string,
786
integer, etc.), and the definition describes the variable's use in
787
the program. This usage of definition lists supports the classifier
788
syntax of Grouch_, a system for describing and enforcing a Python
793
+----------------------------+
794
| term [ " : " classifier ]* |
795
+--+-------------------------+--+
798
+----------------------------+
804
Doctree elements: field_list, field, field_name, field_body.
806
Field lists are used as part of an extension syntax, such as options
807
for directives_, or database-like records meant for further
808
processing. They may also be used for two-column table-like
809
structures resembling database records (label & data pairs).
810
Applications of reStructuredText may recognize field names and
811
transform fields or field bodies in certain contexts. For examples,
812
see `Bibliographic Fields`_ below, or the "image_" and "meta_"
813
directives in `reStructuredText Directives`_.
815
Field lists are mappings from field names to field bodies, modeled on
816
RFC822_ headers. A field name may consist of any characters, but
817
colons (":") inside of field names must be escaped with a backslash.
818
Inline markup is parsed in field names. Field names are
819
case-insensitive when further processed or transformed. The field
820
name, along with a single colon prefix and suffix, together form the
821
field marker. The field marker is followed by whitespace and the
822
field body. The field body may contain multiple body elements,
823
indented relative to the field marker. The first line after the field
824
name marker determines the indentation of the field body. For
832
:Indentation: Since the field marker may be quite long, the second
833
and subsequent lines of the field body do not have to line up
834
with the first line, but they must be indented relative to the
835
field name marker, and they must line up with each other.
836
:Parameter i: integer
838
The interpretation of individual words in a multi-word field name is
839
up to the application. The application may specify a syntax for the
840
field name. For example, second and subsequent words may be treated
841
as "arguments", quoted phrases may be treated as a single argument,
842
and direct support for the "name=value" syntax may be added.
844
Standard RFC822_ headers cannot be used for this construct because
845
they are ambiguous. A word followed by a colon at the beginning of a
846
line is common in written text. However, in well-defined contexts
847
such as when a field list invariably occurs at the beginning of a
848
document (PEPs and email messages), standard RFC822 headers could be
851
Syntax diagram (simplified)::
853
+--------------------+----------------------+
854
| ":" field name ":" | field body |
855
+-------+------------+ |
857
+-----------------------------------+
863
Doctree elements: docinfo, author, authors, organization, contact,
864
version, status, date, copyright, field, topic.
866
When a field list is the first non-comment element in a document
867
(after the document title, if there is one), it may have its fields
868
transformed to document bibliographic data. This bibliographic data
869
corresponds to the front matter of a book, such as the title page and
872
Certain registered field names (listed below) are recognized and
873
transformed to the corresponding doctree elements, most becoming child
874
elements of the "docinfo" element. No ordering is required of these
875
fields, although they may be rearranged to fit the document structure,
876
as noted. Unless otherwise indicated below, each of the bibliographic
877
elements' field bodies may contain a single paragraph only. Field
878
bodies may be checked for `RCS keywords`_ and cleaned up. Any
879
unrecognized fields will remain as generic fields in the docinfo
882
The registered bibliographic field names and their corresponding
883
doctree elements are as follows:
885
- Field name "Author": author element.
886
- "Authors": authors.
887
- "Organization": organization.
888
- "Contact": contact.
889
- "Address": address.
890
- "Version": version.
893
- "Copyright": copyright.
894
- "Dedication": topic.
897
The "Authors" field may contain either: a single paragraph consisting
898
of a list of authors, separated by ";" or ","; or a bullet list whose
899
elements each contain a single paragraph per author. ";" is checked
900
first, so "Doe, Jane; Doe, John" will work. In some languages
901
(e.g. Swedish), there is no singular/plural distinction between
902
"Author" and "Authors", so only an "Authors" field is provided, and a
903
single name is interpreted as an "Author". If a single name contains
904
a comma, end it with a semicolon to disambiguate: ":Authors: Doe,
907
The "Address" field is for a multi-line surface mailing address.
908
Newlines and whitespace will be preserved.
910
The "Dedication" and "Abstract" fields may contain arbitrary body
911
elements. Only one of each is allowed. They become topic elements
912
with "Dedication" or "Abstract" titles (or language equivalents)
913
immediately following the docinfo element.
915
This field-name-to-element mapping can be replaced for other
916
languages. See the `DocInfo transform`_ implementation documentation
919
Unregistered/generic fields may contain one or more paragraphs or
920
arbitrary body elements.
926
`Bibliographic fields`_ recognized by the parser are normally checked
927
for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be
928
entered into source files as "$keyword$", and once stored under RCS or
929
CVS [#]_, they are expanded to "$keyword: expansion text $". For
930
example, a "Status" field will be transformed to a "status" element::
932
:Status: $keyword: expansion text $
934
.. [#] Revision Control System.
935
.. [#] RCS keyword processing can be turned off (unimplemented).
936
.. [#] Concurrent Versions System. CVS uses the same keywords as RCS.
938
Processed, the "status" element's text will become simply "expansion
939
text". The dollar sign delimiters and leading RCS keyword name are
942
The RCS keyword processing only kicks in when the field list is in
943
bibliographic context (first non-comment construct in the document,
944
after a document title if there is one).
950
Doctree elements: option_list, option_list_item, option_group, option,
951
option_string, option_argument, description.
953
Option lists are two-column lists of command-line options and
954
descriptions, documenting a program's options. For example::
957
-b Output both (this description is
959
-c arg Output just arg.
960
--long Output all day long.
962
-p This option has two paragraphs in the description.
965
This is the second. Blank lines may be omitted between
966
options (as above) or left in (as here and below).
968
--very-long-option A VMS-style option. Note the adjustment for
969
the required two spaces.
971
--an-even-longer-option
972
The description can also start on the next line.
974
-2, --two This option has two variants.
976
-f FILE, --file=FILE These two options are synonyms; both have
979
/V A VMS/DOS-style option.
981
There are several types of options recognized by reStructuredText:
983
- Short POSIX options consist of one dash and an option letter.
984
- Long POSIX options consist of two dashes and an option word; some
985
systems use a single dash.
986
- Old GNU-style "plus" options consist of one plus and an option
987
letter ("plus" options are deprecated now, their use discouraged).
988
- DOS/VMS options consist of a slash and an option letter or word.
990
Please note that both POSIX-style and DOS/VMS-style options may be
991
used by DOS or Windows software. These and other variations are
992
sometimes used mixed together. The names above have been chosen for
995
The syntax for short and long POSIX options is based on the syntax
996
supported by Python's getopt.py_ module, which implements an option
997
parser similar to the `GNU libc getopt_long()`_ function but with some
998
restrictions. There are many variant option systems, and
999
reStructuredText option lists do not support all of them.
1001
Although long POSIX and DOS/VMS option words may be allowed to be
1002
truncated by the operating system or the application when used on the
1003
command line, reStructuredText option lists do not show or support
1004
this with any special syntax. The complete option word should be
1005
given, supported by notes about truncation if and when applicable.
1007
Options may be followed by an argument placeholder, whose role and
1008
syntax should be explained in the description text. Either a space or
1009
an equals sign may be used as a delimiter between options and option
1010
argument placeholders; short options ("-" or "+" prefix only) may omit
1011
the delimiter. Option arguments may take one of two forms:
1013
- Begins with a letter (``[a-zA-Z]``) and subsequently consists of
1014
letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``).
1015
- Begins with an open-angle-bracket (``<``) and ends with a
1016
close-angle-bracket (``>``); any characters except angle brackets
1017
are allowed internally.
1019
Multiple option "synonyms" may be listed, sharing a single
1020
description. They must be separated by comma-space.
1022
There must be at least two spaces between the option(s) and the
1023
description. The description may contain multiple body elements. The
1024
first line after the option marker determines the indentation of the
1025
description. As with other types of lists, blank lines are required
1026
before the first option list item and after the last, but are optional
1027
between option entries.
1029
Syntax diagram (simplified)::
1031
+----------------------------+-------------+
1032
| option [" " argument] " " | description |
1033
+-------+--------------------+ |
1034
| (body elements)+ |
1035
+----------------------------------+
1041
Doctree element: literal_block.
1043
A paragraph consisting of two colons ("::") signifies that the
1044
following text block(s) comprise a literal block. The literal block
1045
must either be indented or quoted (see below). No markup processing
1046
is done within a literal block. It is left as-is, and is typically
1047
rendered in a monospaced typeface::
1049
This is a typical paragraph. An indented literal block follows.
1053
for a in [5,4,3,2,1]: # this is program code, shown as-is
1056
# a literal block continues until the indentation ends
1058
This text has returned to the indentation of the first paragraph,
1059
is outside of the literal block, and is therefore treated as an
1062
The paragraph containing only "::" will be completely removed from the
1063
output; no empty paragraph will remain.
1065
As a convenience, the "::" is recognized at the end of any paragraph.
1066
If immediately preceded by whitespace, both colons will be removed
1067
from the output (this is the "partially minimized" form). When text
1068
immediately precedes the "::", *one* colon will be removed from the
1069
output, leaving only one colon visible (i.e., "::" will be replaced by
1070
":"; this is the "fully minimized" form).
1072
In other words, these are all equivalent (please pay attention to the
1073
colons after "Paragraph"):
1083
2. Partially minimized form::
1089
3. Fully minimized form::
1095
All whitespace (including line breaks, but excluding minimum
1096
indentation for indented literal blocks) is preserved. Blank lines
1097
are required before and after a literal block, but these blank lines
1098
are not included as part of the literal block.
1101
Indented Literal Blocks
1102
```````````````````````
1104
Indented literal blocks are indicated by indentation relative to the
1105
surrounding text (leading whitespace on each line). The minimum
1106
indentation will be removed from each line of an indented literal
1107
block. The literal block need not be contiguous; blank lines are
1108
allowed between sections of indented text. The literal block ends
1109
with the end of the indentation.
1113
+------------------------------+
1115
| (ends with "::") |
1116
+------------------------------+
1117
+---------------------------+
1118
| indented literal block |
1119
+---------------------------+
1122
Quoted Literal Blocks
1123
`````````````````````
1125
Quoted literal blocks are unindented contiguous blocks of text where
1126
each line begins with the same non-alphanumeric printable 7-bit ASCII
1127
character [#]_. A blank line ends a quoted literal block. The
1128
quoting characters are preserved in the processed document.
1131
The following are all valid quoting characters::
1133
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
1135
Note that these are the same characters as are valid for title
1136
adornment of sections_.
1138
Possible uses include literate programming in Haskell and email
1145
> Why didn't I think of that?
1151
+------------------------------+
1153
| (ends with "::") |
1154
+------------------------------+
1155
+------------------------------+
1156
| ">" per-line-quoted |
1157
| ">" contiguous literal block |
1158
+------------------------------+
1164
Doctree elements: line_block, line. (New in Docutils 0.3.5.)
1166
Line blocks are useful for address blocks, verse (poetry, song
1167
lyrics), and unadorned lists, where the structure of lines is
1168
significant. Line blocks are groups of lines beginning with vertical
1169
bar ("|") prefixes. Each vertical bar prefix indicates a new line, so
1170
line breaks are preserved. Initial indents are also significant,
1171
resulting in a nested structure. Inline markup is supported.
1172
Continuation lines are wrapped portions of long lines; they begin with
1173
a space in place of the vertical bar. The left edge of a continuation
1174
line must be indented, but need not be aligned with the left edge of
1175
the text above it. A line block ends with a blank line.
1177
This example illustrates continuation lines::
1179
| Lend us a couple of bob till Thursday.
1180
| I'm absolutely skint.
1181
| But I'm expecting a postal order and I can pay you back
1182
as soon as it comes.
1185
This example illustrates the nesting of line blocks, indicated by the
1186
initial indentation of new lines::
1188
Take it away, Eric the Orchestra Leader!
1190
| A one, two, a one two three four
1192
| Half a bee, philosophically,
1193
| must, *ipso facto*, half not be.
1194
| But half the bee has got to be,
1195
| *vis a vis* its entity. D'you see?
1197
| But can a bee be said to be
1198
| or not to be an entire bee,
1199
| when half the bee is not a bee,
1200
| due to some ancient injury?
1206
+------+-----------------------+
1208
+------| continuation line |
1209
+-----------------------+
1215
Doctree element: block_quote, attribution.
1217
A text block that is indented relative to the preceding text, without
1218
markup indicating it to be a literal block, is a block quote. All
1219
markup processing (for body elements and inline markup) continues
1220
within the block quote::
1222
This is an ordinary paragraph, introducing a block quote.
1224
"It is my business to know things. That is my trade."
1228
If the final block of a block quote begins with "--", "---", or a true
1229
em-dash (flush left within the block quote), it is interpreted as an
1230
attribution. If the attribution consists of multiple lines, the left
1231
edges of the second and subsequent lines must align.
1233
Blank lines are required before and after a block quote, but these
1234
blank lines are not included as part of the block quote.
1238
+------------------------------+
1239
| (current level of |
1241
+------------------------------+
1242
+---------------------------+
1244
| (body elements)+ |
1246
| -- attribution text |
1248
+---------------------------+
1254
Doctree element: doctest_block.
1256
Doctest blocks are interactive Python sessions cut-and-pasted into
1257
docstrings. They are meant to illustrate usage by example, and
1258
provide an elegant and powerful testing environment via the `doctest
1259
module`_ in the Python standard library.
1261
Doctest blocks are text blocks which begin with ``">>> "``, the Python
1262
interactive interpreter main prompt, and end with a blank line.
1263
Doctest blocks are treated as a special case of literal blocks,
1264
without requiring the literal block syntax. If both are present, the
1265
literal block syntax takes priority over Doctest block syntax::
1267
This is an ordinary paragraph.
1269
>>> print 'this is a Doctest block'
1270
this is a Doctest block
1272
The following is a literal block::
1274
>>> This is not recognized as a doctest block by
1275
reStructuredText. It *will* be recognized by the doctest
1278
Indentation is not required for doctest blocks.
1284
Doctree elements: table, tgroup, colspec, thead, tbody, row, entry.
1286
ReStructuredText provides two syntaxes for delineating table cells:
1287
`Grid Tables`_ and `Simple Tables`_.
1289
As with other body elements, blank lines are required before and after
1290
tables. Tables' left edges should align with the left edge of
1291
preceding text blocks; if indented, the table is considered to be part
1294
Once isolated, each table cell is treated as a miniature document; the
1295
top and bottom cell boundaries act as delimiting blank lines. Each
1296
cell contains zero or more body elements. Cell contents may include
1297
left and/or right margins, which are removed before processing.
1303
Grid tables provide a complete table representation via grid-like
1304
"ASCII art". Grid tables allow arbitrary cell contents (body
1305
elements), and both row and column spans. However, grid tables can be
1306
cumbersome to produce, especially for simple data sets. The `Emacs
1307
table mode`_ is a tool that allows easy editing of grid tables, in
1308
Emacs. See `Simple Tables`_ for a simpler (but limited)
1311
Grid tables are described with a visual grid made up of the characters
1312
"-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines
1313
(row separators). The equals sign ("=") may be used to separate
1314
optional header rows from the table body (not supported by the `Emacs
1315
table mode`_). The vertical bar ("|") is used for vertical lines
1316
(column separators). The plus sign ("+") is used for intersections of
1317
horizontal and vertical lines. Example::
1319
+------------------------+------------+----------+----------+
1320
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
1321
| (header rows optional) | | | |
1322
+========================+============+==========+==========+
1323
| body row 1, column 1 | column 2 | column 3 | column 4 |
1324
+------------------------+------------+----------+----------+
1325
| body row 2 | Cells may span columns. |
1326
+------------------------+------------+---------------------+
1327
| body row 3 | Cells may | - Table cells |
1328
+------------------------+ span rows. | - contain |
1329
| body row 4 | | - body elements. |
1330
+------------------------+------------+---------------------+
1332
Some care must be taken with grid tables to avoid undesired
1333
interactions with cell text in rare cases. For example, the following
1334
table contains a cell in row 2 spanning from column 2 to column 4::
1336
+--------------+----------+-----------+-----------+
1337
| row 1, col 1 | column 2 | column 3 | column 4 |
1338
+--------------+----------+-----------+-----------+
1340
+--------------+----------+-----------+-----------+
1342
+--------------+----------+-----------+-----------+
1344
If a vertical bar is used in the text of that cell, it could have
1345
unintended effects if accidentally aligned with column boundaries::
1347
+--------------+----------+-----------+-----------+
1348
| row 1, col 1 | column 2 | column 3 | column 4 |
1349
+--------------+----------+-----------+-----------+
1350
| row 2 | Use the command ``ls | more``. |
1351
+--------------+----------+-----------+-----------+
1353
+--------------+----------+-----------+-----------+
1355
Several solutions are possible. All that is needed is to break the
1356
continuity of the cell outline rectangle. One possibility is to shift
1357
the text by adding an extra space before::
1359
+--------------+----------+-----------+-----------+
1360
| row 1, col 1 | column 2 | column 3 | column 4 |
1361
+--------------+----------+-----------+-----------+
1362
| row 2 | Use the command ``ls | more``. |
1363
+--------------+----------+-----------+-----------+
1365
+--------------+----------+-----------+-----------+
1367
Another possibility is to add an extra line to row 2::
1369
+--------------+----------+-----------+-----------+
1370
| row 1, col 1 | column 2 | column 3 | column 4 |
1371
+--------------+----------+-----------+-----------+
1372
| row 2 | Use the command ``ls | more``. |
1374
+--------------+----------+-----------+-----------+
1376
+--------------+----------+-----------+-----------+
1382
Simple tables provide a compact and easy to type but limited
1383
row-oriented table representation for simple data sets. Cell contents
1384
are typically single paragraphs, although arbitrary body elements may
1385
be represented in most cells. Simple tables allow multi-line rows (in
1386
all but the first column) and column spans, but not row spans. See
1387
`Grid Tables`_ above for a complete table representation.
1389
Simple tables are described with horizontal borders made up of "=" and
1390
"-" characters. The equals sign ("=") is used for top and bottom
1391
table borders, and to separate optional header rows from the table
1392
body. The hyphen ("-") is used to indicate column spans in a single
1393
row by underlining the joined columns, and may optionally be used to
1394
explicitly and/or visually separate rows.
1396
A simple table begins with a top border of equals signs with one or
1397
more spaces at each column boundary (two or more spaces recommended).
1398
Regardless of spans, the top border *must* fully describe all table
1399
columns. There must be at least two columns in the table (to
1400
differentiate it from section headers). The last of the optional
1401
header rows is underlined with '=', again with spaces at column
1402
boundaries. There may not be a blank line below the header row
1403
separator; it would be interpreted as the bottom border of the table.
1404
The bottom boundary of the table consists of '=' underlines, also with
1405
spaces at column boundaries. For example, here is a truth table, a
1406
three-column table with one header row and four body rows::
1417
Underlines of '-' may be used to indicate column spans by "filling in"
1418
column margins to join adjacent columns. Column span underlines must
1419
be complete (they must cover all columns) and align with established
1420
column boundaries. Text lines containing column span underlines may
1421
not contain any other text. A column span underline applies only to
1422
one row immediately above it. For example, here is a table with a
1423
column span in the header::
1436
Each line of text must contain spaces at column boundaries, except
1437
where cells have been joined by column spans. Each line of text
1438
starts a new row, except when there is a blank cell in the first
1439
column. In that case, that line of text is parsed as a continuation
1440
line. For this reason, cells in the first column of new rows (*not*
1441
continuation lines) *must* contain some text; blank cells would lead
1442
to a misinterpretation. An empty comment ("..") is sufficient and
1443
will be omitted from the processed output (see Comments_ below).
1444
Also, this mechanism limits cells in the first column to only one line
1445
of text. Use `grid tables`_ if this limitation is unacceptable.
1447
Underlines of '-' may also be used to visually separate rows, even if
1448
there are no column spans. This is especially useful in long tables,
1449
where rows are many lines long.
1451
Blank lines are permitted within simple tables. Their interpretation
1452
depends on the context. Blank lines *between* rows are ignored.
1453
Blank lines *within* multi-line rows may separate paragraphs or other
1454
body elements within cells.
1456
The rightmost column is unbounded; text may continue past the edge of
1457
the table (as indicated by the table borders). However, it is
1458
recommended that borders be made long enough to contain the entire
1461
The following example illustrates continuation lines (row 2 consists
1462
of two lines of text, and four lines for row 3), a blank line
1463
separating paragraphs (row 3, column 2), and text extending past the
1464
right edge of the table::
1469
1 Second column of row 1.
1470
2 Second column of row 2.
1471
Second line of paragraph.
1472
3 - Second column of row 3.
1474
- Second item in bullet
1475
list (row 3, column 2).
1479
Explicit Markup Blocks
1480
----------------------
1482
An explicit markup block is a text block:
1484
- whose first line begins with ".." followed by whitespace (the
1485
"explicit markup start"),
1486
- whose second and subsequent lines (if any) are indented relative to
1488
- which ends before an unindented line.
1490
Explicit markup blocks are analogous to bullet list items, with ".."
1491
as the bullet. The text on the lines immediately after the explicit
1492
markup start determines the indentation of the block body. The
1493
maximum common indentation is always removed from the second and
1494
subsequent lines of the block body. Therefore if the first construct
1495
fits in one line, and the indentation of the first and second
1496
constructs should differ, the first construct should not begin on the
1497
same line as the explicit markup start.
1499
Blank lines are required between explicit markup blocks and other
1500
elements, but are optional between explicit markup blocks where
1503
The explicit markup syntax is used for footnotes, citations, hyperlink
1504
targets, directives, substitution definitions, and comments.
1510
Doctree elements: footnote, label.
1512
Each footnote consists of an explicit markup start (".. "), a left
1513
square bracket, the footnote label, a right square bracket, and
1514
whitespace, followed by indented body elements. A footnote label can
1517
- a whole decimal number consisting of one or more digits,
1519
- a single "#" (denoting `auto-numbered footnotes`_),
1521
- a "#" followed by a simple reference name (an `autonumber label`_),
1524
- a single "*" (denoting `auto-symbol footnotes`_).
1526
The footnote content (body elements) must be consistently indented (by
1527
at least 3 spaces) and left-aligned. The first body element within a
1528
footnote may often begin on the same line as the footnote label.
1529
However, if the first element fits on one line and the indentation of
1530
the remaining elements differ, the first element must begin on the
1531
line after the footnote label. Otherwise, the difference in
1532
indentation will not be detected.
1534
Footnotes may occur anywhere in the document, not only at the end.
1535
Where and how they appear in the processed output depends on the
1538
Here is a manually numbered footnote::
1540
.. [1] Body elements go here.
1542
Each footnote automatically generates a hyperlink target pointing to
1543
itself. The text of the hyperlink target name is the same as that of
1544
the footnote label. `Auto-numbered footnotes`_ generate a number as
1545
their footnote label and reference name. See `Implicit Hyperlink
1546
Targets`_ for a complete description of the mechanism.
1550
+-------+-------------------------+
1551
| ".. " | "[" label "]" footnote |
1553
| (body elements)+ |
1554
+-------------------------+
1557
Auto-Numbered Footnotes
1558
.......................
1560
A number sign ("#") may be used as the first character of a footnote
1561
label to request automatic numbering of the footnote or footnote
1564
The first footnote to request automatic numbering is assigned the
1565
label "1", the second is assigned the label "2", and so on (assuming
1566
there are no manually numbered footnotes present; see `Mixed Manual
1567
and Auto-Numbered Footnotes`_ below). A footnote which has
1568
automatically received a label "1" generates an implicit hyperlink
1569
target with name "1", just as if the label was explicitly specified.
1571
.. _autonumber label: `autonumber labels`_
1573
A footnote may specify a label explicitly while at the same time
1574
requesting automatic numbering: ``[#label]``. These labels are called
1575
_`autonumber labels`. Autonumber labels do two things:
1577
- On the footnote itself, they generate a hyperlink target whose name
1578
is the autonumber label (doesn't include the "#").
1580
- They allow an automatically numbered footnote to be referred to more
1581
than once, as a footnote reference or hyperlink reference. For
1584
If [#note]_ is the first footnote reference, it will show up as
1585
"[1]". We can refer to it again as [#note]_ and again see
1586
"[1]". We can also refer to it as note_ (an ordinary internal
1587
hyperlink reference).
1589
.. [#note] This is the footnote labeled "note".
1591
The numbering is determined by the order of the footnotes, not by the
1592
order of the references. For footnote references without autonumber
1593
labels (``[#]_``), the footnotes and footnote references must be in
1594
the same relative order but need not alternate in lock-step. For
1597
[#]_ is a reference to footnote 1, and [#]_ is a reference to
1600
.. [#] This is footnote 1.
1601
.. [#] This is footnote 2.
1602
.. [#] This is footnote 3.
1604
[#]_ is a reference to footnote 3.
1606
Special care must be taken if footnotes themselves contain
1607
auto-numbered footnote references, or if multiple references are made
1608
in close proximity. Footnotes and references are noted in the order
1609
they are encountered in the document, which is not necessarily the
1610
same as the order in which a person would read them.
1613
Auto-Symbol Footnotes
1614
.....................
1616
An asterisk ("*") may be used for footnote labels to request automatic
1617
symbol generation for footnotes and footnote references. The asterisk
1618
may be the only character in the label. For example::
1620
Here is a symbolic footnote reference: [*]_.
1622
.. [*] This is the footnote.
1624
A transform will insert symbols as labels into corresponding footnotes
1625
and footnote references. The number of references must be equal to
1626
the number of footnotes. One symbol footnote cannot have multiple
1629
The standard Docutils system uses the following symbols for footnote
1632
- asterisk/star ("*")
1633
- dagger (HTML character entity "†", Unicode U+02020)
1634
- double dagger ("‡"/U+02021)
1635
- section mark ("§"/U+000A7)
1636
- pilcrow or paragraph mark ("¶"/U+000B6)
1638
- spade suit ("♠"/U+02660)
1639
- heart suit ("♥"/U+02665)
1640
- diamond suit ("♦"/U+02666)
1641
- club suit ("♣"/U+02663)
1643
.. [#] This list was inspired by the list of symbols for "Note
1644
Reference Marks" in The Chicago Manual of Style, 14th edition,
1645
section 12.51. "Parallels" ("||") were given in CMoS instead of
1646
the pilcrow. The last four symbols (the card suits) were added
1649
If more than ten symbols are required, the same sequence will be
1650
reused, doubled and then tripled, and so on ("**" etc.).
1652
.. Note:: When using auto-symbol footnotes, the choice of output
1653
encoding is important. Many of the symbols used are not encodable
1654
in certain common text encodings such as Latin-1 (ISO 8859-1). The
1655
use of UTF-8 for the output encoding is recommended. An
1656
alternative for HTML and XML output is to use the
1657
"xmlcharrefreplace" `output encoding error handler`__.
1659
__ ../../user/config.html#output-encoding-error-handler
1662
Mixed Manual and Auto-Numbered Footnotes
1663
........................................
1665
Manual and automatic footnote numbering may both be used within a
1666
single document, although the results may not be expected. Manual
1667
numbering takes priority. Only unused footnote numbers are assigned
1668
to auto-numbered footnotes. The following example should be
1671
[2]_ will be "2" (manually numbered),
1672
[#]_ will be "3" (anonymous auto-numbered), and
1673
[#label]_ will be "1" (labeled auto-numbered).
1675
.. [2] This footnote is labeled manually, so its number is fixed.
1677
.. [#label] This autonumber-labeled footnote will be labeled "1".
1678
It is the first auto-numbered footnote and no other footnote
1679
with label "1" exists. The order of the footnotes is used to
1680
determine numbering, not the order of the footnote references.
1682
.. [#] This footnote will be labeled "3". It is the second
1683
auto-numbered footnote, but footnote label "2" is already used.
1689
Citations are identical to footnotes except that they use only
1690
non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation
1691
labels are simple `reference names`_ (case-insensitive single words
1692
consisting of alphanumerics plus internal hyphens, underscores, and
1693
periods; no whitespace). Citations may be rendered separately and
1694
differently from footnotes. For example::
1696
Here is a citation reference: [CIT2002]_.
1698
.. [CIT2002] This is the citation. It's just like a footnote,
1699
except the label is textual.
1707
Doctree element: target.
1709
These are also called _`explicit hyperlink targets`, to differentiate
1710
them from `implicit hyperlink targets`_ defined below.
1712
Hyperlink targets identify a location within or outside of a document,
1713
which may be linked to by `hyperlink references`_.
1715
Hyperlink targets may be named or anonymous. Named hyperlink targets
1716
consist of an explicit markup start (".. "), an underscore, the
1717
reference name (no trailing underscore), a colon, whitespace, and a
1720
.. _hyperlink-name: link-block
1722
Reference names are whitespace-neutral and case-insensitive. See
1723
`Reference Names`_ for details and examples.
1725
Anonymous hyperlink targets consist of an explicit markup start
1726
(".. "), two underscores, a colon, whitespace, and a link block; there
1727
is no reference name::
1729
.. __: anonymous-hyperlink-target-link-block
1731
An alternate syntax for anonymous hyperlinks consists of two
1732
underscores, a space, and a link block::
1734
__ anonymous-hyperlink-target-link-block
1736
See `Anonymous Hyperlinks`_ below.
1738
There are three types of hyperlink targets: internal, external, and
1741
1. _`Internal hyperlink targets` have empty link blocks. They provide
1742
an end point allowing a hyperlink to connect one place to another
1743
within a document. An internal hyperlink target points to the
1744
element following the target. For example::
1746
Clicking on this internal hyperlink will take us to the target_
1751
The hyperlink target above points to this paragraph.
1753
Internal hyperlink targets may be "chained". Multiple adjacent
1754
internal hyperlink targets all point to the same element::
1759
The targets "target1" and "target2" are synonyms; they both
1760
point to this paragraph.
1762
If the element "pointed to" is an external hyperlink target (with a
1763
URI in its link block; see #2 below) the URI from the external
1764
hyperlink target is propagated to the internal hyperlink targets;
1765
they will all "point to" the same URI. There is no need to
1766
duplicate a URI. For example, all three of the following hyperlink
1767
targets refer to the same URI::
1769
.. _Python DOC-SIG mailing list archive:
1771
.. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/
1773
An inline form of internal hyperlink target is available; see
1774
`Inline Internal Targets`_.
1776
2. _`External hyperlink targets` have an absolute or relative URI or
1777
email address in their link blocks. For example, take the
1780
See the Python_ home page for info.
1782
`Write to me`_ with your questions.
1784
.. _Python: http://www.python.org
1785
.. _Write to me: jdoe@example.com
1787
After processing into HTML, the hyperlinks might be expressed as::
1789
See the <a href="http://www.python.org">Python</a> home page
1792
<a href="mailto:jdoe@example.com">Write to me</a> with your
1795
An external hyperlink's URI may begin on the same line as the
1796
explicit markup start and target name, or it may begin in an
1797
indented text block immediately following, with no intervening
1798
blank lines. If there are multiple lines in the link block, they
1799
are concatenated. Any whitespace is removed (whitespace is
1800
permitted to allow for line wrapping). The following external
1801
hyperlink targets are equivalent::
1803
.. _one-liner: http://docutils.sourceforge.net/rst.html
1805
.. _starts-on-this-line: http://
1806
docutils.sourceforge.net/rst.html
1810
sourceforge.net/rst.html
1812
If an external hyperlink target's URI contains an underscore as its
1813
last character, it must be escaped to avoid being mistaken for an
1814
indirect hyperlink target::
1816
This link_ refers to a file called ``underscore_``.
1818
.. _link: underscore\_
1820
It is possible (although not generally recommended) to include URIs
1821
directly within hyperlink references. See `Embedded URIs`_ below.
1823
3. _`Indirect hyperlink targets` have a hyperlink reference in their
1824
link blocks. In the following example, target "one" indirectly
1825
references whatever target "two" references, and target "two"
1826
references target "three", an internal hyperlink target. In
1827
effect, all three reference the same thing::
1833
Just as with `hyperlink references`_ anywhere else in a document,
1834
if a phrase-reference is used in the link block it must be enclosed
1835
in backquotes. As with `external hyperlink targets`_, the link
1836
block of an indirect hyperlink target may begin on the same line as
1837
the explicit markup start or the next line. It may also be split
1838
over multiple lines, in which case the lines are joined with
1839
whitespace before being normalized.
1841
For example, the following indirect hyperlink targets are
1844
.. _one-liner: `A HYPERLINK`_
1850
If the reference name contains any colons, either:
1852
- the phrase must be enclosed in backquotes::
1854
.. _`FAQTS: Computers: Programming: Languages: Python`:
1855
http://python.faqts.com/
1857
- or the colon(s) must be backslash-escaped in the link target::
1859
.. _Chapter One\: "Tadpole Days":
1861
It's not easy being green...
1863
See `Implicit Hyperlink Targets`_ below for the resolution of
1864
duplicate reference names.
1868
+-------+----------------------+
1869
| ".. " | "_" name ":" link |
1872
+----------------------+
1875
Anonymous Hyperlinks
1876
....................
1878
The `World Wide Web Consortium`_ recommends in its `HTML Techniques
1879
for Web Content Accessibility Guidelines`_ that authors should
1880
"clearly identify the target of each link." Hyperlink references
1881
should be as verbose as possible, but duplicating a verbose hyperlink
1882
name in the target is onerous and error-prone. Anonymous hyperlinks
1883
are designed to allow convenient verbose hyperlink references, and are
1884
analogous to `Auto-Numbered Footnotes`_. They are particularly useful
1885
in short or one-off documents. However, this feature is easily abused
1886
and can result in unreadable plaintext and/or unmaintainable
1887
documents. Caution is advised.
1889
Anonymous `hyperlink references`_ are specified with two underscores
1892
See `the web site of my favorite programming language`__.
1894
Anonymous targets begin with ".. __:"; no reference name is required
1897
.. __: http://www.python.org
1899
As a convenient alternative, anonymous targets may begin with "__"
1902
__ http://www.python.org
1904
The reference name of the reference is not used to match the reference
1905
to its target. Instead, the order of anonymous hyperlink references
1906
and targets within the document is significant: the first anonymous
1907
reference will link to the first anonymous target. The number of
1908
anonymous hyperlink references in a document must match the number of
1909
anonymous targets. For readability, it is recommended that targets be
1910
kept close to references. Take care when editing text containing
1911
anonymous references; adding, removing, and rearranging references
1912
require attention to the order of corresponding targets.
1918
Doctree elements: depend on the directive.
1920
Directives are an extension mechanism for reStructuredText, a way of
1921
adding support for new constructs without adding new primary syntax
1922
(directives may support additional syntax locally). All standard
1923
directives (those implemented and registered in the reference
1924
reStructuredText parser) are described in the `reStructuredText
1925
Directives`_ document, and are always available. Any other directives
1926
are domain-specific, and may require special action to make them
1927
available when processing the document.
1929
For example, here's how an image_ may be placed::
1931
.. image:: mylogo.jpeg
1933
A figure_ (a graphic with a caption) may placed like this::
1935
.. figure:: larch.png
1939
An admonition_ (note, caution, etc.) contains other body elements::
1941
.. note:: This is a paragraph
1943
- Here is a bullet list.
1945
Directives are indicated by an explicit markup start (".. ") followed
1946
by the directive type, two colons, and whitespace (together called the
1947
"directive marker"). Directive types are case-insensitive single
1948
words (alphanumerics plus internal hyphens, underscores, and periods;
1949
no whitespace). Two colons are used after the directive type for
1952
- Two colons are distinctive, and unlikely to be used in common text.
1954
- Two colons avoids clashes with common comment text like::
1956
.. Danger: modify at your own risk!
1958
- If an implementation of reStructuredText does not recognize a
1959
directive (i.e., the directive-handler is not installed), a level-3
1960
(error) system message is generated, and the entire directive block
1961
(including the directive itself) will be included as a literal
1962
block. Thus "::" is a natural choice.
1964
The directive block is consists of any text on the first line of the
1965
directive after the directive marker, and any subsequent indented
1966
text. The interpretation of the directive block is up to the
1967
directive code. There are three logical parts to the directive block:
1969
1. Directive arguments.
1970
2. Directive options.
1971
3. Directive content.
1973
Individual directives can employ any combination of these parts.
1974
Directive arguments can be filesystem paths, URLs, title text, etc.
1975
Directive options are indicated using `field lists`_; the field names
1976
and contents are directive-specific. Arguments and options must form
1977
a contiguous block beginning on the first or second line of the
1978
directive; a blank line indicates the beginning of the directive
1979
content block. If either arguments and/or options are employed by the
1980
directive, a blank line must separate them from the directive content.
1981
The "figure" directive employs all three parts::
1983
.. figure:: larch.png
1988
Simple directives may not require any content. If a directive that
1989
does not employ a content block is followed by indented text anyway,
1990
it is an error. If a block quote should immediately follow a
1991
directive, use an empty comment in-between (see Comments_ below).
1993
Actions taken in response to directives and the interpretation of text
1994
in the directive content block or subsequent text block(s) are
1995
directive-dependent. See `reStructuredText Directives`_ for details.
1997
Directives are meant for the arbitrary processing of their contents,
1998
which can be transformed into something possibly unrelated to the
1999
original text. It may also be possible for directives to be used as
2000
pragmas, to modify the behavior of the parser, such as to experiment
2001
with alternate syntax. There is no parser support for this
2002
functionality at present; if a reasonable need for pragma directives
2003
is found, they may be supported.
2005
Directives do not generate "directive" elements; they are a *parser
2006
construct* only, and have no intrinsic meaning outside of
2007
reStructuredText. Instead, the parser will transform recognized
2008
directives into (possibly specialized) document elements. Unknown
2009
directives will trigger level-3 (error) system messages.
2013
+-------+-------------------------------+
2014
| ".. " | directive type "::" directive |
2017
+-------------------------------+
2020
Substitution Definitions
2021
````````````````````````
2023
Doctree element: substitution_definition.
2025
Substitution definitions are indicated by an explicit markup start
2026
(".. ") followed by a vertical bar, the substitution text, another
2027
vertical bar, whitespace, and the definition block. Substitution text
2028
may not begin or end with whitespace. A substitution definition block
2029
contains an embedded inline-compatible directive (without the leading
2030
".. "), such as "image_" or "replace_". For example::
2032
The |biohazard| symbol must be used on containers used to
2033
dispose of medical waste.
2035
.. |biohazard| image:: biohazard.png
2037
It is an error for a substitution definition block to directly or
2038
indirectly contain a circular substitution reference.
2040
`Substitution references`_ are replaced in-line by the processed
2041
contents of the corresponding definition (linked by matching
2042
substitution text). Matches are case-sensitive but forgiving; if no
2043
exact match is found, a case-insensitive comparison is attempted.
2045
Substitution definitions allow the power and flexibility of
2046
block-level directives_ to be shared by inline text. They are a way
2047
to include arbitrarily complex inline structures within text, while
2048
keeping the details out of the flow of text. They are the equivalent
2049
of SGML/XML's named entities or programming language macros.
2051
Without the substitution mechanism, every time someone wants an
2052
application-specific new inline structure, they would have to petition
2053
for a syntax change. In combination with existing directive syntax,
2054
any inline structure can be coded without new syntax (except possibly
2059
+-------+-----------------------------------------------------+
2060
| ".. " | "|" substitution text "| " directive type "::" data |
2061
+-------+ directive block |
2063
+-----------------------------------------------------+
2065
Following are some use cases for the substitution mechanism. Please
2066
note that most of the embedded directives shown are examples only and
2067
have not been implemented.
2070
Substitution references may be used to associate ambiguous text
2071
with a unique object identifier.
2073
For example, many sites may wish to implement an inline "user"
2076
|Michael| and |Jon| are our widget-wranglers.
2078
.. |Michael| user:: mjones
2081
Depending on the needs of the site, this may be used to index the
2082
document for later searching, to hyperlink the inline text in
2083
various ways (mailto, homepage, mouseover Javascript with profile
2084
and contact information, etc.), or to customize presentation of
2085
the text (include username in the inline text, include an icon
2086
image with a link next to the text, make the text bold or a
2087
different color, etc.).
2089
The same approach can be used in documents which frequently refer
2090
to a particular type of objects with unique identifiers but
2091
ambiguous common names. Movies, albums, books, photos, court
2092
cases, and laws are possible. For example::
2094
|The Transparent Society| offers a fascinating alternate view
2097
.. |The Transparent Society| book:: isbn=0738201448
2099
Classes or functions, in contexts where the module or class names
2100
are unclear and/or interpreted text cannot be used, are another
2103
4XSLT has the convenience method |runString|, so you don't
2104
have to mess with DOM objects if all you want is the
2107
.. |runString| function:: module=xml.xslt class=Processor
2110
Images are a common use for substitution references::
2112
West led the |H| 3, covered by dummy's |H| Q, East's |H| K,
2113
and trumped in hand with the |S| 2.
2115
.. |H| image:: /images/heart.png
2118
.. |S| image:: /images/spade.png
2122
* |Red light| means stop.
2123
* |Green light| means go.
2124
* |Yellow light| means go really fast.
2126
.. |Red light| image:: red_light.png
2127
.. |Green light| image:: green_light.png
2128
.. |Yellow light| image:: yellow_light.png
2130
|-><-| is the official symbol of POEE_.
2132
.. |-><-| image:: discord.png
2133
.. _POEE: http://www.poee.org/
2135
The "image_" directive has been implemented.
2138
Substitution references may be used to associate inline text with
2139
an externally defined presentation style::
2141
Even |the text in Texas| is big.
2143
.. |the text in Texas| style:: big
2145
The style name may be meaningful in the context of some particular
2146
output format (CSS class name for HTML output, LaTeX style name
2147
for LaTeX, etc), or may be ignored for other output formats (such
2150
.. @@@ This needs to be rethought & rewritten or removed:
2152
Interpreted text is unsuitable for this purpose because the set
2153
of style names cannot be predefined - it is the domain of the
2154
content author, not the author of the parser and output
2155
formatter - and there is no way to associate a style name
2156
argument with an interpreted text style role. Also, it may be
2157
desirable to use the same mechanism for styling blocks::
2160
At Bob's Underwear Shop, we'll do anything to get in
2163
.. style:: disclaimer
2164
All rights reversed. Reprint what you like.
2166
.. [#] There may be sufficient need for a "style" mechanism to
2167
warrant simpler syntax such as an extension to the interpreted
2168
text role syntax. The substitution mechanism is cumbersome for
2169
simple text styling.
2172
Inline markup may be used for later processing by a template
2173
engine. For example, a Zope_ author might write::
2175
Welcome back, |name|!
2177
.. |name| tal:: replace user/getUserName
2179
After processing, this ZPT output would result::
2182
<span tal:replace="user/getUserName">name</span>!
2184
Zope would then transform this to something like "Welcome back,
2185
David!" during a session with an actual user.
2188
The substitution mechanism may be used for simple macro
2189
substitution. This may be appropriate when the replacement text
2190
is repeated many times throughout one or more documents,
2191
especially if it may need to change later. A short example is
2192
unavoidably contrived::
2194
|RST| is a little annoying to type over and over, especially
2195
when writing about |RST| itself, and spelling out the
2196
bicapitalized word |RST| every time isn't really necessary for
2197
|RST| source readability.
2199
.. |RST| replace:: reStructuredText_
2200
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
2202
Substitution is also appropriate when the replacement text cannot
2203
be represented using other inline constructs, or is obtrusively
2206
But still, that's nothing compared to a name like
2209
.. |j2ee-cas| replace::
2210
the Java `TM`:super: 2 Platform, Enterprise Edition Client
2212
__ http://developer.java.sun.com/developer/earlyAccess/
2215
The "replace_" directive has been implemented.
2221
Doctree element: comment.
2223
Arbitrary indented text may follow the explicit markup start and will
2224
be processed as a comment element. No further processing is done on
2225
the comment block text; a comment contains a single "text blob".
2226
Depending on the output formatter, comments may be removed from the
2227
processed output. The only restriction on comments is that they not
2228
use the same syntax as any of the other explicit markup constructs:
2229
substitution definitions, directives, footnotes, citations, or
2230
hyperlink targets. To ensure that none of the other explicit markup
2231
constructs is recognized, leave the ".." on a line by itself::
2233
.. This is a comment
2243
An explicit markup start followed by a blank line and nothing else
2244
(apart from whitespace) is an "empty comment". It serves to terminate
2245
a preceding construct, and does **not** consume any indented text
2246
following. To have a block quote follow a list or any indented
2247
construct, insert an unindented empty comment in-between.
2251
+-------+----------------------+
2255
+----------------------+
2258
Implicit Hyperlink Targets
2259
==========================
2261
Implicit hyperlink targets are generated by section titles, footnotes,
2262
and citations, and may also be generated by extension constructs.
2263
Implicit hyperlink targets otherwise behave identically to explicit
2264
`hyperlink targets`_.
2266
Problems of ambiguity due to conflicting duplicate implicit and
2267
explicit reference names are avoided by following this procedure:
2269
1. `Explicit hyperlink targets`_ override any implicit targets having
2270
the same reference name. The implicit hyperlink targets are
2271
removed, and level-1 (info) system messages are inserted.
2273
2. Duplicate implicit hyperlink targets are removed, and level-1
2274
(info) system messages inserted. For example, if two or more
2275
sections have the same title (such as "Introduction" subsections of
2276
a rigidly-structured document), there will be duplicate implicit
2279
3. Duplicate explicit hyperlink targets are removed, and level-2
2280
(warning) system messages are inserted. Exception: duplicate
2281
`external hyperlink targets`_ (identical hyperlink names and
2282
referenced URIs) do not conflict, and are not removed.
2284
System messages are inserted where target links have been removed.
2285
See "Error Handling" in `PEP 258`_.
2287
The parser must return a set of *unique* hyperlink targets. The
2288
calling software (such as the Docutils_) can warn of unresolvable
2289
links, giving reasons for the messages.
2295
In reStructuredText, inline markup applies to words or phrases within
2296
a text block. The same whitespace and punctuation that serves to
2297
delimit words in written text is used to delimit the inline markup
2298
syntax constructs. The text within inline markup may not begin or end
2299
with whitespace. Arbitrary `character-level inline markup`_ is
2300
supported although not encouraged. Inline markup cannot be nested.
2302
There are nine inline markup constructs. Five of the constructs use
2303
identical start-strings and end-strings to indicate the markup:
2306
- `strong emphasis`_: "**"
2307
- `interpreted text`_: "`"
2308
- `inline literals`_: "``"
2309
- `substitution references`_: "|"
2311
Three constructs use different start-strings and end-strings:
2313
- `inline internal targets`_: "_`" and "`"
2314
- `footnote references`_: "[" and "]_"
2315
- `hyperlink references`_: "`" and "\`_" (phrases), or just a
2316
trailing "_" (single words)
2318
`Standalone hyperlinks`_ are recognized implicitly, and use no extra
2321
The inline markup start-string and end-string recognition rules are as
2322
follows. If any of the conditions are not met, the start-string or
2323
end-string will not be recognized or processed.
2325
1. Inline markup start-strings must start a text block or be
2326
immediately preceded by whitespace or one of::
2330
2. Inline markup start-strings must be immediately followed by
2333
3. Inline markup end-strings must be immediately preceded by
2336
4. Inline markup end-strings must end a text block or be immediately
2337
followed by whitespace or one of::
2339
' " ) ] } > - / : . , ; ! ? \
2341
5. If an inline markup start-string is immediately preceded by a
2342
single or double quote, "(", "[", "{", or "<", it must not be
2343
immediately followed by the corresponding single or double quote,
2344
")", "]", "}", or ">".
2346
6. An inline markup end-string must be separated by at least one
2347
character from the start-string.
2349
7. An unescaped backslash preceding a start-string or end-string will
2350
disable markup recognition, except for the end-string of `inline
2351
literals`_. See `Escaping Mechanism`_ above for details.
2353
For example, none of the following are recognized as containing inline
2354
markup start-strings:
2356
- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_*
2357
- double asterisks: ** a**b O(N**2) etc.
2358
- backquotes: ` `` etc.
2359
- underscores: _ __ __init__ __init__() etc.
2360
- vertical bars: | || etc.
2362
It may be desirable to use inline literals for some of these anyhow,
2363
especially if they represent code snippets. It's a judgment call.
2365
These cases *do* require either literal-quoting or escaping to avoid
2368
*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt
2370
The inline markup recognition rules were devised intentionally to
2371
allow 90% of non-markup uses of "*", "`", "_", and "|" *without*
2372
resorting to backslashes. For 9 of the remaining 10%, use inline
2373
literals or literal blocks::
2375
"``\*``" -> "\*" (possibly in another font or quoted)
2377
Only those who understand the escaping and inline markup rules should
2378
attempt the remaining 1%. ;-)
2380
Inline markup delimiter characters are used for multiple constructs,
2381
so to avoid ambiguity there must be a specific recognition order for
2382
each character. The inline markup recognition order is as follows:
2384
- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_
2387
- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_
2388
(leading "_`", trailing "`"), are mutually independent, and are
2389
recognized before phrase `hyperlink references`_ (leading "`",
2390
trailing "\`_") and `interpreted text`_ ("`").
2392
- Trailing underscores: Footnote references ("[" + label + "]_") and
2393
simple `hyperlink references`_ (name + trailing "_") are mutually
2396
- Vertical bars: `Substitution references`_ ("|") are independently
2399
- `Standalone hyperlinks`_ are the last to be recognized.
2402
Character-Level Inline Markup
2403
-----------------------------
2405
It is possible to mark up individual characters within a word with
2406
backslash escapes (see `Escaping Mechanism`_ above). Backslash
2407
escapes can be used to allow arbitrary text to immediately follow
2410
Python ``list``\s use square bracket syntax.
2412
The backslash will disappear from the processed document. The word
2413
"list" will appear as inline literal text, and the letter "s" will
2414
immediately follow it as normal text, with no space in-between.
2416
Arbitrary text may immediately precede inline markup using
2417
backslash-escaped whitespace::
2419
Possible in *re*\ ``Structured``\ *Text*, though not encouraged.
2421
The backslashes and spaces separating "re", "Structured", and "Text"
2422
above will disappear from the processed document.
2426
The use of backslash-escapes for character-level inline markup is
2427
not encouraged. Such use is ugly and detrimental to the
2428
unprocessed document's readability. Please use this feature
2429
sparingly and only where absolutely necessary.
2435
Doctree element: emphasis.
2437
Start-string = end-string = "*".
2439
Text enclosed by single asterisk characters is emphasized::
2441
This is *emphasized text*.
2443
Emphasized text is typically displayed in italics.
2449
Doctree element: strong.
2451
Start-string = end-string = "**".
2453
Text enclosed by double-asterisks is emphasized strongly::
2455
This is **strong text**.
2457
Strongly emphasized text is typically displayed in boldface.
2463
Doctree element: depends on the explicit or implicit role and
2466
Start-string = end-string = "`".
2468
Interpreted text is text that is meant to be related, indexed, linked,
2469
summarized, or otherwise processed, but the text itself is typically
2470
left alone. Interpreted text is enclosed by single backquote
2473
This is `interpreted text`.
2475
The "role" of the interpreted text determines how the text is
2476
interpreted. The role may be inferred implicitly (as above; the
2477
"default role" is used) or indicated explicitly, using a role marker.
2478
A role marker consists of a colon, the role name, and another colon.
2479
A role name is a single word consisting of alphanumerics plus internal
2480
hyphens, underscores, and periods; no whitespace or other characters
2481
are allowed. A role marker is either a prefix or a suffix to the
2482
interpreted text, whichever reads better; it's up to the author::
2484
:role:`interpreted text`
2486
`interpreted text`:role:
2488
Interpreted text allows extensions to the available inline descriptive
2489
markup constructs. To emphasis_, `strong emphasis`_, `inline
2490
literals`_, and `hyperlink references`_, we can add "title reference",
2491
"index entry", "acronym", "class", "red", "blinking" or anything else
2492
we want. Only pre-determined roles are recognized; unknown roles will
2493
generate errors. A core set of standard roles is implemented in the
2494
reference parser; see `reStructuredText Interpreted Text Roles`_ for
2495
individual descriptions. In addition, applications may support
2502
Doctree element: literal.
2504
Start-string = end-string = "``".
2506
Text enclosed by double-backquotes is treated as inline literals::
2508
This text is an example of ``inline literals``.
2510
Inline literals may contain any characters except two adjacent
2511
backquotes in an end-string context (according to the recognition
2512
rules above). No markup interpretation (including backslash-escape
2513
interpretation) is done within inline literals.
2515
Line breaks are *not* preserved in inline literals. Although a
2516
reStructuredText parser will preserve runs of spaces in its output,
2517
the final representation of the processed document is dependent on the
2518
output formatter, thus the preservation of whitespace cannot be
2519
guaranteed. If the preservation of line breaks and/or other
2520
whitespace is important, `literal blocks`_ should be used.
2522
Inline literals are useful for short code snippets. For example::
2524
The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches
2525
floating-point numbers (without exponents).
2528
Hyperlink References
2529
--------------------
2531
Doctree element: reference.
2533
- Named hyperlink references:
2535
- Start-string = "" (empty string), end-string = "_".
2536
- Start-string = "`", end-string = "\`_". (Phrase references.)
2538
- Anonymous hyperlink references:
2540
- Start-string = "" (empty string), end-string = "__".
2541
- Start-string = "`", end-string = "\`__". (Phrase references.)
2543
Hyperlink references are indicated by a trailing underscore, "_",
2544
except for `standalone hyperlinks`_ which are recognized
2545
independently. The underscore can be thought of as a right-pointing
2546
arrow. The trailing underscores point away from hyperlink references,
2547
and the leading underscores point toward `hyperlink targets`_.
2549
Hyperlinks consist of two parts. In the text body, there is a source
2550
link, a reference name with a trailing underscore (or two underscores
2551
for `anonymous hyperlinks`_)::
2553
See the Python_ home page for info.
2555
A target link with a matching reference name must exist somewhere else
2556
in the document. See `Hyperlink Targets`_ for a full description).
2558
`Anonymous hyperlinks`_ (which see) do not use reference names to
2559
match references to targets, but otherwise behave similarly to named
2566
A hyperlink reference may directly embed a target URI inline, within
2567
angle brackets ("<...>") as follows::
2569
See the `Python home page <http://www.python.org>`_ for info.
2571
This is exactly equivalent to::
2573
See the `Python home page`_ for info.
2575
.. _Python home page: http://www.python.org
2577
The bracketed URI must be preceded by whitespace and be the last text
2578
before the end string. With a single trailing underscore, the
2579
reference is named and the same target URI may be referred to again.
2581
With two trailing underscores, the reference and target are both
2582
anonymous, and the target cannot be referred to again. These are
2583
"one-off" hyperlinks. For example::
2585
`RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2586
2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
2587
define the syntax of URIs.
2591
`RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs.
2593
__ http://www.rfc-editor.org/rfc/rfc2396.txt
2594
__ http://www.rfc-editor.org/rfc/rfc2732.txt
2596
If reference text happens to end with angle-bracketed text that is
2597
*not* a URI, the open-angle-bracket needs to be backslash-escaped.
2598
For example, here is a reference to a title describing a tag::
2600
See `HTML Element: \<a>`_ below.
2602
The reference text may also be omitted, in which case the URI will be
2603
duplicated for use as the reference text. This is useful for relative
2604
URIs where the address or file name is also the desired reference
2607
See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__
2612
This construct offers easy authoring and maintenance of hyperlinks
2613
at the expense of general readability. Inline URIs, especially
2614
long ones, inevitably interrupt the natural flow of text. For
2615
documents meant to be read in source form, the use of independent
2616
block-level `hyperlink targets`_ is **strongly recommended**. The
2617
embedded URI construct is most suited to documents intended *only*
2618
to be read in processed form.
2621
Inline Internal Targets
2622
------------------------
2624
Doctree element: target.
2626
Start-string = "_`", end-string = "`".
2628
Inline internal targets are the equivalent of explicit `internal
2629
hyperlink targets`_, but may appear within running text. The syntax
2630
begins with an underscore and a backquote, is followed by a hyperlink
2631
name or phrase, and ends with a backquote. Inline internal targets
2632
may not be anonymous.
2634
For example, the following paragraph contains a hyperlink target named
2637
Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it?
2639
See `Implicit Hyperlink Targets`_ for the resolution of duplicate
2646
Doctree element: footnote_reference.
2648
Start-string = "[", end-string = "]_".
2650
Each footnote reference consists of a square-bracketed label followed
2651
by a trailing underscore. Footnote labels are one of:
2653
- one or more digits (i.e., a number),
2655
- a single "#" (denoting `auto-numbered footnotes`_),
2657
- a "#" followed by a simple reference name (an `autonumber label`_),
2660
- a single "*" (denoting `auto-symbol footnotes`_).
2666
.. [1] Read The Fine Manual
2672
Doctree element: citation_reference.
2674
Start-string = "[", end-string = "]_".
2676
Each citation reference consists of a square-bracketed label followed
2677
by a trailing underscore. Citation labels are simple `reference
2678
names`_ (case-insensitive single words, consisting of alphanumerics
2679
plus internal hyphens, underscores, and periods; no whitespace).
2683
Here is a citation reference: [CIT2002]_.
2685
See Citations_ for the citation itself.
2688
Substitution References
2689
-----------------------
2691
Doctree element: substitution_reference, reference.
2693
Start-string = "|", end-string = "|" (optionally followed by "_" or
2696
Vertical bars are used to bracket the substitution reference text. A
2697
substitution reference may also be a hyperlink reference by appending
2698
a "_" (named) or "__" (anonymous) suffix; the substitution text is
2699
used for the reference text in the named case.
2701
The processing system replaces substitution references with the
2702
processed contents of the corresponding `substitution definitions`_
2703
(which see for the definition of "correspond"). Substitution
2704
definitions produce inline-compatible elements.
2708
This is a simple |substitution reference|. It will be replaced by
2709
the processing system.
2711
This is a combination |substitution and hyperlink reference|_. In
2712
addition to being replaced, the replacement text or element will
2713
refer to the "substitution and hyperlink reference" target.
2716
Standalone Hyperlinks
2717
---------------------
2719
Doctree element: reference.
2721
Start-string = end-string = "" (empty string).
2723
A URI (absolute URI [#URI]_ or standalone email address) within a text
2724
block is treated as a general external hyperlink with the URI itself
2725
as the link's text. For example::
2727
See http://www.python.org for info.
2729
would be marked up in HTML as::
2731
See <a href="http://www.python.org">http://www.python.org</a> for
2734
Two forms of URI are recognized:
2736
1. Absolute URIs. These consist of a scheme, a colon (":"), and a
2737
scheme-specific part whose interpretation depends on the scheme.
2739
The scheme is the name of the protocol, such as "http", "ftp",
2740
"mailto", or "telnet". The scheme consists of an initial letter,
2741
followed by letters, numbers, and/or "+", "-", ".". Recognition is
2742
limited to known schemes, per the `Official IANA Registry of URI
2743
Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_.
2745
The scheme-specific part of the resource identifier may be either
2746
hierarchical or opaque:
2748
- Hierarchical identifiers begin with one or two slashes and may
2749
use slashes to separate hierarchical components of the path.
2750
Examples are web pages and FTP sites::
2752
http://www.python.org
2754
ftp://ftp.python.org/pub/python
2756
- Opaque identifiers do not begin with slashes. Examples are
2757
email addresses and newsgroups::
2759
mailto:someone@somewhere.com
2761
news:comp.lang.python
2763
With queries, fragments, and %-escape sequences, URIs can become
2764
quite complicated. A reStructuredText parser must be able to
2765
recognize any absolute URI, as defined in RFC2396_ and RFC2732_.
2767
2. Standalone email addresses, which are treated as if they were
2768
absolute URIs with a "mailto:" scheme. Example::
2770
someone@somewhere.com
2772
Punctuation at the end of a URI is not considered part of the URI,
2773
unless the URI is terminated by a closing angle bracket (">").
2774
Backslashes may be used in URIs to escape markup characters,
2775
specifically asterisks ("*") and underscores ("_") which are vaid URI
2776
characters (see `Escaping Mechanism`_ above).
2778
.. [#URI] Uniform Resource Identifier. URIs are a general form of
2779
URLs (Uniform Resource Locators). For the syntax of URIs see
2780
RFC2396_ and RFC2732_.
2786
(New in Docutils 0.3.10.)
2788
All measures consist of a positive floating point number in standard
2789
(non-scientific) notation and a unit, possibly separated by one or
2792
Units are only supported where explicitly mentioned in the reference
2799
The following length units are supported by the reStructuredText
2802
* em (ems, the height of the element's font)
2803
* ex (x-height, the height of the letter "x")
2804
* px (pixels, relative to the canvas resolution)
2805
* in (inches; 1in=2.54cm)
2806
* cm (centimeters; 1cm=10mm)
2808
* pt (points; 1pt=1/72in)
2809
* pc (picas; 1pc=12pt)
2811
(List and explanations taken from
2812
http://www.htmlhelp.com/reference/css/units.html#length.)
2814
The following are all valid length values: "1.5em", "20 mm", ".5in".
2820
Percentage values have a percent sign ("%") as unit. Percentage
2821
values are relative to other values, depending on the context in which
2829
Doctree element: system_message, problematic.
2831
Markup errors are handled according to the specification in `PEP
2835
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
2836
.. _Docutils: http://docutils.sourceforge.net/
2837
.. _The Docutils Document Tree: ../doctree.html
2838
.. _Docutils Generic DTD: ../docutils.dtd
2840
http://docutils.sourceforge.net/docutils/transforms/
2841
.. _Grouch: http://www.mems-exchange.org/software/grouch/
2842
.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt
2843
.. _DocTitle transform:
2844
.. _DocInfo transform:
2845
http://docutils.sourceforge.net/docutils/transforms/frontmatter.py
2847
http://www.python.org/doc/current/lib/module-getopt.html
2848
.. _GNU libc getopt_long():
2849
http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html
2851
http://www.python.org/doc/current/lib/module-doctest.html
2852
.. _Emacs table mode: http://table.sourceforge.net/
2853
.. _Official IANA Registry of URI Schemes:
2854
http://www.iana.org/assignments/uri-schemes
2855
.. _Retired Index of WWW Addressing Schemes:
2856
http://www.w3.org/Addressing/schemes.html
2857
.. _World Wide Web Consortium: http://www.w3.org/
2858
.. _HTML Techniques for Web Content Accessibility Guidelines:
2859
http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text
2860
.. _image: directives.html#image
2861
.. _replace: directives.html#replace
2862
.. _meta: directives.html#meta
2863
.. _figure: directives.html#figure
2864
.. _admonition: directives.html#admonitions
2865
.. _reStructuredText Directives: directives.html
2866
.. _reStructuredText Interpreted Text Roles: roles.html
2867
.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt
2868
.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt
2869
.. _Zope: http://www.zope.com/
2870
.. _PEP 258: ../../peps/pep-0258.html
2876
indent-tabs-mode: nil
2877
sentence-end-double-space: t
added
removed
docs/ref/rst/restructuredtext.txt
