1 .. -*- coding: utf-8 -*-
3 =======================================
4 reStructuredText Markup Specification
5 =======================================
8 :Contact: docutils-develop@lists.sourceforge.net
11 :Copyright: This document has been placed in the public domain.
15 This document is a detailed technical specification; it is not a
16 tutorial or a primer. If this is your first exposure to
17 reStructuredText, please read `A ReStructuredText Primer`_ and the
18 `Quick reStructuredText`_ user reference first.
20 .. _A ReStructuredText Primer: ../../user/rst/quickstart.html
21 .. _Quick reStructuredText: ../../user/rst/quickref.html
24 reStructuredText_ is plaintext that uses simple and intuitive
25 constructs to indicate the structure of a document. These constructs
26 are equally easy to read in raw and processed forms. This document is
27 itself an example of reStructuredText (raw, if you are reading the
28 text file, or processed, if you are reading an HTML document, for
29 example). The reStructuredText parser is a component of Docutils_.
31 Simple, implicit markup is used to indicate special constructs, such
32 as section headings, bullet lists, and emphasis. The markup used is
33 as minimal and unobtrusive as possible. Less often-used constructs
34 and extensions to the basic reStructuredText syntax may have more
35 elaborate or explicit markup.
37 reStructuredText is applicable to documents of any length, from the
38 very small (such as inline program documentation fragments, e.g.
39 Python docstrings) to the quite large (this document).
41 The first section gives a quick overview of the syntax of the
42 reStructuredText markup by example. A complete specification is given
43 in the `Syntax Details`_ section.
45 `Literal blocks`_ (in which no markup processing is done) are used for
46 examples throughout this document, to illustrate the plaintext markup.
52 -----------------------
54 -----------------------
56 A reStructuredText document is made up of body or block-level
57 elements, and may be structured into sections. Sections_ are
58 indicated through title style (underlines & optional overlines).
59 Sections contain body elements and/or subsections. Some body elements
60 contain further elements, such as lists containing list items, which
61 in turn may contain paragraphs and other body elements. Others, such
62 as paragraphs, contain text and `inline markup`_ elements.
64 Here are examples of `body elements`_:
66 - Paragraphs_ (and `inline markup`_)::
68 Paragraphs contain text and may contain inline markup:
69 *emphasis*, **strong emphasis**, `interpreted text`, ``inline
70 literals``, standalone hyperlinks (http://www.python.org),
71 external hyperlinks (Python_), internal cross-references
72 (example_), footnote references ([1]_), citation references
73 ([CIT2002]_), substitution references (|example|), and _`inline
76 Paragraphs are separated by blank lines and are left-aligned.
78 - Five types of lists:
82 - This is a bullet list.
84 - Bullets can be "*", "+", or "-".
86 2. `Enumerated lists`_::
88 1. This is an enumerated list.
90 2. Enumerators may be arabic numbers, letters, or roman
93 3. `Definition lists`_::
96 Definition lists associate a term with a definition.
99 The term is a one-line phrase, and the definition is one
100 or more paragraphs or body elements, indented relative to
105 :what: Field lists map field names to field bodies, like
106 database records. They are often part of an extension
109 :how: The field marker is a colon, the field name, and a
112 The field body may contain one or more body elements,
113 indented relative to the field marker.
115 5. `Option lists`_, for listing command-line options::
117 -a command-line option "a"
118 -b file options can have arguments
119 and long descriptions
120 --long options can be long also
121 --input=file long options can also have
123 /V DOS/VMS-style options too
125 There must be at least two spaces between the option and the
128 - `Literal blocks`_::
130 Literal blocks are either indented or line-prefix-quoted blocks,
131 and indicated with a double-colon ("::") at the end of the
132 preceding paragraph (right here -->)::
135 text = 'is left as-is'
136 spaces_and_linebreaks = 'are preserved'
137 markup_processing = None
141 Block quotes consist of indented body elements:
143 This theory, that is mine, is mine.
147 - `Doctest blocks`_::
149 >>> print 'Python-specific usage examples; begun with ">>>"'
150 Python-specific usage examples; begun with ">>>"
151 >>> print '(cut and pasted from interactive Python sessions)'
152 (cut and pasted from interactive Python sessions)
154 - Two syntaxes for tables_:
156 1. `Grid tables`_; complete, but complex and verbose::
158 +------------------------+------------+----------+
159 | Header row, column 1 | Header 2 | Header 3 |
160 +========================+============+==========+
161 | body row 1, column 1 | column 2 | column 3 |
162 +------------------------+------------+----------+
163 | body row 2 | Cells may span |
164 +------------------------+-----------------------+
166 2. `Simple tables`_; easy and compact, but limited::
168 ==================== ========== ==========
169 Header row, column 1 Header 2 Header 3
170 ==================== ========== ==========
171 body row 1, column 1 column 2 column 3
172 body row 2 Cells may span columns
173 ==================== ======================
175 - `Explicit markup blocks`_ all begin with an explicit block marker,
176 two periods and a space:
180 .. [1] A footnote contains body elements, consistently
181 indented by at least 3 spaces.
185 .. [CIT2002] Just like a footnote, except the label is
188 - `Hyperlink targets`_::
190 .. _Python: http://www.python.org
194 The "_example" target above points to this paragraph.
198 .. image:: mylogo.png
200 - `Substitution definitions`_::
202 .. |symbol here| image:: symbol.png
206 .. Comments begin with two dots and a space. Anything may
207 follow, except for the syntax of footnotes/citations,
208 hyperlink targets, directives, or substitution definitions.
215 Descriptions below list "doctree elements" (document tree element
216 names; XML DTD generic identifiers) corresponding to syntax
217 constructs. For details on the hierarchy of elements, please see `The
218 Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
225 Spaces are recommended for indentation_, but tabs may also be used.
226 Tabs will be converted to spaces. Tab stops are at every 8th column
227 (processing systems may make this value configurable).
229 Other whitespace characters (form feeds [chr(12)] and vertical tabs
230 [chr(11)]) are converted to single spaces before processing.
236 Blank lines are used to separate paragraphs and other elements.
237 Multiple successive blank lines are equivalent to a single blank line,
238 except within literal blocks (where all whitespace is preserved).
239 Blank lines may be omitted when the markup makes element separation
240 unambiguous, in conjunction with indentation. The first line of a
241 document is treated as if it is preceded by a blank line, and the last
242 line of a document is treated as if it is followed by a blank line.
248 Indentation is used to indicate -- and is only significant in
249 indicating -- block quotes, definitions (in `definition lists`_),
250 and local nested content:
252 - list item content (multi-line contents of list items, and multiple
253 body elements within a list item, including nested lists),
254 - the content of `literal blocks`_, and
255 - the content of `explicit markup blocks`_ (directives, footnotes, ...).
257 Any text whose indentation is less than that of the current level
258 (i.e., unindented text or "dedents") ends the current level of
261 Since all indentation is significant, the level of indentation must be
262 consistent. For example, indentation is the sole markup indicator for
265 This is a top-level paragraph.
267 This paragraph belongs to a first-level block quote.
269 Paragraph 2 of the first-level block quote.
271 Multiple levels of indentation within a block quote will result in
272 more complex structures::
274 This is a top-level paragraph.
276 This paragraph belongs to a first-level block quote.
278 This paragraph belongs to a second-level block quote.
280 Another top-level paragraph.
282 This paragraph belongs to a second-level block quote.
284 This paragraph belongs to a first-level block quote. The
285 second-level block quote above is inside this first-level
288 When a paragraph or other construct consists of more than one line of
289 text, the lines must be left-aligned::
291 This is a paragraph. The lines of
292 this paragraph are aligned at the left.
294 This paragraph has problems. The
295 lines are not left-aligned. In addition
296 to potential misinterpretation, warning
297 and/or error messages will be generated
300 Several constructs begin with a marker, and the body of the construct
301 must be indented relative to the marker. For constructs using simple
302 markers (`bullet lists`_, `enumerated lists`_), the level of
303 indentation of the body is determined by the position of the first
304 line of text. For example::
306 - This is the first line of a bullet list
307 item's paragraph. All lines must align
308 relative to the first line.
310 This indented paragraph is interpreted
313 Another paragraph belonging to the first list item.
315 Because it is not sufficiently indented,
316 this paragraph does not belong to the list
317 item (it's a block quote following the list).
319 The body of `explicit markup blocks`_, `field lists`_, and `option
320 lists`_ ends above the first line with the same or less indentation
321 than the marker. For example, field lists may have very long markers
322 (containing the field names)::
324 :Hello: This field has a short field name, so aligning the field
325 body with the first line is feasible.
327 :Number-of-African-swallows-required-to-carry-a-coconut: It would
328 be very difficult to align the field body with the left edge
329 of the first line. It may even be preferable not to begin the
330 body on the same line as the marker.
336 The character set universally available to plaintext documents, 7-bit
337 ASCII, is limited. No matter what characters are used for markup,
338 they will already have multiple meanings in written text. Therefore
339 markup characters *will* sometimes appear in text **without being
340 intended as markup**. Any serious markup system requires an escaping
341 mechanism to override the default meaning of the characters used for
342 the markup. In reStructuredText we use the backslash, commonly used
343 as an escaping character in other domains.
345 A backslash followed by any character (except whitespace characters
347 escapes that character. The escaped character represents the
348 character itself, and is prevented from playing a role in any markup
349 interpretation. The backslash is removed from the output. A literal
350 backslash is represented by two backslashes in a row (the first
351 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 In URIs, backslash-escaped whitespace represents a single space.
360 There are two contexts in which backslashes have no special meaning:
361 literal blocks and inline literals. In these contexts, a single
362 backslash represents a literal backslash, without having to double up.
364 Please note that the reStructuredText specification and parser do not
365 address the issue of the representation or extraction of text input
366 (how and in what form the text actually *reaches* the parser).
367 Backslashes and other characters may serve a character-escaping
368 purpose in certain contexts and must be dealt with appropriately. For
369 example, Python uses backslashes in strings to escape certain
370 characters, but not others. The simplest solution when backslashes
371 appear in Python docstrings is to use raw docstrings::
373 r"""This is a raw docstring. Backslashes (\) are not touched."""
380 `Reference names` identify elements for cross-referencing.
382 .. Note:: References to a target position in external, generated documents
383 must use the auto-generated `identifier key`_ which may differ from the
384 `reference name` due to restrictions on identifiers/labels in the
387 Simple reference names are single words consisting of alphanumerics
388 plus isolated (no two adjacent) internal hyphens, underscores,
389 periods, colons and plus signs; no whitespace or other characters are
390 allowed. Footnote labels (Footnotes_ & `Footnote References`_), citation
391 labels (Citations_ & `Citation References`_), `interpreted text`_ roles,
392 and some `hyperlink references`_ use the simple reference name syntax.
394 Reference names using punctuation or whose names are phrases (two or
395 more space-separated words) are called "phrase-references".
396 Phrase-references are expressed by enclosing the phrase in backquotes
397 and treating the backquoted text as a reference name::
399 Want to learn about `my favorite programming language`_?
401 .. _my favorite programming language: http://www.python.org
403 Simple reference names may also optionally use backquotes.
405 .. _`normalized reference names`:
407 Reference names are whitespace-neutral and case-insensitive. When
408 resolving reference names internally:
410 - whitespace is normalized (one or more spaces, horizontal or vertical
411 tabs, newlines, carriage returns, or form feeds, are interpreted as
414 - case is normalized (all alphabetic characters are converted to
417 For example, the following `hyperlink references`_ are equivalent::
424 Hyperlinks_, footnotes_, and citations_ all share the same namespace
425 for reference names. The labels of citations (simple reference names)
426 and manually-numbered footnotes (numbers) are entered into the same
427 database as other hyperlink names. This means that a footnote
428 (defined as "``.. [1]``") which can be referred to by a footnote
429 reference (``[1]_``), can also be referred to by a plain hyperlink
430 reference (1_). Of course, each type of reference (hyperlink,
431 footnote, citation) may be processed and rendered differently. Some
432 care should be taken to avoid reference name conflicts.
441 Doctree element: `document <document element_>`_.
444 The top-level element of a parsed reStructuredText document is the
445 "document" element. After initial parsing, the document element is a
446 simple container for a document fragment, consisting of `body
447 elements`_, transitions_, and sections_, but lacking a document title
448 or other bibliographic elements. The code that calls the parser may
449 choose to run one or more optional post-parse transforms_,
450 rearranging the document fragment into a complete document with a
451 title and possibly other metadata elements (author, date, etc.; see
452 `Bibliographic Fields`_).
456 Specifically, there is no way to indicate a document title and
457 subtitle explicitly in reStructuredText. [#]_ Instead, a lone top-level
458 section title (see Sections_ below) can be treated as the document
459 title. Similarly, a lone second-level section title immediately after
460 the "document title" can become the document subtitle. The rest of
461 the sections are then lifted up a level or two. See the `DocTitle
462 transform`_ for details.
464 .. [#] The `title configuration setting`__ and the `title directive`__
465 set a document title that does not become part of the document body.
467 __ ../../user/config.html#title
468 __ directives.html#metadata-document-title
474 Doctree elements: section_, title_.
476 Sections are identified through their titles, which are marked up with
477 adornment: "underlines" below the title text, or underlines and
478 matching "overlines" above the title. An underline/overline is a
479 single repeated punctuation character that begins in column 1 and
480 forms a line extending at least as far as the right edge of the title
481 text. Specifically, an underline/overline character may be any
482 non-alphanumeric printable 7-bit ASCII character [#]_. When an
483 overline is used, the length and character used must match the
484 underline. Underline-only adornment styles are distinct from
485 overline-and-underline styles that use the same character. There may
486 be any number of levels of section titles, although some output
487 formats may have limits (HTML has 6 levels).
489 .. [#] The following are all valid section title adornment
492 ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
494 Some characters are more suitable than others. The following are
497 = - ` : . ' " ~ ^ _ * + #
499 Rather than imposing a fixed number and order of section title
500 adornment styles, the order enforced will be the order as encountered.
501 The first style encountered will be an outermost title (like HTML H1),
502 the second style will be a subtitle, the third will be a subsubtitle,
505 Below are examples of section title styles::
542 When a title has both an underline and an overline, the title text may
543 be inset, as in the first two examples above. This is merely
544 aesthetic and not significant. Underline-only title text may *not* be
547 A blank line after a title is optional. All text blocks up to the
548 next title of the same or higher level are included in a section (or
551 All section title styles need not be used, nor need any specific
552 section title style be used. However, a document must be consistent
553 in its use of section titles: once a hierarchy of title styles is
554 established, sections must use that hierarchy.
556 Each section title automatically generates a hyperlink target pointing
557 to the section. The text of the hyperlink target (the "reference
558 name") is the same as that of the section title. See `Implicit
559 Hyperlink Targets`_ for a complete description.
561 Sections may contain `body elements`_, transitions_, and nested
568 Doctree element: transition_.
570 Instead of subheads, extra space or a type ornament between
571 paragraphs may be used to mark text divisions or to signal
572 changes in subject or emphasis.
574 (The Chicago Manual of Style, 14th edition, section 1.80)
576 Transitions are commonly seen in novels and short fiction, as a gap
577 spanning one or more lines, with or without a type ornament such as a
578 row of asterisks. Transitions separate other body elements. A
579 transition should not begin or end a section or document, nor should
580 two transitions be immediately adjacent.
582 The syntax for a transition marker is a horizontal line of 4 or more
583 repeated punctuation characters. The syntax is the same as section
584 title underlines without title text. Transition markers require blank
585 lines before and after::
593 Unlike section title underlines, no hierarchy of transition markers is
594 enforced, nor do differences in transition markers accomplish
595 anything. It is recommended that a single consistent style be used.
597 The processing system is free to render transitions in output in any
598 way it likes. For example, horizontal rules (``<hr>``) in HTML output
599 would be an obvious choice.
608 Doctree element: paragraph_.
610 Paragraphs consist of blocks of left-aligned text with no markup
611 indicating any other body element. Blank lines separate paragraphs
612 from each other and from other body elements. Paragraphs may contain
617 +------------------------------+
620 +------------------------------+
622 +------------------------------+
625 +------------------------------+
631 Doctree elements: bullet_list_, list_item_.
633 A text block which begins with a "*", "+", "-", "•", "‣", or "⁃",
634 followed by whitespace, is a bullet list item (a.k.a. "unordered" list
635 item). List item bodies must be left-aligned and indented relative to
636 the bullet; the text immediately after the bullet determines the
637 indentation. For example::
639 - This is the first bullet list item. The blank line above the
640 first list item is required; blank lines between list items
641 (such as below this paragraph) are optional.
643 - This is the first paragraph in the second item in the list.
645 This is the second paragraph in the second item in the list.
646 The blank line above this paragraph is required. The left edge
647 of this paragraph lines up with the paragraph above, both
648 indented relative to the bullet.
650 - This is a sublist. The bullet lines up with the left edge of
651 the text blocks above. A sublist is a new list so requires a
652 blank line above and below.
654 - This is the third item of the main list.
656 This paragraph is not part of the list.
658 Here are examples of **incorrectly** formatted bullet lists::
660 - This first line is fine.
661 A blank line is required between list items and paragraphs.
664 - The following line appears to be a new sublist, but it is not:
665 - This is a paragraph continuation, not a sublist (since there's
666 no blank line). This line is also incorrectly indented.
667 - Warnings may be issued by the implementation.
671 +------+-----------------------+
673 +------| (body elements)+ |
674 +-----------------------+
680 Doctree elements: enumerated_list_, list_item_.
682 Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists,
683 but use enumerators instead of bullets. An enumerator consists of an
684 enumeration sequence member and formatting, followed by whitespace.
685 The following enumeration sequences are recognized:
687 - arabic numerals: 1, 2, 3, ... (no upper limit).
688 - uppercase alphabet characters: A, B, C, ..., Z.
689 - lower-case alphabet characters: a, b, c, ..., z.
690 - uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
691 - lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).
693 In addition, the auto-enumerator, "#", may be used to automatically
694 enumerate a list. Auto-enumerated lists may begin with explicit
695 enumeration, which sets the sequence. Fully auto-enumerated lists use
696 arabic numerals and begin with 1. (Auto-enumerated lists are new in
699 The following formatting types are recognized:
701 - suffixed with a period: "1.", "A.", "a.", "I.", "i.".
702 - surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)".
703 - suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)".
705 While parsing an enumerated list, a new list will be started whenever:
707 - An enumerator is encountered which does not have the same format and
708 sequence type as the current list (e.g. "1.", "(a)" produces two
711 - The enumerators are not in sequence (e.g., "1.", "3." produces two
714 It is recommended that the enumerator of the first list item be
715 ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values
716 will be recognized, they may not be supported by the output format. A
717 level-1 [info] system message will be generated for any list beginning
718 with a non-ordinal-1 enumerator.
720 Lists using Roman numerals must begin with "I"/"i" or a
721 multi-character value, such as "II" or "XV". Any other
722 single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be
723 interpreted as a letter of the alphabet, not as a Roman numeral.
724 Likewise, lists using letters of the alphabet may not begin with
725 "I"/"i", since these are recognized as Roman numeral 1.
727 The second line of each enumerated list item is checked for validity.
728 This is to prevent ordinary paragraphs from being mistakenly
729 interpreted as list items, when they happen to begin with text
730 identical to enumerators. For example, this text is parsed as an
733 A. Einstein was a really
736 However, ambiguity cannot be avoided if the paragraph consists of only
737 one line. This text is parsed as an enumerated list item::
739 A. Einstein was a really smart dude.
741 If a single-line paragraph begins with text identical to an enumerator
742 ("A.", "1.", "(b)", "I)", etc.), the first character will have to be
743 escaped in order to have the line parsed as an ordinary paragraph::
745 \A. Einstein was a really smart dude.
747 Examples of nested enumerated lists::
749 1. Item 1 initial text.
757 Example syntax diagram::
759 +-------+----------------------+
760 | "1. " | list item |
761 +-------| (body elements)+ |
762 +----------------------+
768 Doctree elements: definition_list_, definition_list_item_, term_,
769 classifier_, definition_.
771 Each definition list item contains a term, optional classifiers, and a
772 definition. A term is a simple one-line word or phrase. Optional
773 classifiers may follow the term on the same line, each after an inline
774 " : " (space, colon, space). A definition is a block indented
775 relative to the term, and may contain multiple paragraphs and other
776 body elements. There may be no blank line between a term line and a
777 definition block (this distinguishes definition lists from `block
778 quotes`_). Blank lines are required before the first and after the
779 last definition list item, but are optional in-between. For example::
785 Definition 2, paragraph 1.
787 Definition 2, paragraph 2.
792 term 4 : classifier one : classifier two
795 Inline markup is parsed in the term line before the classifier
796 delimiter (" : ") is recognized. The delimiter will only be
797 recognized if it appears outside of any inline markup.
799 A definition list may be used in various ways, including:
801 - As a dictionary or glossary. The term is the word itself, a
802 classifier may be used to indicate the usage of the term (noun,
803 verb, etc.), and the definition follows.
805 - To describe program variables. The term is the variable name, a
806 classifier may be used to indicate the type of the variable (string,
807 integer, etc.), and the definition describes the variable's use in
808 the program. This usage of definition lists supports the classifier
809 syntax of Grouch_, a system for describing and enforcing a Python
814 +----------------------------+
815 | term [ " : " classifier ]* |
816 +--+-------------------------+--+
819 +----------------------------+
825 Doctree elements: field_list_, field_, field_name_, field_body_.
827 Field lists are used as part of an extension syntax, such as options
828 for directives_, or database-like records meant for further
829 processing. They may also be used for two-column table-like
830 structures resembling database records (label & data pairs).
831 Applications of reStructuredText may recognize field names and
832 transform fields or field bodies in certain contexts. For examples,
833 see `Bibliographic Fields`_ below, or the "image_" and "meta_"
834 directives in `reStructuredText Directives`_.
838 Field lists are mappings from *field names* to *field bodies*, modeled on
839 RFC822_ headers. A field name may consist of any characters, but
840 colons (":") inside of field names must be backslash-escaped
841 when followed by whitespace.\ [#]_
842 Inline markup is parsed in field names, but care must be taken when
843 using `interpreted text`_ with explicit roles in field names: the role
844 must be a suffix to the interpreted text. Field names are
845 case-insensitive when further processed or transformed. The field
846 name, along with a single colon prefix and suffix, together form the
847 field marker. The field marker is followed by whitespace and the
848 field body. The field body may contain multiple body elements,
849 indented relative to the field marker. The first line after the field
850 name marker determines the indentation of the field body. For
858 :Indentation: Since the field marker may be quite long, the second
859 and subsequent lines of the field body do not have to line up
860 with the first line, but they must be indented relative to the
861 field name marker, and they must line up with each other.
862 :Parameter i: integer
864 The interpretation of individual words in a multi-word field name is
865 up to the application. The application may specify a syntax for the
866 field name. For example, second and subsequent words may be treated
867 as "arguments", quoted phrases may be treated as a single argument,
868 and direct support for the "name=value" syntax may be added.
870 Standard RFC822_ headers cannot be used for this construct because
871 they are ambiguous. A word followed by a colon at the beginning of a
872 line is common in written text. However, in well-defined contexts
873 such as when a field list invariably occurs at the beginning of a
874 document (PEPs and email messages), standard RFC822 headers could be
877 Syntax diagram (simplified)::
879 +--------------------+----------------------+
880 | ":" field name ":" | field body |
881 +-------+------------+ |
883 +-----------------------------------+
885 .. [#] Up to Docutils 0.14, field markers were not recognized when
891 Doctree elements: docinfo_, address_, author_, authors_, contact_,
892 copyright_, date_, organization_, revision_, status_, topic_,
895 When a field list is the first non-comment element in a document
896 (after the document title, if there is one), it may have its fields
897 transformed to document bibliographic data. This bibliographic data
898 corresponds to the front matter of a book, such as the title page and
901 Certain registered field names (listed below) are recognized and
902 transformed to the corresponding doctree elements, most becoming child
903 elements of the docinfo_ element. No ordering is required of these
904 fields, although they may be rearranged to fit the document structure,
905 as noted. Unless otherwise indicated below, each of the bibliographic
906 elements' field bodies may contain a single paragraph only. Field
907 bodies may be checked for `RCS keywords`_ and cleaned up. Any
908 unrecognized fields will remain as generic fields in the docinfo
911 The registered bibliographic field names and their corresponding
912 doctree elements are as follows:
914 ============= ================
915 Field name doctree element
916 ============= ================
925 Organization organization_
929 ============= ================
931 The "Authors" field may contain either: a single paragraph consisting
932 of a list of authors, separated by ";" or "," (";" is checked first,
933 so "Doe, Jane; Doe, John" will work.); multiple paragraphs (one per
934 author); or a bullet list whose elements each contain a single
935 paragraph per author. In some languages
936 (e.g. Swedish), there is no singular/plural distinction between
937 "Author" and "Authors", so only an "Authors" field is provided, and a
938 single name is interpreted as an "Author". If a single name contains
939 a comma, end it with a semicolon to disambiguate: ":Authors: Doe,
942 The "Address" field is for a multi-line surface mailing address.
943 Newlines and whitespace will be preserved.
945 The "Dedication" and "Abstract" fields may contain arbitrary body
946 elements. Only one of each is allowed. They become topic elements
947 with "Dedication" or "Abstract" titles (or language equivalents)
948 immediately following the docinfo element.
950 This field-name-to-element mapping can be replaced for other
951 languages. See the `DocInfo transform`_ implementation documentation
954 Unregistered/generic fields may contain one or more paragraphs or
955 arbitrary body elements.
956 The field name is also used as a `"classes" attribute`_ value after being
957 converted into a valid identifier form.
963 `Bibliographic fields`_ recognized by the parser are normally checked
964 for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be
965 entered into source files as "$keyword$", and once stored under RCS or
966 CVS [#]_, they are expanded to "$keyword: expansion text $". For
967 example, a "Status" field will be transformed to a "status" element::
969 :Status: $keyword: expansion text $
971 .. [#] Revision Control System.
972 .. [#] RCS keyword processing can be turned off (unimplemented).
973 .. [#] Concurrent Versions System. CVS uses the same keywords as RCS.
975 Processed, the "status" element's text will become simply "expansion
976 text". The dollar sign delimiters and leading RCS keyword name are
979 The RCS keyword processing only kicks in when the field list is in
980 bibliographic context (first non-comment construct in the document,
981 after a document title if there is one).
987 Doctree elements: option_list_, option_list_item_, option_group_, option_,
988 option_string_, option_argument_, description_.
990 Option lists are two-column lists of command-line options and
991 descriptions, documenting a program's options. For example::
994 -b Output both (this description is
996 -c arg Output just arg.
997 --long Output all day long.
999 -p This option has two paragraphs in the description.
1002 This is the second. Blank lines may be omitted between
1003 options (as above) or left in (as here and below).
1005 --very-long-option A VMS-style option. Note the adjustment for
1006 the required two spaces.
1008 --an-even-longer-option
1009 The description can also start on the next line.
1011 -2, --two This option has two variants.
1013 -f FILE, --file=FILE These two options are synonyms; both have
1016 /V A VMS/DOS-style option.
1018 There are several types of options recognized by reStructuredText:
1020 - Short POSIX options consist of one dash and an option letter.
1021 - Long POSIX options consist of two dashes and an option word; some
1022 systems use a single dash.
1023 - Old GNU-style "plus" options consist of one plus and an option
1024 letter ("plus" options are deprecated now, their use discouraged).
1025 - DOS/VMS options consist of a slash and an option letter or word.
1027 Please note that both POSIX-style and DOS/VMS-style options may be
1028 used by DOS or Windows software. These and other variations are
1029 sometimes used mixed together. The names above have been chosen for
1032 The syntax for short and long POSIX options is based on the syntax
1033 supported by Python's getopt.py_ module, which implements an option
1034 parser similar to the `GNU libc getopt_long()`_ function but with some
1035 restrictions. There are many variant option systems, and
1036 reStructuredText option lists do not support all of them.
1038 Although long POSIX and DOS/VMS option words may be allowed to be
1039 truncated by the operating system or the application when used on the
1040 command line, reStructuredText option lists do not show or support
1041 this with any special syntax. The complete option word should be
1042 given, supported by notes about truncation if and when applicable.
1044 Options may be followed by an argument placeholder, whose role and
1045 syntax should be explained in the description text. Either a space or
1046 an equals sign may be used as a delimiter between options and option
1047 argument placeholders; short options ("-" or "+" prefix only) may omit
1048 the delimiter. Option arguments may take one of two forms:
1050 - Begins with a letter (``[a-zA-Z]``) and subsequently consists of
1051 letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``).
1052 - Begins with an open-angle-bracket (``<``) and ends with a
1053 close-angle-bracket (``>``); any characters except angle brackets
1054 are allowed internally.
1056 Multiple option "synonyms" may be listed, sharing a single
1057 description. They must be separated by comma-space.
1059 There must be at least two spaces between the option(s) and the
1060 description. The description may contain multiple body elements. The
1061 first line after the option marker determines the indentation of the
1062 description. As with other types of lists, blank lines are required
1063 before the first option list item and after the last, but are optional
1064 between option entries.
1066 Syntax diagram (simplified)::
1068 +----------------------------+-------------+
1069 | option [" " argument] " " | description |
1070 +-------+--------------------+ |
1071 | (body elements)+ |
1072 +----------------------------------+
1078 Doctree element: literal_block_.
1080 A paragraph consisting of two colons ("::") signifies that the
1081 following text block(s) comprise a literal block. The literal block
1082 must either be indented or quoted (see below). No markup processing
1083 is done within a literal block. It is left as-is, and is typically
1084 rendered in a monospaced typeface::
1086 This is a typical paragraph. An indented literal block follows.
1090 for a in [5,4,3,2,1]: # this is program code, shown as-is
1093 # a literal block continues until the indentation ends
1095 This text has returned to the indentation of the first paragraph,
1096 is outside of the literal block, and is therefore treated as an
1099 The paragraph containing only "::" will be completely removed from the
1100 output; no empty paragraph will remain.
1102 As a convenience, the "::" is recognized at the end of any paragraph.
1103 If immediately preceded by whitespace, both colons will be removed
1104 from the output (this is the "partially minimized" form). When text
1105 immediately precedes the "::", *one* colon will be removed from the
1106 output, leaving only one colon visible (i.e., "::" will be replaced by
1107 ":"; this is the "fully minimized" form).
1109 In other words, these are all equivalent (please pay attention to the
1110 colons after "Paragraph"):
1120 2. Partially minimized form::
1126 3. Fully minimized form::
1132 All whitespace (including line breaks, but excluding minimum
1133 indentation for indented literal blocks) is preserved. Blank lines
1134 are required before and after a literal block, but these blank lines
1135 are not included as part of the literal block.
1138 Indented Literal Blocks
1139 ```````````````````````
1141 Indented literal blocks are indicated by indentation relative to the
1142 surrounding text (leading whitespace on each line). The minimum
1143 indentation will be removed from each line of an indented literal
1144 block. The literal block need not be contiguous; blank lines are
1145 allowed between sections of indented text. The literal block ends
1146 with the end of the indentation.
1150 +------------------------------+
1152 | (ends with "::") |
1153 +------------------------------+
1154 +---------------------------+
1155 | indented literal block |
1156 +---------------------------+
1159 Quoted Literal Blocks
1160 `````````````````````
1162 Quoted literal blocks are unindented contiguous blocks of text where
1163 each line begins with the same non-alphanumeric printable 7-bit ASCII
1164 character [#]_. A blank line ends a quoted literal block. The
1165 quoting characters are preserved in the processed document.
1168 The following are all valid quoting characters::
1170 ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
1172 Note that these are the same characters as are valid for title
1173 adornment of sections_.
1175 Possible uses include literate programming in Haskell and email
1182 > Why didn't I think of that?
1188 +------------------------------+
1190 | (ends with "::") |
1191 +------------------------------+
1192 +------------------------------+
1193 | ">" per-line-quoted |
1194 | ">" contiguous literal block |
1195 +------------------------------+
1201 Doctree elements: line_block_, line_. (New in Docutils 0.3.5.)
1203 Line blocks are useful for address blocks, verse (poetry, song
1204 lyrics), and unadorned lists, where the structure of lines is
1205 significant. Line blocks are groups of lines beginning with vertical
1206 bar ("|") prefixes. Each vertical bar prefix indicates a new line, so
1207 line breaks are preserved. Initial indents are also significant,
1208 resulting in a nested structure. Inline markup is supported.
1209 Continuation lines are wrapped portions of long lines; they begin with
1210 a space in place of the vertical bar. The left edge of a continuation
1211 line must be indented, but need not be aligned with the left edge of
1212 the text above it. A line block ends with a blank line.
1214 This example illustrates continuation lines::
1216 | Lend us a couple of bob till Thursday.
1217 | I'm absolutely skint.
1218 | But I'm expecting a postal order and I can pay you back
1219 as soon as it comes.
1222 This example illustrates the nesting of line blocks, indicated by the
1223 initial indentation of new lines::
1225 Take it away, Eric the Orchestra Leader!
1227 | A one, two, a one two three four
1229 | Half a bee, philosophically,
1230 | must, *ipso facto*, half not be.
1231 | But half the bee has got to be,
1232 | *vis a vis* its entity. D'you see?
1234 | But can a bee be said to be
1235 | or not to be an entire bee,
1236 | when half the bee is not a bee,
1237 | due to some ancient injury?
1243 +------+-----------------------+
1245 +------| continuation line |
1246 +-----------------------+
1252 Doctree elements: block_quote_, attribution_.
1254 A text block that is indented relative to the preceding text, without
1255 preceding markup indicating it to be a literal block or other content,
1256 is a block quote. All markup processing (for body elements and inline
1257 markup) continues within the block quote::
1259 This is an ordinary paragraph, introducing a block quote.
1261 "It is my business to know things. That is my trade."
1265 A block quote may end with an attribution: a text block beginning with
1266 "--", "---", or a true em-dash, flush left within the block quote. If
1267 the attribution consists of multiple lines, the left edges of the
1268 second and subsequent lines must align.
1270 Multiple block quotes may occur consecutively if terminated with
1273 Unindented paragraph.
1281 `Empty comments`_ may be used to explicitly terminate preceding
1282 constructs that would otherwise consume a block quote::
1290 Empty comments may also be used to separate block quotes::
1298 Blank lines are required before and after a block quote, but these
1299 blank lines are not included as part of the block quote.
1303 +------------------------------+
1304 | (current level of |
1306 +------------------------------+
1307 +---------------------------+
1309 | (body elements)+ |
1311 | -- attribution text |
1313 +---------------------------+
1319 Doctree element: doctest_block_.
1321 Doctest blocks are interactive Python sessions cut-and-pasted into
1322 docstrings. They are meant to illustrate usage by example, and
1323 provide an elegant and powerful testing environment via the `doctest
1324 module`_ in the Python standard library.
1326 Doctest blocks are text blocks which begin with ``">>> "``, the Python
1327 interactive interpreter main prompt, and end with a blank line.
1328 Doctest blocks are treated as a special case of literal blocks,
1329 without requiring the literal block syntax. If both are present, the
1330 literal block syntax takes priority over Doctest block syntax::
1332 This is an ordinary paragraph.
1334 >>> print 'this is a Doctest block'
1335 this is a Doctest block
1337 The following is a literal block::
1339 >>> This is not recognized as a doctest block by
1340 reStructuredText. It *will* be recognized by the doctest
1343 Indentation is not required for doctest blocks.
1349 Doctree elements: table_, tgroup_, colspec_, thead_, tbody_, row_, entry_.
1351 ReStructuredText provides two syntax variants for delineating table
1352 cells: `Grid Tables`_ and `Simple Tables`_. Tables are also generated by
1353 the `CSV Table`_ and `List Table`_ directives. The `table
1354 directive`_ is used to add a table title or specify options.
1356 As with other body elements, blank lines are required before and after
1357 tables. Tables' left edges should align with the left edge of
1358 preceding text blocks; if indented, the table is considered to be part
1361 Once isolated, each table cell is treated as a miniature document; the
1362 top and bottom cell boundaries act as delimiting blank lines. Each
1363 cell contains zero or more body elements. Cell contents may include
1364 left and/or right margins, which are removed before processing.
1370 Grid tables provide a complete table representation via grid-like
1371 "ASCII art". Grid tables allow arbitrary cell contents (body
1372 elements), and both row and column spans. However, grid tables can be
1373 cumbersome to produce, especially for simple data sets. The `Emacs
1374 table mode`_ is a tool that allows easy editing of grid tables, in
1375 Emacs. See `Simple Tables`_ for a simpler (but limited)
1378 Grid tables are described with a visual grid made up of the characters
1379 "-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines
1380 (row separators). The equals sign ("=") may be used to separate
1381 optional header rows from the table body (not supported by the `Emacs
1382 table mode`_). The vertical bar ("|") is used for vertical lines
1383 (column separators). The plus sign ("+") is used for intersections of
1384 horizontal and vertical lines. Example::
1386 +------------------------+------------+----------+----------+
1387 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
1388 | (header rows optional) | | | |
1389 +========================+============+==========+==========+
1390 | body row 1, column 1 | column 2 | column 3 | column 4 |
1391 +------------------------+------------+----------+----------+
1392 | body row 2 | Cells may span columns. |
1393 +------------------------+------------+---------------------+
1394 | body row 3 | Cells may | - Table cells |
1395 +------------------------+ span rows. | - contain |
1396 | body row 4 | | - body elements. |
1397 +------------------------+------------+---------------------+
1399 Some care must be taken with grid tables to avoid undesired
1400 interactions with cell text in rare cases. For example, the following
1401 table contains a cell in row 2 spanning from column 2 to column 4::
1403 +--------------+----------+-----------+-----------+
1404 | row 1, col 1 | column 2 | column 3 | column 4 |
1405 +--------------+----------+-----------+-----------+
1407 +--------------+----------+-----------+-----------+
1409 +--------------+----------+-----------+-----------+
1411 If a vertical bar is used in the text of that cell, it could have
1412 unintended effects if accidentally aligned with column boundaries::
1414 +--------------+----------+-----------+-----------+
1415 | row 1, col 1 | column 2 | column 3 | column 4 |
1416 +--------------+----------+-----------+-----------+
1417 | row 2 | Use the command ``ls | more``. |
1418 +--------------+----------+-----------+-----------+
1420 +--------------+----------+-----------+-----------+
1422 Several solutions are possible. All that is needed is to break the
1423 continuity of the cell outline rectangle. One possibility is to shift
1424 the text by adding an extra space before::
1426 +--------------+----------+-----------+-----------+
1427 | row 1, col 1 | column 2 | column 3 | column 4 |
1428 +--------------+----------+-----------+-----------+
1429 | row 2 | Use the command ``ls | more``. |
1430 +--------------+----------+-----------+-----------+
1432 +--------------+----------+-----------+-----------+
1434 Another possibility is to add an extra line to row 2::
1436 +--------------+----------+-----------+-----------+
1437 | row 1, col 1 | column 2 | column 3 | column 4 |
1438 +--------------+----------+-----------+-----------+
1439 | row 2 | Use the command ``ls | more``. |
1441 +--------------+----------+-----------+-----------+
1443 +--------------+----------+-----------+-----------+
1449 Simple tables provide a compact and easy to type but limited
1450 row-oriented table representation for simple data sets. Cell contents
1451 are typically single paragraphs, although arbitrary body elements may
1452 be represented in most cells. Simple tables allow multi-line rows (in
1453 all but the first column) and column spans, but not row spans. See
1454 `Grid Tables`_ above for a complete table representation.
1456 Simple tables are described with horizontal borders made up of "=" and
1457 "-" characters. The equals sign ("=") is used for top and bottom
1458 table borders, and to separate optional header rows from the table
1459 body. The hyphen ("-") is used to indicate column spans in a single
1460 row by underlining the joined columns, and may optionally be used to
1461 explicitly and/or visually separate rows.
1463 A simple table begins with a top border of equals signs with one or
1464 more spaces at each column boundary (two or more spaces recommended).
1465 Regardless of spans, the top border *must* fully describe all table
1466 columns. There must be at least two columns in the table (to
1467 differentiate it from section headers). The top border may be
1468 followed by header rows, and the last of the optional header rows is
1469 underlined with '=', again with spaces at column boundaries. There
1470 may not be a blank line below the header row separator; it would be
1471 interpreted as the bottom border of the table. The bottom boundary of
1472 the table consists of '=' underlines, also with spaces at column
1473 boundaries. For example, here is a truth table, a three-column table
1474 with one header row and four body rows::
1485 Underlines of '-' may be used to indicate column spans by "filling in"
1486 column margins to join adjacent columns. Column span underlines must
1487 be complete (they must cover all columns) and align with established
1488 column boundaries. Text lines containing column span underlines may
1489 not contain any other text. A column span underline applies only to
1490 one row immediately above it. For example, here is a table with a
1491 column span in the header::
1504 Each line of text must contain spaces at column boundaries, except
1505 where cells have been joined by column spans. Each line of text
1506 starts a new row, except when there is a blank cell in the first
1507 column. In that case, that line of text is parsed as a continuation
1508 line. For this reason, cells in the first column of new rows (*not*
1509 continuation lines) *must* contain some text; blank cells would lead
1510 to a misinterpretation (but see the tip below). Also, this mechanism
1511 limits cells in the first column to only one line of text. Use `grid
1512 tables`_ if this limitation is unacceptable.
1516 To start a new row in a simple table without text in the first
1517 column in the processed output, use one of these:
1519 * an empty comment (".."), which may be omitted from the processed
1520 output (see Comments_ below)
1522 * a backslash escape ("``\``") followed by a space (see `Escaping
1525 Underlines of '-' may also be used to visually separate rows, even if
1526 there are no column spans. This is especially useful in long tables,
1527 where rows are many lines long.
1529 Blank lines are permitted within simple tables. Their interpretation
1530 depends on the context. Blank lines *between* rows are ignored.
1531 Blank lines *within* multi-line rows may separate paragraphs or other
1532 body elements within cells.
1534 The rightmost column is unbounded; text may continue past the edge of
1535 the table (as indicated by the table borders). However, it is
1536 recommended that borders be made long enough to contain the entire
1539 The following example illustrates continuation lines (row 2 consists
1540 of two lines of text, and four lines for row 3), a blank line
1541 separating paragraphs (row 3, column 2), text extending past the right
1542 edge of the table, and a new row which will have no text in the first
1543 column in the processed output (row 4)::
1548 1 Second column of row 1.
1549 2 Second column of row 2.
1550 Second line of paragraph.
1551 3 - Second column of row 3.
1553 - Second item in bullet
1554 list (row 3, column 2).
1555 \ Row 4; column 1 will be empty.
1559 Explicit Markup Blocks
1560 ----------------------
1562 The explicit markup syntax is used for footnotes_, citations_,
1563 `hyperlink targets`_, directives_, `substitution definitions`_,
1566 An explicit markup block is a text block:
1568 - whose first line begins with ".." followed by whitespace (the
1569 "explicit markup start"),
1570 - whose second and subsequent lines (if any) are indented relative to
1572 - which ends before an unindented line.
1574 Explicit markup blocks are analogous to field list items. The
1575 maximum common indentation is always removed from the second and
1576 subsequent lines of the block body. Therefore, if the first construct
1577 fits in one line and the indentation of the first and second
1578 constructs should differ, the first construct should not begin on the
1579 same line as the explicit markup start.
1581 Blank lines are required between explicit markup blocks and other
1582 elements, but are optional between explicit markup blocks where
1589 See also: `Footnote References`_.
1591 Doctree elements: footnote_, label_.
1593 Configuration settings:
1594 `footnote_references <footnote_references setting_>`_.
1596 .. _footnote_references setting:
1597 ../../user/config.html#footnote-references
1599 Each footnote consists of an explicit markup start (".. "), a left
1600 square bracket, the footnote label, a right square bracket, and
1601 whitespace, followed by indented body elements. A footnote label can
1604 - a whole decimal number consisting of one or more digits,
1606 - a single "#" (denoting `auto-numbered footnotes`_),
1608 - a "#" followed by a simple reference name (an `autonumber label`_),
1611 - a single "*" (denoting `auto-symbol footnotes`_).
1613 The footnote content (body elements) must be consistently indented
1614 and left-aligned. The first body element within a
1615 footnote may often begin on the same line as the footnote label.
1616 However, if the first element fits on one line and the indentation of
1617 the remaining elements differ, the first element must begin on the
1618 line after the footnote label. Otherwise, the difference in
1619 indentation will not be detected.
1621 Footnotes may occur anywhere in the document, not only at the end.
1622 Where and how they appear in the processed output depends on the
1625 Here is a manually numbered footnote::
1627 .. [1] Body elements go here.
1629 Each footnote automatically generates a hyperlink target pointing to
1630 itself. The text of the hyperlink target name is the same as that of
1631 the footnote label. `Auto-numbered footnotes`_ generate a number as
1632 their footnote label and reference name. See `Implicit Hyperlink
1633 Targets`_ for a complete description of the mechanism.
1637 +-------+-------------------------+
1638 | ".. " | "[" label "]" footnote |
1640 | (body elements)+ |
1641 +-------------------------+
1644 Auto-Numbered Footnotes
1645 .......................
1647 A number sign ("#") may be used as the first character of a footnote
1648 label to request automatic numbering of the footnote or footnote
1651 The first footnote to request automatic numbering is assigned the
1652 label "1", the second is assigned the label "2", and so on (assuming
1653 there are no manually numbered footnotes present; see `Mixed Manual
1654 and Auto-Numbered Footnotes`_ below). A footnote which has
1655 automatically received a label "1" generates an implicit hyperlink
1656 target with name "1", just as if the label was explicitly specified.
1658 .. _autonumber label: `autonumber labels`_
1660 A footnote may specify a label explicitly while at the same time
1661 requesting automatic numbering: ``[#label]``. These labels are called
1662 _`autonumber labels`. Autonumber labels do two things:
1664 - On the footnote itself, they generate a hyperlink target whose name
1665 is the autonumber label (doesn't include the "#").
1667 - They allow an automatically numbered footnote to be referred to more
1668 than once, as a footnote reference or hyperlink reference. For
1671 If [#note]_ is the first footnote reference, it will show up as
1672 "[1]". We can refer to it again as [#note]_ and again see
1673 "[1]". We can also refer to it as note_ (an ordinary internal
1674 hyperlink reference).
1676 .. [#note] This is the footnote labeled "note".
1678 The numbering is determined by the order of the footnotes, not by the
1679 order of the references. For footnote references without autonumber
1680 labels (``[#]_``), the footnotes and footnote references must be in
1681 the same relative order but need not alternate in lock-step. For
1684 [#]_ is a reference to footnote 1, and [#]_ is a reference to
1687 .. [#] This is footnote 1.
1688 .. [#] This is footnote 2.
1689 .. [#] This is footnote 3.
1691 [#]_ is a reference to footnote 3.
1693 Special care must be taken if footnotes themselves contain
1694 auto-numbered footnote references, or if multiple references are made
1695 in close proximity. Footnotes and references are noted in the order
1696 they are encountered in the document, which is not necessarily the
1697 same as the order in which a person would read them.
1700 Auto-Symbol Footnotes
1701 .....................
1703 An asterisk ("*") may be used for footnote labels to request automatic
1704 symbol generation for footnotes and footnote references. The asterisk
1705 may be the only character in the label. For example::
1707 Here is a symbolic footnote reference: [*]_.
1709 .. [*] This is the footnote.
1711 A transform will insert symbols as labels into corresponding footnotes
1712 and footnote references. The number of references must be equal to
1713 the number of footnotes. One symbol footnote cannot have multiple
1716 The standard Docutils system uses the following symbols for footnote
1719 - asterisk/star ("*")
1720 - dagger (HTML character entity "†", Unicode U+02020)
1721 - double dagger ("‡"/U+02021)
1722 - section mark ("§"/U+000A7)
1723 - pilcrow or paragraph mark ("¶"/U+000B6)
1725 - spade suit ("♠"/U+02660)
1726 - heart suit ("♥"/U+02665)
1727 - diamond suit ("♦"/U+02666)
1728 - club suit ("♣"/U+02663)
1730 .. [#] This list was inspired by the list of symbols for "Note
1731 Reference Marks" in The Chicago Manual of Style, 14th edition,
1732 section 12.51. "Parallels" ("||") were given in CMoS instead of
1733 the pilcrow. The last four symbols (the card suits) were added
1736 If more than ten symbols are required, the same sequence will be
1737 reused, doubled and then tripled, and so on ("**" etc.).
1739 .. Note:: When using auto-symbol footnotes, the choice of output
1740 encoding is important. Many of the symbols used are not encodable
1741 in certain common text encodings such as Latin-1 (ISO 8859-1). The
1742 use of UTF-8 for the output encoding is recommended. An
1743 alternative for HTML and XML output is to use the
1744 "xmlcharrefreplace" `output encoding error handler`__.
1746 __ ../../user/config.html#output-encoding-error-handler
1749 Mixed Manual and Auto-Numbered Footnotes
1750 ........................................
1752 Manual and automatic footnote numbering may both be used within a
1753 single document, although the results may not be expected. Manual
1754 numbering takes priority. Only unused footnote numbers are assigned
1755 to auto-numbered footnotes. The following example should be
1758 [2]_ will be "2" (manually numbered),
1759 [#]_ will be "3" (anonymous auto-numbered), and
1760 [#label]_ will be "1" (labeled auto-numbered).
1762 .. [2] This footnote is labeled manually, so its number is fixed.
1764 .. [#label] This autonumber-labeled footnote will be labeled "1".
1765 It is the first auto-numbered footnote and no other footnote
1766 with label "1" exists. The order of the footnotes is used to
1767 determine numbering, not the order of the footnote references.
1769 .. [#] This footnote will be labeled "3". It is the second
1770 auto-numbered footnote, but footnote label "2" is already used.
1776 See also: `Citation References`_.
1778 Doctree element: citation_
1780 Citations are identical to footnotes except that they use only
1781 non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation
1782 labels are simple `reference names`_ (case-insensitive single words
1783 consisting of alphanumerics plus internal hyphens, underscores, and
1784 periods; no whitespace). Citations may be rendered separately and
1785 differently from footnotes. For example::
1787 Here is a citation reference: [CIT2002]_.
1789 .. [CIT2002] This is the citation. It's just like a footnote,
1790 except the label is textual.
1798 Doctree element: target_.
1800 These are also called _`explicit hyperlink targets`, to differentiate
1801 them from `implicit hyperlink targets`_ defined below.
1803 Hyperlink targets identify a location within or outside of a document,
1804 which may be linked to by `hyperlink references`_.
1806 Hyperlink targets may be named or anonymous. Named hyperlink targets
1807 consist of an explicit markup start (".. "), an underscore, the
1808 reference name (no trailing underscore), a colon, whitespace, and a
1811 .. _hyperlink-name: link-block
1813 Reference names are whitespace-neutral and case-insensitive. See
1814 `Reference Names`_ for details and examples.
1816 Anonymous hyperlink targets consist of an explicit markup start
1817 (".. "), two underscores, a colon, whitespace, and a link block; there
1818 is no reference name::
1820 .. __: anonymous-hyperlink-target-link-block
1822 An alternate syntax for anonymous hyperlinks consists of two
1823 underscores, a space, and a link block::
1825 __ anonymous-hyperlink-target-link-block
1827 See `Anonymous Hyperlinks`_ below.
1829 There are three types of hyperlink targets: internal, external, and
1832 1. _`Internal hyperlink targets` have empty link blocks. They provide
1833 an end point allowing a hyperlink to connect one place to another
1834 within a document. An internal hyperlink target points to the
1835 element following the target. [#]_ For example::
1837 Clicking on this internal hyperlink will take us to the target_
1842 The hyperlink target above points to this paragraph.
1844 Internal hyperlink targets may be "chained". Multiple adjacent
1845 internal hyperlink targets all point to the same element::
1850 The targets "target1" and "target2" are synonyms; they both
1851 point to this paragraph.
1853 If the element "pointed to" is an external hyperlink target (with a
1854 URI in its link block; see #2 below) the URI from the external
1855 hyperlink target is propagated to the internal hyperlink targets;
1856 they will all "point to" the same URI. There is no need to
1857 duplicate a URI. For example, all three of the following hyperlink
1858 targets refer to the same URI::
1860 .. _Python DOC-SIG mailing list archive:
1862 .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/
1864 An inline form of internal hyperlink target is available; see
1865 `Inline Internal Targets`_.
1867 .. [#] Works also, if the internal hyperlink target is "nested" at the
1868 end of an indented text block. This behaviour allows setting targets
1869 to individual list items (except the first, as a preceding internal
1870 target applies to the list as a whole)::
1876 * second item, with hyperlink target.
1879 2. _`External hyperlink targets` have an absolute or relative URI or
1880 email address in their link blocks. For example, take the
1883 See the Python_ home page for info.
1885 `Write to me`_ with your questions.
1887 .. _Python: http://www.python.org
1888 .. _Write to me: jdoe@example.com
1890 After processing into HTML, the hyperlinks might be expressed as::
1892 See the <a href="http://www.python.org">Python</a> home page
1895 <a href="mailto:jdoe@example.com">Write to me</a> with your
1898 An external hyperlink's URI may begin on the same line as the
1899 explicit markup start and target name, or it may begin in an
1900 indented text block immediately following, with no intervening
1901 blank lines. If there are multiple lines in the link block, they
1902 are concatenated. Any unescaped whitespace is removed (whitespace is
1903 permitted to allow for line wrapping). The following external
1904 hyperlink targets are equivalent::
1906 .. _one-liner: http://docutils.sourceforge.net/rst.html
1908 .. _starts-on-this-line: http://
1909 docutils.sourceforge.net/rst.html
1913 sourceforge.net/rst.html
1915 Escaped whitespace is preserved as intentional spaces, e.g.::
1917 .. _reference: ../local\ path\ with\ spaces.html
1919 If an external hyperlink target's URI contains an underscore as its
1920 last character, it must be escaped to avoid being mistaken for an
1921 indirect hyperlink target::
1923 This link_ refers to a file called ``underscore_``.
1925 .. _link: underscore\_
1927 It is possible (although not generally recommended) to include URIs
1928 directly within hyperlink references. See `Embedded URIs and Aliases`_
1931 3. _`Indirect hyperlink targets` have a hyperlink reference in their
1932 link blocks. In the following example, target "one" indirectly
1933 references whatever target "two" references, and target "two"
1934 references target "three", an internal hyperlink target. In
1935 effect, all three reference the same thing::
1941 Just as with `hyperlink references`_ anywhere else in a document,
1942 if a phrase-reference is used in the link block it must be enclosed
1943 in backquotes. As with `external hyperlink targets`_, the link
1944 block of an indirect hyperlink target may begin on the same line as
1945 the explicit markup start or the next line. It may also be split
1946 over multiple lines, in which case the lines are joined with
1947 whitespace before being normalized.
1949 For example, the following indirect hyperlink targets are
1952 .. _one-liner: `A HYPERLINK`_
1958 It is possible to include an alias directly within hyperlink
1959 references. See `Embedded URIs and Aliases`_ below.
1961 If the reference name contains any colons, either:
1963 - the phrase must be enclosed in backquotes::
1965 .. _`FAQTS: Computers: Programming: Languages: Python`:
1966 http://python.faqts.com/
1968 - or the colon(s) must be backslash-escaped in the link target::
1970 .. _Chapter One\: "Tadpole Days":
1972 It's not easy being green...
1974 See `Implicit Hyperlink Targets`_ below for the resolution of
1975 duplicate reference names.
1979 +-------+----------------------+
1980 | ".. " | "_" name ":" link |
1983 +----------------------+
1986 Anonymous Hyperlinks
1987 ....................
1989 The `World Wide Web Consortium`_ recommends in its `HTML Techniques
1990 for Web Content Accessibility Guidelines`_ that authors should
1991 "clearly identify the target of each link." Hyperlink references
1992 should be as verbose as possible, but duplicating a verbose hyperlink
1993 name in the target is onerous and error-prone. Anonymous hyperlinks
1994 are designed to allow convenient verbose hyperlink references, and are
1995 analogous to `Auto-Numbered Footnotes`_. They are particularly useful
1996 in short or one-off documents. However, this feature is easily abused
1997 and can result in unreadable plaintext and/or unmaintainable
1998 documents. Caution is advised.
2000 Anonymous `hyperlink references`_ are specified with two underscores
2003 See `the web site of my favorite programming language`__.
2005 Anonymous targets begin with ".. __:"; no reference name is required
2008 .. __: http://www.python.org
2010 As a convenient alternative, anonymous targets may begin with "__"
2013 __ http://www.python.org
2015 The reference name of the reference is not used to match the reference
2016 to its target. Instead, the order of anonymous hyperlink references
2017 and targets within the document is significant: the first anonymous
2018 reference will link to the first anonymous target. The number of
2019 anonymous hyperlink references in a document must match the number of
2020 anonymous targets. For readability, it is recommended that targets be
2021 kept close to references. Take care when editing text containing
2022 anonymous references; adding, removing, and rearranging references
2023 require attention to the order of corresponding targets.
2029 Doctree elements: depend on the directive.
2031 Directives are an extension mechanism for reStructuredText, a way of
2032 adding support for new constructs without adding new primary syntax
2033 (directives may support additional syntax locally). All standard
2034 directives (those implemented and registered in the reference
2035 reStructuredText parser) are described in the `reStructuredText
2036 Directives`_ document, and are always available. Any other directives
2037 are domain-specific, and may require special action to make them
2038 available when processing the document.
2040 For example, here's how an image_ may be placed::
2042 .. image:: mylogo.jpeg
2044 A figure_ (a graphic with a caption) may placed like this::
2046 .. figure:: larch.png
2050 An admonition_ (note, caution, etc.) contains other body elements::
2052 .. note:: This is a paragraph
2054 - Here is a bullet list.
2056 Directives are indicated by an explicit markup start (".. ") followed
2057 by the directive type, two colons, and whitespace (together called the
2058 "directive marker"). Directive types are case-insensitive single
2059 words (alphanumerics plus isolated internal hyphens, underscores,
2060 plus signs, colons, and periods; no whitespace). Two colons are used
2061 after the directive type for these reasons:
2063 - Two colons are distinctive, and unlikely to be used in common text.
2065 - Two colons avoids clashes with common comment text like::
2067 .. Danger: modify at your own risk!
2069 - If an implementation of reStructuredText does not recognize a
2070 directive (i.e., the directive-handler is not installed), a level-3
2071 (error) system message is generated, and the entire directive block
2072 (including the directive itself) will be included as a literal
2073 block. Thus "::" is a natural choice.
2075 The directive block consists of any text on the first line of the
2076 directive after the directive marker, and any subsequent indented
2077 text. The interpretation of the directive block is up to the
2078 directive code. There are three logical parts to the directive block:
2080 1. Directive arguments.
2081 2. Directive options.
2082 3. Directive content.
2084 Individual directives can employ any combination of these parts.
2085 Directive arguments can be filesystem paths, URLs, title text, etc.
2086 Directive options are indicated using `field lists`_; the field names
2087 and contents are directive-specific. Arguments and options must form
2088 a contiguous block beginning on the first or second line of the
2089 directive; a blank line indicates the beginning of the directive
2090 content block. If either arguments and/or options are employed by the
2091 directive, a blank line must separate them from the directive content.
2092 The "figure" directive employs all three parts::
2094 .. figure:: larch.png
2099 Simple directives may not require any content. If a directive that
2100 does not employ a content block is followed by indented text anyway,
2101 it is an error. If a block quote should immediately follow a
2102 directive, use an empty comment in-between (see Comments_ below).
2104 Actions taken in response to directives and the interpretation of text
2105 in the directive content block or subsequent text block(s) are
2106 directive-dependent. See `reStructuredText Directives`_ for details.
2108 Directives are meant for the arbitrary processing of their contents,
2109 which can be transformed into something possibly unrelated to the
2110 original text. It may also be possible for directives to be used as
2111 pragmas, to modify the behavior of the parser, such as to experiment
2112 with alternate syntax. There is no parser support for this
2113 functionality at present; if a reasonable need for pragma directives
2114 is found, they may be supported.
2116 Directives do not generate "directive" elements; they are a *parser
2117 construct* only, and have no intrinsic meaning outside of
2118 reStructuredText. Instead, the parser will transform recognized
2119 directives into (possibly specialized) document elements. Unknown
2120 directives will trigger level-3 (error) system messages.
2124 +-------+-------------------------------+
2125 | ".. " | directive type "::" directive |
2128 +-------------------------------+
2131 Substitution Definitions
2132 ````````````````````````
2134 Doctree element: substitution_definition_.
2136 Substitution definitions are indicated by an explicit markup start
2137 (".. ") followed by a vertical bar, the substitution text, another
2138 vertical bar, whitespace, and the definition block. Substitution text
2139 may not begin or end with whitespace. A substitution definition block
2140 contains an embedded inline-compatible directive (without the leading
2141 ".. "), such as "image_" or "replace_". For example::
2143 The |biohazard| symbol must be used on containers used to
2144 dispose of medical waste.
2146 .. |biohazard| image:: biohazard.png
2148 It is an error for a substitution definition block to directly or
2149 indirectly contain a circular substitution reference.
2151 `Substitution references`_ are replaced in-line by the processed
2152 contents of the corresponding definition (linked by matching
2153 substitution text). Matches are case-sensitive but forgiving; if no
2154 exact match is found, a case-insensitive comparison is attempted.
2156 Substitution definitions allow the power and flexibility of
2157 block-level directives_ to be shared by inline text. They are a way
2158 to include arbitrarily complex inline structures within text, while
2159 keeping the details out of the flow of text. They are the equivalent
2160 of SGML/XML's named entities or programming language macros.
2162 Without the substitution mechanism, every time someone wants an
2163 application-specific new inline structure, they would have to petition
2164 for a syntax change. In combination with existing directive syntax,
2165 any inline structure can be coded without new syntax (except possibly
2170 +-------+-----------------------------------------------------+
2171 | ".. " | "|" substitution text "| " directive type "::" data |
2172 +-------+ directive block |
2174 +-----------------------------------------------------+
2176 Following are some use cases for the substitution mechanism. Please
2177 note that most of the embedded directives shown are examples only and
2178 have not been implemented.
2181 Substitution references may be used to associate ambiguous text
2182 with a unique object identifier.
2184 For example, many sites may wish to implement an inline "user"
2187 |Michael| and |Jon| are our widget-wranglers.
2189 .. |Michael| user:: mjones
2192 Depending on the needs of the site, this may be used to index the
2193 document for later searching, to hyperlink the inline text in
2194 various ways (mailto, homepage, mouseover Javascript with profile
2195 and contact information, etc.), or to customize presentation of
2196 the text (include username in the inline text, include an icon
2197 image with a link next to the text, make the text bold or a
2198 different color, etc.).
2200 The same approach can be used in documents which frequently refer
2201 to a particular type of objects with unique identifiers but
2202 ambiguous common names. Movies, albums, books, photos, court
2203 cases, and laws are possible. For example::
2205 |The Transparent Society| offers a fascinating alternate view
2208 .. |The Transparent Society| book:: isbn=0738201448
2210 Classes or functions, in contexts where the module or class names
2211 are unclear and/or interpreted text cannot be used, are another
2214 4XSLT has the convenience method |runString|, so you don't
2215 have to mess with DOM objects if all you want is the
2218 .. |runString| function:: module=xml.xslt class=Processor
2221 Images are a common use for substitution references::
2223 West led the |H| 3, covered by dummy's |H| Q, East's |H| K,
2224 and trumped in hand with the |S| 2.
2226 .. |H| image:: /images/heart.png
2229 .. |S| image:: /images/spade.png
2233 * |Red light| means stop.
2234 * |Green light| means go.
2235 * |Yellow light| means go really fast.
2237 .. |Red light| image:: red_light.png
2238 .. |Green light| image:: green_light.png
2239 .. |Yellow light| image:: yellow_light.png
2241 |-><-| is the official symbol of POEE_.
2243 .. |-><-| image:: discord.png
2244 .. _POEE: http://www.poee.org/
2246 The "image_" directive has been implemented.
2249 Substitution references may be used to associate inline text with
2250 an externally defined presentation style::
2252 Even |the text in Texas| is big.
2254 .. |the text in Texas| style:: big
2256 The style name may be meaningful in the context of some particular
2257 output format (CSS class name for HTML output, LaTeX style name
2258 for LaTeX, etc), or may be ignored for other output formats (such
2261 .. @@@ This needs to be rethought & rewritten or removed:
2263 Interpreted text is unsuitable for this purpose because the set
2264 of style names cannot be predefined - it is the domain of the
2265 content author, not the author of the parser and output
2266 formatter - and there is no way to associate a style name
2267 argument with an interpreted text style role. Also, it may be
2268 desirable to use the same mechanism for styling blocks::
2271 At Bob's Underwear Shop, we'll do anything to get in
2274 .. style:: disclaimer
2275 All rights reversed. Reprint what you like.
2277 .. [#] There may be sufficient need for a "style" mechanism to
2278 warrant simpler syntax such as an extension to the interpreted
2279 text role syntax. The substitution mechanism is cumbersome for
2280 simple text styling.
2283 Inline markup may be used for later processing by a template
2284 engine. For example, a Zope_ author might write::
2286 Welcome back, |name|!
2288 .. |name| tal:: replace user/getUserName
2290 After processing, this ZPT output would result::
2293 <span tal:replace="user/getUserName">name</span>!
2295 Zope would then transform this to something like "Welcome back,
2296 David!" during a session with an actual user.
2299 The substitution mechanism may be used for simple macro
2300 substitution. This may be appropriate when the replacement text
2301 is repeated many times throughout one or more documents,
2302 especially if it may need to change later. A short example is
2303 unavoidably contrived::
2305 |RST|_ is a little annoying to type over and over, especially
2306 when writing about |RST| itself, and spelling out the
2307 bicapitalized word |RST| every time isn't really necessary for
2308 |RST| source readability.
2310 .. |RST| replace:: reStructuredText
2311 .. _RST: http://docutils.sourceforge.net/rst.html
2313 Note the trailing underscore in the first use of a substitution
2314 reference. This indicates a reference to the corresponding
2317 Substitution is also appropriate when the replacement text cannot
2318 be represented using other inline constructs, or is obtrusively
2321 But still, that's nothing compared to a name like
2324 .. |j2ee-cas| replace::
2325 the Java `TM`:super: 2 Platform, Enterprise Edition Client
2327 __ http://developer.java.sun.com/developer/earlyAccess/
2330 The "replace_" directive has been implemented.
2336 Doctree element: comment_.
2338 `Explicit markup blocks`_ that are not recognized as citations_,
2339 directives_, footnotes_, `hyperlink targets`_, or `substitution
2340 definitions`_ will be processed as a comment element. Arbitrary
2341 indented text may be used on the lines following the explicit markup
2342 start. To ensure that none of the other explicit markup constructs is
2343 recognized, leave the ".." on a line by itself::
2345 .. This is a comment
2355 .. [this] however, is a citation.
2357 Apart from removing the maximum common indentation, no further
2358 processing is done on the content; a comment contains a single "text
2359 blob". Depending on the output formatter, comments may be removed
2360 from the processed output.
2364 +-------+----------------------+
2368 +----------------------+
2373 An explicit markup start followed by a blank line and nothing else
2374 (apart from whitespace) is an "_`empty comment`". It serves to
2375 terminate a preceding construct, and does **not** consume any indented
2376 text following. To have a block quote follow a list or any indented
2377 construct, insert an unindented empty comment in-between::
2384 This is a block quote.
2386 Implicit Hyperlink Targets
2387 ==========================
2389 Implicit hyperlink targets are generated by section titles, footnotes,
2390 and citations, and may also be generated by extension constructs.
2391 Implicit hyperlink targets otherwise behave identically to explicit
2392 `hyperlink targets`_.
2394 Problems of ambiguity due to conflicting duplicate implicit and
2395 explicit reference names are avoided by following this procedure:
2397 1. `Explicit hyperlink targets`_ override any implicit targets having
2398 the same reference name. The implicit hyperlink targets are
2399 removed, and level-1 (info) system messages are inserted.
2401 2. Duplicate implicit hyperlink targets are removed, and level-1
2402 (info) system messages inserted. For example, if two or more
2403 sections have the same title (such as "Introduction" subsections of
2404 a rigidly-structured document), there will be duplicate implicit
2407 3. Duplicate explicit hyperlink targets are removed, and level-2
2408 (warning) system messages are inserted. Exception: duplicate
2409 `external hyperlink targets`_ (identical hyperlink names and
2410 referenced URIs) do not conflict, and are not removed.
2412 System messages are inserted where target links have been removed.
2413 See "Error Handling" in `PEP 258`_.
2415 The parser must return a set of *unique* hyperlink targets. The
2416 calling software (such as the Docutils_) can warn of unresolvable
2417 links, giving reasons for the messages.
2423 In reStructuredText, inline markup applies to words or phrases within
2424 a text block. The same whitespace and punctuation that serves to
2425 delimit words in written text is used to delimit the inline markup
2426 syntax constructs (see the `inline markup recognition rules`_ for
2427 details). The text within inline markup may not begin or end with
2428 whitespace. Arbitrary `character-level inline markup`_ is supported
2429 although not encouraged. Inline markup cannot be nested.
2431 There are nine inline markup constructs. Five of the constructs use
2432 identical start-strings and end-strings to indicate the markup:
2435 - `strong emphasis`_: "**"
2436 - `interpreted text`_: "`"
2437 - `inline literals`_: "``"
2438 - `substitution references`_: "|"
2440 Three constructs use different start-strings and end-strings:
2442 - `inline internal targets`_: "_`" and "`"
2443 - `footnote references`_: "[" and "]_"
2444 - `hyperlink references`_: "`" and "\`_" (phrases), or just a
2445 trailing "_" (single words)
2447 `Standalone hyperlinks`_ are recognized implicitly, and use no extra
2450 Inline comments are not supported.
2453 Inline markup recognition rules
2454 -------------------------------
2456 Inline markup start-strings and end-strings are only recognized if
2457 the following conditions are met:
2459 1. Inline markup start-strings must be immediately followed by
2462 2. Inline markup end-strings must be immediately preceded by
2465 3. The inline markup end-string must be separated by at least one
2466 character from the start-string.
2468 4. Both, inline markup start-string and end-string must not be preceded by
2469 an unescaped backslash (except for the end-string of `inline literals`_).
2470 See `Escaping Mechanism`_ above for details.
2472 5. If an inline markup start-string is immediately preceded by one of the
2473 ASCII characters ``' " < ( [ {`` or a similar
2474 non-ASCII character [#openers]_, it must not be followed by the
2475 corresponding closing character from ``' " ) ] } >`` or a similar non-ASCII
2476 character [#closers]_. (For quotes, matching characters can be any of
2477 the `quotation marks in international usage`_.)
2479 If the configuration setting `simple-inline-markup`_ is False (default),
2480 additional conditions apply to the characters "around" the
2483 6. Inline markup start-strings must start a text block or be
2484 immediately preceded by
2487 * one of the ASCII characters ``- : / ' " < ( [ {``
2488 * or a similar non-ASCII punctuation character. [#pre-chars]_
2490 7. Inline markup end-strings must end a text block or be immediately
2494 * one of the ASCII characters ``- . , : ; ! ? \ / ' " ) ] } >``
2495 * or a similar non-ASCII punctuation character. [#post-chars]_
2497 .. [#openers] `Unicode categories`_ `Ps` (Open), `Pi` (Initial quote),
2498 or `Pf` (Final quote). [#uni-version]_
2499 .. [#closers] Unicode categories `Pe` (Close), `Pi` (Initial quote),
2500 or `Pf` (Final quote). [#uni-version]_
2501 .. [#pre-chars] Unicode categories `Ps` (Open), `Pi` (Initial quote),
2502 `Pf` (Final quote), `Pd` (Dash), or `Po` (Other). [#uni-version]_
2503 .. [#post-chars] Unicode categories `Pe` (Close), `Pi` (Initial quote),
2504 `Pf` (Final quote), `Pd` (Dash), or `Po` (Other). [#uni-version]_
2506 .. [#uni-version] The category of some characters changed with the
2507 development of the Unicode standard.
2508 Docutils 0.13 uses `Unicode version 5.2.0`_.
2510 .. _Unicode categories:
2511 http://www.unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values
2512 .. _Unicode version 5.2.0: http://www.unicode.org/Public/5.2.0/
2513 .. _quotation marks in international usage:
2514 http://en.wikipedia.org/wiki/Quotation_mark,_non-English_usage
2516 The inline markup recognition rules were devised to allow 90% of non-markup
2517 uses of "*", "`", "_", and "|" without escaping. For example, none of the
2518 following terms are recognized as containing inline markup strings:
2520 - 2 * x a ** b (* BOM32_* ` `` _ __ | (breaks rule 1)
2521 - || (breaks rule 3)
2522 - "*" '|' (*) [*] {*} <*>
2525 »*« ›*‹ «*» »*» ›*› (breaks rule 5)
2526 - 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.*
2527 __init__ __init__() (breaks rule 6)
2529 No escaping is required inside the following inline markup examples:
2531 - ``*2 * x *a **b *.txt*`` (breaks rule 2; renders as "*2 * x *a **b *.txt*")
2532 - ``*2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)*``
2533 (breaks rule 7; renders as "*2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)*")
2535 It may be desirable to use `inline literals`_ for some of these anyhow,
2536 especially if they represent code snippets. It's a judgment call.
2538 The following terms *do* require either literal-quoting or escaping to avoid
2541 *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt
2543 In most use cases, `inline literals`_ or `literal blocks`_ are the best
2544 choice (by default, this also selects a monospaced font). Alternatively, the
2545 inline markup characters can be escaped::
2547 \*4, class\_, \*args, \**kwargs, \`TeX-quoted', \*ML, \*.txt
2550 For languages that don't use whitespace between words (e.g. Japanese or
2551 Chinese) it is recommended to set `simple-inline-markup`_ to True and
2552 eventually escape inline markup characters.
2553 The examples breaking rules 6 and 7 above show which constructs may need
2557 .. _simple-inline-markup: ../../user/config.html#simple-inline-markup
2563 Inline markup delimiter characters are used for multiple constructs,
2564 so to avoid ambiguity there must be a specific recognition order for
2565 each character. The inline markup recognition order is as follows:
2567 - Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_
2570 - Backquotes: `Inline literals`_ ("``"), `inline internal targets`_
2571 (leading "_`", trailing "`"), are mutually independent, and are
2572 recognized before phrase `hyperlink references`_ (leading "`",
2573 trailing "\`_") and `interpreted text`_ ("`").
2575 - Trailing underscores: Footnote references ("[" + label + "]_") and
2576 simple `hyperlink references`_ (name + trailing "_") are mutually
2579 - Vertical bars: `Substitution references`_ ("|") are independently
2582 - `Standalone hyperlinks`_ are the last to be recognized.
2585 Character-Level Inline Markup
2586 -----------------------------
2588 It is possible to mark up individual characters within a word with
2589 backslash escapes (see `Escaping Mechanism`_ above). Backslash
2590 escapes can be used to allow arbitrary text to immediately follow
2593 Python ``list``\s use square bracket syntax.
2595 The backslash will disappear from the processed document. The word
2596 "list" will appear as inline literal text, and the letter "s" will
2597 immediately follow it as normal text, with no space in-between.
2599 Arbitrary text may immediately precede inline markup using
2600 backslash-escaped whitespace::
2602 Possible in *re*\ ``Structured``\ *Text*, though not encouraged.
2604 The backslashes and spaces separating "re", "Structured", and "Text"
2605 above will disappear from the processed document.
2609 The use of backslash-escapes for character-level inline markup is
2610 not encouraged. Such use is ugly and detrimental to the
2611 unprocessed document's readability. Please use this feature
2612 sparingly and only where absolutely necessary.
2618 Doctree element: emphasis_.
2620 Start-string = end-string = "*".
2622 Text enclosed by single asterisk characters is emphasized::
2624 This is *emphasized text*.
2626 Emphasized text is typically displayed in italics.
2632 Doctree element: strong_.
2634 Start-string = end-string = "**".
2636 Text enclosed by double-asterisks is emphasized strongly::
2638 This is **strong text**.
2640 Strongly emphasized text is typically displayed in boldface.
2646 Doctree element: depends on the explicit or implicit role and
2649 Start-string = end-string = "`".
2651 Interpreted text is text that is meant to be related, indexed, linked,
2652 summarized, or otherwise processed, but the text itself is typically
2653 left alone. Interpreted text is enclosed by single backquote
2656 This is `interpreted text`.
2658 The "role" of the interpreted text determines how the text is
2659 interpreted. The role may be inferred implicitly (as above; the
2660 "default role" is used) or indicated explicitly, using a role marker.
2661 A role marker consists of a colon, the role name, and another colon.
2662 A role name is a single word consisting of alphanumerics plus isolated
2663 internal hyphens, underscores, plus signs, colons, and periods;
2664 no whitespace or other characters are allowed. A role marker is
2665 either a prefix or a suffix to the interpreted text, whichever reads
2666 better; it's up to the author::
2668 :role:`interpreted text`
2670 `interpreted text`:role:
2672 Interpreted text allows extensions to the available inline descriptive
2673 markup constructs. To emphasis_, `strong emphasis`_, `inline
2674 literals`_, and `hyperlink references`_, we can add "title reference",
2675 "index entry", "acronym", "class", "red", "blinking" or anything else
2676 we want (as long as it is a simple `reference name`_).
2677 Only pre-determined roles are recognized; unknown roles will
2678 generate errors. A core set of standard roles is implemented in the
2679 reference parser; see `reStructuredText Interpreted Text Roles`_ for
2680 individual descriptions. The role_ directive can be used to define
2681 custom interpreted text roles. In addition, applications may support
2684 In `field lists`_, care must be taken when using interpreted text with
2685 explicit roles in field names: the role must be a suffix to the
2686 interpreted text. The following are recognized as field list items::
2688 :`field name`:code:: interpreted text with explicit role as suffix
2690 :a `complex`:code:\ field name: a backslash-escaped space
2693 The following are **not** recognized as field list items::
2695 ::code:`not a field name`: paragraph with interpreted text
2697 :code:`not a field name`: paragraph with interpreted text
2701 :field\:`name`: interpreted text (standard role) requires
2702 escaping the leading colon in a field name
2704 :field:\`name`: not interpreted text
2710 Doctree element: literal_.
2712 Start-string = end-string = "``".
2714 Text enclosed by double-backquotes is treated as inline literals::
2716 This text is an example of ``inline literals``.
2718 Inline literals may contain any characters except two adjacent
2719 backquotes in an end-string context (according to the recognition
2720 rules above). No markup interpretation (including backslash-escape
2721 interpretation) is done within inline literals.
2723 Line breaks are *not* preserved in inline literals. Although a
2724 reStructuredText parser will preserve runs of spaces in its output,
2725 the final representation of the processed document is dependent on the
2726 output formatter, thus the preservation of whitespace cannot be
2727 guaranteed. If the preservation of line breaks and/or other
2728 whitespace is important, `literal blocks`_ should be used.
2730 Inline literals are useful for short code snippets. For example::
2732 The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches
2733 floating-point numbers (without exponents).
2736 Hyperlink References
2737 --------------------
2739 Doctree element: reference_.
2741 - Named hyperlink references:
2743 - No start-string, end-string = "_".
2744 - Start-string = "`", end-string = "\`_". (Phrase references.)
2746 - Anonymous hyperlink references:
2748 - No start-string, end-string = "__".
2749 - Start-string = "`", end-string = "\`__". (Phrase references.)
2751 Hyperlink references are indicated by a trailing underscore, "_",
2752 except for `standalone hyperlinks`_ which are recognized
2753 independently. The underscore can be thought of as a right-pointing
2754 arrow. The trailing underscores point away from hyperlink references,
2755 and the leading underscores point toward `hyperlink targets`_.
2757 Hyperlinks consist of two parts. In the text body, there is a source
2758 link, a reference name with a trailing underscore (or two underscores
2759 for `anonymous hyperlinks`_)::
2761 See the Python_ home page for info.
2763 A target link with a matching reference name must exist somewhere else
2764 in the document. See `Hyperlink Targets`_ for a full description).
2766 `Anonymous hyperlinks`_ (which see) do not use reference names to
2767 match references to targets, but otherwise behave similarly to named
2771 Embedded URIs and Aliases
2772 `````````````````````````
2774 A hyperlink reference may directly embed a target URI or (since
2775 Docutils 0.11) a hyperlink reference within angle brackets ("<...>")
2778 See the `Python home page <http://www.python.org>`_ for info.
2780 This `link <Python home page_>`_ is an alias to the link above.
2782 This is exactly equivalent to::
2784 See the `Python home page`_ for info.
2786 This link_ is an alias to the link above.
2788 .. _Python home page: http://www.python.org
2789 .. _link: `Python home page`_
2791 The bracketed URI must be preceded by whitespace and be the last text
2792 before the end string.
2794 With a single trailing underscore, the reference is named and the same
2795 target URI may be referred to again.
2796 With two trailing underscores, the reference and target are both
2797 anonymous, and the target cannot be referred to again. These are
2798 "one-off" hyperlinks. For example::
2800 `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2801 2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
2802 define the syntax of URIs.
2806 `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs.
2808 __ http://www.rfc-editor.org/rfc/rfc2396.txt
2809 __ http://www.rfc-editor.org/rfc/rfc2732.txt
2811 `Standalone hyperlinks`_ are treated as URIs, even if they end with an
2812 underscore like in the example of a Python function documentation::
2814 `__init__ <http:example.py.html#__init__>`__
2816 If a target URI that is not recognized as `standalone hyperlink`_ happens
2817 to end with an underscore, this needs to be backslash-escaped to avoid
2818 being parsed as hyperlink reference. For example ::
2820 Use the `source <parrots.txt\_>`__.
2822 creates an anonymous reference to the file ``parrots.txt_``.
2824 If the reference text happens to end with angle-bracketed text that is
2825 *not* a URI or hyperlink reference, at least one angle-bracket needs to
2826 be backslash-escaped or an escaped space should follow. For example, here
2827 are three references to titles describing a tag::
2829 See `HTML Element: \<a>`_, `HTML Element: <b\> `_, and
2830 `HTML Element: <c>\ `_.
2832 The reference text may also be omitted, in which case the URI will be
2833 duplicated for use as the reference text. This is useful for relative
2834 URIs where the address or file name is also the desired reference
2837 See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__
2842 This construct offers easy authoring and maintenance of hyperlinks
2843 at the expense of general readability. Inline URIs, especially
2844 long ones, inevitably interrupt the natural flow of text. For
2845 documents meant to be read in source form, the use of independent
2846 block-level `hyperlink targets`_ is **strongly recommended**. The
2847 embedded URI construct is most suited to documents intended *only*
2848 to be read in processed form.
2851 Inline Internal Targets
2852 ------------------------
2854 Doctree element: target_.
2856 Start-string = "_`", end-string = "`".
2858 Inline internal targets are the equivalent of explicit `internal
2859 hyperlink targets`_, but may appear within running text. The syntax
2860 begins with an underscore and a backquote, is followed by a hyperlink
2861 name or phrase, and ends with a backquote. Inline internal targets
2862 may not be anonymous.
2864 For example, the following paragraph contains a hyperlink target named
2867 Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it?
2869 See `Implicit Hyperlink Targets`_ for the resolution of duplicate
2876 See also: Footnotes_
2878 Doctree element: footnote_reference_.
2880 Configuration settings:
2881 `footnote_references <footnote_references setting_>`_,
2882 trim_footnote_reference_space_.
2884 .. _trim_footnote_reference_space:
2885 ../../user/config.html#trim-footnote-reference-space
2887 Start-string = "[", end-string = "]_".
2889 Each footnote reference consists of a square-bracketed label followed
2890 by a trailing underscore. Footnote labels are one of:
2892 - one or more digits (i.e., a number),
2894 - a single "#" (denoting `auto-numbered footnotes`_),
2896 - a "#" followed by a simple `reference name`_ (an `autonumber label`_),
2899 - a single "*" (denoting `auto-symbol footnotes`_).
2905 .. [1] Read The Fine Manual
2907 `Inline markup recognition rules`_ may require whitespace in front of the
2908 footnote reference. To remove the whitespace from the output, use an
2909 escaped whitespace character (see `Escaping Mechanism`_) or set the
2910 trim_footnote_reference_space_ configuration setting. Leading whitespace
2911 is removed by default, if the `footnote_references setting`_ is
2918 See also: Citations_
2920 Doctree element: citation_reference_.
2922 Start-string = "[", end-string = "]_".
2924 Each citation reference consists of a square-bracketed label followed
2925 by a trailing underscore. Citation labels are simple `reference
2926 names`_ (case-insensitive single words, consisting of alphanumerics
2927 plus internal hyphens, underscores, and periods; no whitespace).
2931 Here is a citation reference: [CIT2002]_.
2934 Substitution References
2935 -----------------------
2937 Doctree elements: substitution_reference_, reference_.
2939 Start-string = "|", end-string = "|" (optionally followed by "_" or
2942 Vertical bars are used to bracket the substitution reference text. A
2943 substitution reference may also be a hyperlink reference by appending
2944 a "_" (named) or "__" (anonymous) suffix; the substitution text is
2945 used for the reference text in the named case.
2947 The processing system replaces substitution references with the
2948 processed contents of the corresponding `substitution definitions`_
2949 (which see for the definition of "correspond"). Substitution
2950 definitions produce inline-compatible elements.
2954 This is a simple |substitution reference|. It will be replaced by
2955 the processing system.
2957 This is a combination |substitution and hyperlink reference|_. In
2958 addition to being replaced, the replacement text or element will
2959 refer to the "substitution and hyperlink reference" target.
2961 .. _standalone hyperlink:
2963 Standalone Hyperlinks
2964 ---------------------
2966 Doctree element: reference_.
2968 No start-string or end-string.
2970 A URI (absolute URI [#URI]_ or standalone email address) within a text
2971 block is treated as a general external hyperlink with the URI itself
2972 as the link's text. For example::
2974 See http://www.python.org for info.
2976 would be marked up in HTML as::
2978 See <a href="http://www.python.org">http://www.python.org</a> for
2981 Two forms of URI are recognized:
2983 1. Absolute URIs. These consist of a scheme, a colon (":"), and a
2984 scheme-specific part whose interpretation depends on the scheme.
2986 The scheme is the name of the protocol, such as "http", "ftp",
2987 "mailto", or "telnet". The scheme consists of an initial letter,
2988 followed by letters, numbers, and/or "+", "-", ".". Recognition is
2989 limited to known schemes, per the `Official IANA Registry of URI
2990 Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_.
2992 The scheme-specific part of the resource identifier may be either
2993 hierarchical or opaque:
2995 - Hierarchical identifiers begin with one or two slashes and may
2996 use slashes to separate hierarchical components of the path.
2997 Examples are web pages and FTP sites::
2999 http://www.python.org
3001 ftp://ftp.python.org/pub/python
3003 - Opaque identifiers do not begin with slashes. Examples are
3004 email addresses and newsgroups::
3006 mailto:someone@somewhere.com
3008 news:comp.lang.python
3010 With queries, fragments, and %-escape sequences, URIs can become
3011 quite complicated. A reStructuredText parser must be able to
3012 recognize any absolute URI, as defined in RFC2396_ and RFC2732_.
3014 2. Standalone email addresses, which are treated as if they were
3015 absolute URIs with a "mailto:" scheme. Example::
3017 someone@somewhere.com
3019 Punctuation at the end of a URI is not considered part of the URI,
3020 unless the URI is terminated by a closing angle bracket (">").
3021 Backslashes may be used in URIs to escape markup characters,
3022 specifically asterisks ("*") and underscores ("_") which are valid URI
3023 characters (see `Escaping Mechanism`_ above).
3025 .. [#URI] Uniform Resource Identifier. URIs are a general form of
3026 URLs (Uniform Resource Locators). For the syntax of URIs see
3027 RFC2396_ and RFC2732_.
3033 (New in Docutils 0.3.10.)
3035 All measures consist of a positive floating point number in standard
3036 (non-scientific) notation and a unit, possibly separated by one or
3039 Units are only supported where explicitly mentioned in the reference
3046 The following length units are supported by the reStructuredText
3049 * em (em unit, the element's font size)
3050 * ex (ex unit, x-height of the element’s font)
3051 * mm (millimeters; 1 mm = 1/1000 m)
3052 * cm (centimeters; 1 cm = 10 mm)
3053 * in (inches; 1 in = 2.54 cm = 96 px)
3054 * px (pixels, 1 px = 1/96 in) [#]_
3055 * pt (points; 1 pt = 1/72 in)
3056 * pc (picas; 1 pc = 1/6 in = 12 pt)
3058 This set corresponds to the `length units in CSS2`_ (a subset of `length
3061 .. [#] In LaTeX, the default definition is 1 px = 1/72 in (cf. `How to
3062 configure the size of a pixel`_ in the LaTeX writer documentation).
3064 The following are all valid length values: "1.5em", "20 mm", ".5in".
3066 Length values without unit are completed with a writer-dependent
3067 default (e.g. "px" with HTML, "pt" with `latex2e`). See the writer
3068 specific documentation in the `user doc`__ for details.
3070 .. _length units in CSS2:
3071 http://www.w3.org/TR/CSS2/syndata.html#length-units
3072 .. _length units in CSS3:
3073 http://www.w3.org/TR/css-values-3/#absolute-lengths
3074 .. _How to configure the size of a pixel:
3075 ../../user/latex.html#size-of-a-pixel
3082 Percentage values have a percent sign ("%") as unit. Percentage
3083 values are relative to other values, depending on the context in which
3091 Doctree elements: system_message_, problematic_.
3093 Markup errors are handled according to the specification in `PEP
3097 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
3098 .. _Docutils: http://docutils.sourceforge.net/
3099 .. _Docutils Generic DTD: ../docutils.dtd
3101 http://docutils.sourceforge.net/docutils/transforms/
3102 .. _Grouch: http://www.mems-exchange.org/software/grouch/
3103 .. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt
3104 .. _DocTitle transform:
3105 .. _DocInfo transform:
3106 http://docutils.sourceforge.net/docutils/transforms/frontmatter.py
3108 http://www.python.org/doc/current/lib/module-getopt.html
3109 .. _GNU libc getopt_long():
3110 http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html
3112 http://www.python.org/doc/current/lib/module-doctest.html
3113 .. _Emacs table mode: http://table.sourceforge.net/
3114 .. _Official IANA Registry of URI Schemes:
3115 http://www.iana.org/assignments/uri-schemes
3116 .. _Retired Index of WWW Addressing Schemes:
3117 http://www.w3.org/Addressing/schemes.html
3118 .. _World Wide Web Consortium: http://www.w3.org/
3119 .. _HTML Techniques for Web Content Accessibility Guidelines:
3120 http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text
3121 .. _reStructuredText Directives: directives.html
3122 .. _admonition: directives.html#admonitions
3123 .. _figure: directives.html#figure
3124 .. _image: directives.html#image
3125 .. _meta: directives.html#metadata
3126 .. _replace: directives.html#replace
3127 .. _role: directives.html#custom-interpreted-text-roles
3128 .. _table directive: directives.html#table
3129 .. _list table: directives.html#list-table
3130 .. _CSV table: directives.html#csv-table
3131 .. _reStructuredText Interpreted Text Roles: roles.html
3132 .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt
3133 .. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt
3134 .. _Zope: http://www.zope.com/
3135 .. _PEP 258: ../../peps/pep-0258.html
3137 .. _The Docutils Document Tree: ../doctree.html
3138 .. _"classes" attribute: ../doctree.html#classes
3139 .. _topic: ../doctree.html#topic
3140 .. _address: ../doctree.html#address
3141 .. _author: ../doctree.html#author
3142 .. _authors: ../doctree.html#authors
3143 .. _contact: ../doctree.html#contact
3144 .. _copyright: ../doctree.html#copyright
3145 .. _date: ../doctree.html#date
3146 .. _topic: ../doctree.html#topic
3147 .. _organization: ../doctree.html#organization
3148 .. _revision: ../doctree.html#revision
3149 .. _status: ../doctree.html#status
3150 .. _version: ../doctree.html#version
3151 .. _docinfo: ../doctree.html#docinfo
3152 .. _field: ../doctree.html#field
3153 .. _section: ../doctree.html#section
3154 .. _bullet_list: ../doctree.html#bullet-list
3155 .. _list_item: ../doctree.html#list-item
3156 .. _enumerated_list: ../doctree.html#enumerated-list
3157 .. _list_item: ../doctree.html#list-item
3158 .. _definition_list: ../doctree.html#definition-list
3159 .. _definition_list_item: ../doctree.html#definition-list-item
3160 .. _term: ../doctree.html#term
3161 .. _classifier: ../doctree.html#classifier
3162 .. _definition: ../doctree.html#definition
3163 .. _field_list: ../doctree.html#field-list
3164 .. _field_name: ../doctree.html#field-name
3165 .. _field_body: ../doctree.html#field-body
3166 .. _option_list: ../doctree.html#option-list
3167 .. _option_list_item: ../doctree.html#option-list-item
3168 .. _option_group: ../doctree.html#option-group
3169 .. _option: ../doctree.html#option
3170 .. _option_string: ../doctree.html#option-string
3171 .. _option_argument: ../doctree.html#option-argument
3172 .. _description: ../doctree.html#description
3173 .. _line_block: ../doctree.html#line-block
3174 .. _line: ../doctree.html#line
3175 .. _table: ../doctree.html#table
3176 .. _tgroup: ../doctree.html#tgroup
3177 .. _colspec: ../doctree.html#colspec
3178 .. _thead: ../doctree.html#thead
3179 .. _tbody: ../doctree.html#tbody
3180 .. _title: ../doctree.html#title
3181 .. _row: ../doctree.html#row
3182 .. _entry: ../doctree.html#entry
3183 .. _identifier key: ../doctree.html#identifier-keys
3184 .. _document element: ../doctree.html#document
3185 .. _footnote: ../doctree.html#footnote
3186 .. _label: ../doctree.html#label
3187 .. _citation: ../doctree.html#citation
3188 .. _target: ../doctree.html#target
3189 .. _footnote_reference: ../doctree.html#footnote-reference
3190 .. _citation_reference: ../doctree.html#citation-reference
3191 .. _transition: ../doctree.html#transition
3192 .. _paragraph: ../doctree.html#paragraph
3193 .. _literal_block: ../doctree.html#literal-block
3194 .. _block_quote: ../doctree.html#block-quote
3195 .. _attribution: ../doctree.html#attribution
3196 .. _doctest_block: ../doctree.html#doctest-block
3197 .. _substitution_definition: ../doctree.html#substitution-definition
3198 .. _comment: ../doctree.html#comment
3199 .. _strong: ../doctree.html#strong
3200 .. _literal: ../doctree.html#literal
3201 .. _reference: ../doctree.html#reference
3202 .. _substitution_reference: ../doctree.html#substitution-reference
3203 .. _reference: ../doctree.html#reference
3204 .. _reference: ../doctree.html#reference
3205 .. _system_message: ../doctree.html#system-message
3206 .. _problematic: ../doctree.html#problematic
3213 indent-tabs-mode: nil
3214 sentence-end-double-space: t