Merge lp:~mitya57/ubuntu/raring/python-docutils/updated-aliases-patch into lp:ubuntu/raring/python-docutils

[Dmitry Shachnev]

Note: I don't think this needs an FFe because this patch was present in previous version of the package before the FF, and disabling it was a quick work-around for the crash (please correct me if I'm wrong).

The patch is question makes it possible to always use links like

    `Example link <1_>`_

    .. _1: http://example.com

which is an useful feature for localized projects like Ubuntu Packaging Guide (it has been possible to *sometimes* use such links before, but now the support is consistent).

This patch was disabled in 0.10-1ubuntu2 because it caused python3.3 docs to fail to build. That crash could be possible without this patch, but the patch made it easier to trigger. The crash is now fixed in the new version, and also references that start with the URI scheme are now ignored and processed as in the previous versions (that ensures we don't break any existing projects).

All changes are covered by regression tests, which are run during build and on jenkins.ubuntu.com. I've verified that both Docutils and Sphinx test suites succeed, and that python3.3 docs build correctly.

=== modified file '.pc/applied-patches'
--- .pc/applied-patches	2013-03-06 14:34:02 +0000
+++ .pc/applied-patches	2013-03-19 07:30:29 +0000
@@ -8,3 +8,4 @@
 test-sys-path.diff
 move-data-to-usr-share.diff
 disable_py33_failing_tests.diff
+support-aliases-in-references.diff

=== added directory '.pc/support-aliases-in-references.diff'
=== added directory '.pc/support-aliases-in-references.diff/docs'
=== added directory '.pc/support-aliases-in-references.diff/docs/ref'
=== added directory '.pc/support-aliases-in-references.diff/docs/ref/rst'
=== added file '.pc/support-aliases-in-references.diff/docs/ref/rst/restructuredtext.txt'
--- .pc/support-aliases-in-references.diff/docs/ref/rst/restructuredtext.txt	1970-01-01 00:00:00 +0000
+++ .pc/support-aliases-in-references.diff/docs/ref/rst/restructuredtext.txt	2013-03-19 07:30:29 +0000
@@ -0,0 +1,2979 @@
+.. -*- coding: utf-8 -*-
+
+=======================================
+ reStructuredText Markup Specification
+=======================================
+
+:Author: David Goodger
+:Contact: [e-mail]
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03. Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+.. Note::
+
+   This document is a detailed technical specification; it is not a
+   tutorial or a primer.  If this is your first exposure to
+   reStructuredText, please read `A ReStructuredText Primer`_ and the
+   `Quick reStructuredText`_ user reference first.
+
+.. _A ReStructuredText Primer: ../../user/rst/quickstart.html
+.. _Quick reStructuredText: ../../user/rst/quickref.html
+
+
+reStructuredText_ is plaintext that uses simple and intuitive
+constructs to indicate the structure of a document.  These constructs
+are equally easy to read in raw and processed forms.  This document is
+itself an example of reStructuredText (raw, if you are reading the
+text file, or processed, if you are reading an HTML document, for
+example).  The reStructuredText parser is a component of Docutils_.
+
+Simple, implicit markup is used to indicate special constructs, such
+as section headings, bullet lists, and emphasis.  The markup used is
+as minimal and unobtrusive as possible.  Less often-used constructs
+and extensions to the basic reStructuredText syntax may have more
+elaborate or explicit markup.
+
+reStructuredText is applicable to documents of any length, from the
+very small (such as inline program documentation fragments, e.g.
+Python docstrings) to the quite large (this document).
+
+The first section gives a quick overview of the syntax of the
+reStructuredText markup by example.  A complete specification is given
+in the `Syntax Details`_ section.
+
+`Literal blocks`_ (in which no markup processing is done) are used for
+examples throughout this document, to illustrate the plaintext markup.
+
+
+.. contents::
+
+
+-----------------------
+ Quick Syntax Overview
+-----------------------
+
+A reStructuredText document is made up of body or block-level
+elements, and may be structured into sections.  Sections_ are
+indicated through title style (underlines & optional overlines).
+Sections contain body elements and/or subsections.  Some body elements
+contain further elements, such as lists containing list items, which
+in turn may contain paragraphs and other body elements.  Others, such
+as paragraphs, contain text and `inline markup`_ elements.
+
+Here are examples of `body elements`_:
+
+- Paragraphs_ (and `inline markup`_)::
+
+      Paragraphs contain text and may contain inline markup:
+      *emphasis*, **strong emphasis**, `interpreted text`, ``inline
+      literals``, standalone hyperlinks (http://www.python.org),
+      external hyperlinks (Python_), internal cross-references
+      (example_), footnote references ([1]_), citation references
+      ([CIT2002]_), substitution references (|example|), and _`inline
+      internal targets`.
+
+      Paragraphs are separated by blank lines and are left-aligned.
+
+- Five types of lists:
+
+  1. `Bullet lists`_::
+
+         - This is a bullet list.
+
+         - Bullets can be "*", "+", or "-".
+
+  2. `Enumerated lists`_::
+
+         1. This is an enumerated list.
+
+         2. Enumerators may be arabic numbers, letters, or roman
+            numerals.
+
+  3. `Definition lists`_::
+
+         what
+             Definition lists associate a term with a definition.
+
+         how
+             The term is a one-line phrase, and the definition is one
+             or more paragraphs or body elements, indented relative to
+             the term.
+
+  4. `Field lists`_::
+
+         :what: Field lists map field names to field bodies, like
+                database records.  They are often part of an extension
+                syntax.
+
+         :how: The field marker is a colon, the field name, and a
+               colon.
+
+               The field body may contain one or more body elements,
+               indented relative to the field marker.
+
+  5. `Option lists`_, for listing command-line options::
+
+         -a            command-line option "a"
+         -b file       options can have arguments
+                       and long descriptions
+         --long        options can be long also
+         --input=file  long options can also have
+                       arguments
+         /V            DOS/VMS-style options too
+
+     There must be at least two spaces between the option and the
+     description.
+
+- `Literal blocks`_::
+
+      Literal blocks are either indented or line-prefix-quoted blocks,
+      and indicated with a double-colon ("::") at the end of the
+      preceding paragraph (right here -->)::
+
+          if literal_block:
+              text = 'is left as-is'
+              spaces_and_linebreaks = 'are preserved'
+              markup_processing = None
+
+- `Block quotes`_::
+
+      Block quotes consist of indented body elements:
+
+          This theory, that is mine, is mine.
+
+          -- Anne Elk (Miss)
+
+- `Doctest blocks`_::
+
+      >>> print 'Python-specific usage examples; begun with ">>>"'
+      Python-specific usage examples; begun with ">>>"
+      >>> print '(cut and pasted from interactive Python sessions)'
+      (cut and pasted from interactive Python sessions)
+
+- Two syntaxes for tables_:
+
+  1. `Grid tables`_; complete, but complex and verbose::
+
+         +------------------------+------------+----------+
+         | Header row, column 1   | Header 2   | Header 3 |
+         +========================+============+==========+
+         | body row 1, column 1   | column 2   | column 3 |
+         +------------------------+------------+----------+
+         | body row 2             | Cells may span        |
+         +------------------------+-----------------------+
+
+  2. `Simple tables`_; easy and compact, but limited::
+
+         ====================  ==========  ==========
+         Header row, column 1  Header 2    Header 3
+         ====================  ==========  ==========
+         body row 1, column 1  column 2    column 3
+         body row 2            Cells may span columns
+         ====================  ======================
+
+- `Explicit markup blocks`_ all begin with an explicit block marker,
+  two periods and a space:
+
+  - Footnotes_::
+
+        .. [1] A footnote contains body elements, consistently
+           indented by at least 3 spaces.
+
+  - Citations_::
+
+        .. [CIT2002] Just like a footnote, except the label is
+           textual.
+
+  - `Hyperlink targets`_::
+
+        .. _Python: http://www.python.org
+
+        .. _example:
+
+        The "_example" target above points to this paragraph.
+
+  - Directives_::
+
+        .. image:: mylogo.png
+
+  - `Substitution definitions`_::
+
+        .. |symbol here| image:: symbol.png
+
+  - Comments_::
+
+        .. Comments begin with two dots and a space.  Anything may
+           follow, except for the syntax of footnotes/citations,
+           hyperlink targets, directives, or substitution definitions.
+
+
+----------------
+ Syntax Details
+----------------
+
+Descriptions below list "doctree elements" (document tree element
+names; XML DTD generic identifiers) corresponding to syntax
+constructs.  For details on the hierarchy of elements, please see `The
+Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
+type definition.
+
+
+Whitespace
+==========
+
+Spaces are recommended for indentation_, but tabs may also be used.
+Tabs will be converted to spaces.  Tab stops are at every 8th column.
+
+Other whitespace characters (form feeds [chr(12)] and vertical tabs
+[chr(11)]) are converted to single spaces before processing.
+
+
+Blank Lines
+-----------
+
+Blank lines are used to separate paragraphs and other elements.
+Multiple successive blank lines are equivalent to a single blank line,
+except within literal blocks (where all whitespace is preserved).
+Blank lines may be omitted when the markup makes element separation
+unambiguous, in conjunction with indentation.  The first line of a
+document is treated as if it is preceded by a blank line, and the last
+line of a document is treated as if it is followed by a blank line.
+
+
+Indentation
+-----------
+
+Indentation is used to indicate -- and is only significant in
+indicating -- block quotes, definitions (in definition list items),
+and local nested content:
+
+- list item content (multi-line contents of list items, and multiple
+  body elements within a list item, including nested lists),
+- the content of literal blocks, and
+- the content of explicit markup blocks.
+
+Any text whose indentation is less than that of the current level
+(i.e., unindented text or "dedents") ends the current level of
+indentation.
+
+Since all indentation is significant, the level of indentation must be
+consistent.  For example, indentation is the sole markup indicator for
+`block quotes`_::
+
+    This is a top-level paragraph.
+
+        This paragraph belongs to a first-level block quote.
+
+        Paragraph 2 of the first-level block quote.
+
+Multiple levels of indentation within a block quote will result in
+more complex structures::
+
+    This is a top-level paragraph.
+
+        This paragraph belongs to a first-level block quote.
+
+            This paragraph belongs to a second-level block quote.
+
+    Another top-level paragraph.
+
+            This paragraph belongs to a second-level block quote.
+
+        This paragraph belongs to a first-level block quote.  The
+        second-level block quote above is inside this first-level
+        block quote.
+
+When a paragraph or other construct consists of more than one line of
+text, the lines must be left-aligned::
+
+    This is a paragraph.  The lines of
+    this paragraph are aligned at the left.
+
+        This paragraph has problems.  The
+    lines are not left-aligned.  In addition
+      to potential misinterpretation, warning
+        and/or error messages will be generated
+      by the parser.
+
+Several constructs begin with a marker, and the body of the construct
+must be indented relative to the marker.  For constructs using simple
+markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_,
+`hyperlink targets`_, directives_, and comments_), the level of
+indentation of the body is determined by the position of the first
+line of text, which begins on the same line as the marker.  For
+example, bullet list bodies must be indented by at least two columns
+relative to the left edge of the bullet::
+
+    - This is the first line of a bullet list
+      item's paragraph.  All lines must align
+      relative to the first line.  [1]_
+
+          This indented paragraph is interpreted
+          as a block quote.
+
+    Because it is not sufficiently indented,
+    this paragraph does not belong to the list
+    item.
+
+    .. [1] Here's a footnote.  The second line is aligned
+       with the beginning of the footnote label.  The ".."
+       marker is what determines the indentation.
+
+For constructs using complex markers (`field lists`_ and `option
+lists`_), where the marker may contain arbitrary text, the indentation
+of the first line *after* the marker determines the left edge of the
+body.  For example, field lists may have very long markers (containing
+the field names)::
+
+    :Hello: This field has a short field name, so aligning the field
+            body with the first line is feasible.
+
+    :Number-of-African-swallows-required-to-carry-a-coconut: It would
+        be very difficult to align the field body with the left edge
+        of the first line.  It may even be preferable not to begin the
+        body on the same line as the marker.
+
+
+Escaping Mechanism
+==================
+
+The character set universally available to plaintext documents, 7-bit
+ASCII, is limited.  No matter what characters are used for markup,
+they will already have multiple meanings in written text.  Therefore
+markup characters *will* sometimes appear in text **without being
+intended as markup**.  Any serious markup system requires an escaping
+mechanism to override the default meaning of the characters used for
+the markup.  In reStructuredText we use the backslash, commonly used
+as an escaping character in other domains.
+
+A backslash followed by any character (except whitespace characters)
+escapes that character.  The escaped character represents the
+character itself, and is prevented from playing a role in any markup
+interpretation.  The backslash is removed from the output.  A literal
+backslash is represented by two backslashes in a row (the first
+backslash "escapes" the second, preventing it being interpreted in an
+"escaping" role).
+
+Backslash-escaped whitespace characters are removed from the document.
+This allows for character-level `inline markup`_.
+
+There are two contexts in which backslashes have no special meaning:
+literal blocks and inline literals.  In these contexts, a single
+backslash represents a literal backslash, without having to double up.
+
+Please note that the reStructuredText specification and parser do not
+address the issue of the representation or extraction of text input
+(how and in what form the text actually *reaches* the parser).
+Backslashes and other characters may serve a character-escaping
+purpose in certain contexts and must be dealt with appropriately.  For
+example, Python uses backslashes in strings to escape certain
+characters, but not others.  The simplest solution when backslashes
+appear in Python docstrings is to use raw docstrings::
+
+    r"""This is a raw docstring.  Backslashes (\) are not touched."""
+
+
+Reference Names
+===============
+
+Simple reference names are single words consisting of alphanumerics
+plus isolated (no two adjacent) internal hyphens, underscores,
+periods, colons and plus signs; no whitespace or other characters are
+allowed.  Footnote labels (Footnotes_ & `Footnote References`_), citation
+labels (Citations_ & `Citation References`_), `interpreted text`_ roles,
+and some `hyperlink references`_ use the simple reference name syntax.
+
+Reference names using punctuation or whose names are phrases (two or
+more space-separated words) are called "phrase-references".
+Phrase-references are expressed by enclosing the phrase in backquotes
+and treating the backquoted text as a reference name::
+
+    Want to learn about `my favorite programming language`_?
+
+    .. _my favorite programming language: http://www.python.org
+
+Simple reference names may also optionally use backquotes.
+
+Reference names are whitespace-neutral and case-insensitive.  When
+resolving reference names internally:
+
+- whitespace is normalized (one or more spaces, horizontal or vertical
+  tabs, newlines, carriage returns, or form feeds, are interpreted as
+  a single space), and
+
+- case is normalized (all alphabetic characters are converted to
+  lowercase).
+
+For example, the following `hyperlink references`_ are equivalent::
+
+    - `A HYPERLINK`_
+    - `a    hyperlink`_
+    - `A
+      Hyperlink`_
+
+Hyperlinks_, footnotes_, and citations_ all share the same namespace
+for reference names.  The labels of citations (simple reference names)
+and manually-numbered footnotes (numbers) are entered into the same
+database as other hyperlink names.  This means that a footnote
+(defined as "``.. [1]``") which can be referred to by a footnote
+reference (``[1]_``), can also be referred to by a plain hyperlink
+reference (1_).  Of course, each type of reference (hyperlink,
+footnote, citation) may be processed and rendered differently.  Some
+care should be taken to avoid reference name conflicts.
+
+
+Document Structure
+==================
+
+Document
+--------
+
+Doctree element: document.
+
+The top-level element of a parsed reStructuredText document is the
+"document" element.  After initial parsing, the document element is a
+simple container for a document fragment, consisting of `body
+elements`_, transitions_, and sections_, but lacking a document title
+or other bibliographic elements.  The code that calls the parser may
+choose to run one or more optional post-parse transforms_,
+rearranging the document fragment into a complete document with a
+title and possibly other metadata elements (author, date, etc.; see
+`Bibliographic Fields`_).
+
+Specifically, there is no way to indicate a document title and
+subtitle explicitly in reStructuredText.  Instead, a lone top-level
+section title (see Sections_ below) can be treated as the document
+title.  Similarly, a lone second-level section title immediately after
+the "document title" can become the document subtitle.  The rest of
+the sections are then lifted up a level or two.  See the `DocTitle
+transform`_ for details.
+
+
+Sections
+--------
+
+Doctree elements: section, title.
+
+Sections are identified through their titles, which are marked up with
+adornment: "underlines" below the title text, or underlines and
+matching "overlines" above the title.  An underline/overline is a
+single repeated punctuation character that begins in column 1 and
+forms a line extending at least as far as the right edge of the title
+text.  Specifically, an underline/overline character may be any
+non-alphanumeric printable 7-bit ASCII character [#]_.  When an
+overline is used, the length and character used must match the
+underline.  Underline-only adornment styles are distinct from
+overline-and-underline styles that use the same character.  There may
+be any number of levels of section titles, although some output
+formats may have limits (HTML has 6 levels).
+
+.. [#] The following are all valid section title adornment
+   characters::
+
+       ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
+
+   Some characters are more suitable than others.  The following are
+   recommended::
+
+       = - ` : . ' " ~ ^ _ * + #
+
+Rather than imposing a fixed number and order of section title
+adornment styles, the order enforced will be the order as encountered.
+The first style encountered will be an outermost title (like HTML H1),
+the second style will be a subtitle, the third will be a subsubtitle,
+and so on.
+
+Below are examples of section title styles::
+
+    ===============
+     Section Title
+    ===============
+
+    ---------------
+     Section Title
+    ---------------
+
+    Section Title
+    =============
+
+    Section Title
+    -------------
+
+    Section Title
+    `````````````
+
+    Section Title
+    '''''''''''''
+
+    Section Title
+    .............
+
+    Section Title
+    ~~~~~~~~~~~~~
+
+    Section Title
+    *************
+
+    Section Title
+    +++++++++++++
+
+    Section Title
+    ^^^^^^^^^^^^^
+
+When a title has both an underline and an overline, the title text may
+be inset, as in the first two examples above.  This is merely
+aesthetic and not significant.  Underline-only title text may *not* be
+inset.
+
+A blank line after a title is optional.  All text blocks up to the
+next title of the same or higher level are included in a section (or
+subsection, etc.).
+
+All section title styles need not be used, nor need any specific
+section title style be used.  However, a document must be consistent
+in its use of section titles: once a hierarchy of title styles is
+established, sections must use that hierarchy.
+
+Each section title automatically generates a hyperlink target pointing
+to the section.  The text of the hyperlink target (the "reference
+name") is the same as that of the section title.  See `Implicit
+Hyperlink Targets`_ for a complete description.
+
+Sections may contain `body elements`_, transitions_, and nested
+sections.
+
+
+Transitions
+-----------
+
+Doctree element: transition.
+
+    Instead of subheads, extra space or a type ornament between
+    paragraphs may be used to mark text divisions or to signal
+    changes in subject or emphasis.
+
+    (The Chicago Manual of Style, 14th edition, section 1.80)
+
+Transitions are commonly seen in novels and short fiction, as a gap
+spanning one or more lines, with or without a type ornament such as a
+row of asterisks.  Transitions separate other body elements.  A
+transition should not begin or end a section or document, nor should
+two transitions be immediately adjacent.
+
+The syntax for a transition marker is a horizontal line of 4 or more
+repeated punctuation characters.  The syntax is the same as section
+title underlines without title text.  Transition markers require blank
+lines before and after::
+
+    Para.
+
+    ----------
+
+    Para.
+
+Unlike section title underlines, no hierarchy of transition markers is
+enforced, nor do differences in transition markers accomplish
+anything.  It is recommended that a single consistent style be used.
+
+The processing system is free to render transitions in output in any
+way it likes.  For example, horizontal rules (``<hr>``) in HTML output
+would be an obvious choice.
+
+
+Body Elements
+=============
+
+Paragraphs
+----------
+
+Doctree element: paragraph.
+
+Paragraphs consist of blocks of left-aligned text with no markup
+indicating any other body element.  Blank lines separate paragraphs
+from each other and from other body elements.  Paragraphs may contain
+`inline markup`_.
+
+Syntax diagram::
+
+    +------------------------------+
+    | paragraph                    |
+    |                              |
+    +------------------------------+
+
+    +------------------------------+
+    | paragraph                    |
+    |                              |
+    +------------------------------+
+
+
+Bullet Lists
+------------
+
+Doctree elements: bullet_list, list_item.
+
+A text block which begins with a "*", "+", "-", "•", "‣", or "⁃",
+followed by whitespace, is a bullet list item (a.k.a. "unordered" list
+item).  List item bodies must be left-aligned and indented relative to
+the bullet; the text immediately after the bullet determines the
+indentation.  For example::
+
+    - This is the first bullet list item.  The blank line above the
+      first list item is required; blank lines between list items
+      (such as below this paragraph) are optional.
+
+    - This is the first paragraph in the second item in the list.
+
+      This is the second paragraph in the second item in the list.
+      The blank line above this paragraph is required.  The left edge
+      of this paragraph lines up with the paragraph above, both
+      indented relative to the bullet.
+
+      - This is a sublist.  The bullet lines up with the left edge of
+        the text blocks above.  A sublist is a new list so requires a
+        blank line above and below.
+
+    - This is the third item of the main list.
+
+    This paragraph is not part of the list.
+
+Here are examples of **incorrectly** formatted bullet lists::
+
+    - This first line is fine.
+    A blank line is required between list items and paragraphs.
+    (Warning)
+
+    - The following line appears to be a new sublist, but it is not:
+      - This is a paragraph continuation, not a sublist (since there's
+        no blank line).  This line is also incorrectly indented.
+      - Warnings may be issued by the implementation.
+
+Syntax diagram::
+
+    +------+-----------------------+
+    | "- " | list item             |
+    +------| (body elements)+      |
+           +-----------------------+
+
+
+Enumerated Lists
+----------------
+
+Doctree elements: enumerated_list, list_item.
+
+Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists,
+but use enumerators instead of bullets.  An enumerator consists of an
+enumeration sequence member and formatting, followed by whitespace.
+The following enumeration sequences are recognized:
+
+- arabic numerals: 1, 2, 3, ... (no upper limit).
+- uppercase alphabet characters: A, B, C, ..., Z.
+- lower-case alphabet characters: a, b, c, ..., z.
+- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
+- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).
+
+In addition, the auto-enumerator, "#", may be used to automatically
+enumerate a list.  Auto-enumerated lists may begin with explicit
+enumeration, which sets the sequence.  Fully auto-enumerated lists use
+arabic numerals and begin with 1.  (Auto-enumerated lists are new in
+Docutils 0.3.8.)
+
+The following formatting types are recognized:
+
+- suffixed with a period: "1.", "A.", "a.", "I.", "i.".
+- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)".
+- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)".
+
+While parsing an enumerated list, a new list will be started whenever:
+
+- An enumerator is encountered which does not have the same format and
+  sequence type as the current list (e.g. "1.", "(a)" produces two
+  separate lists).
+
+- The enumerators are not in sequence (e.g., "1.", "3." produces two
+  separate lists).
+
+It is recommended that the enumerator of the first list item be
+ordinal-1 ("1", "A", "a", "I", or "i").  Although other start-values
+will be recognized, they may not be supported by the output format.  A
+level-1 [info] system message will be generated for any list beginning
+with a non-ordinal-1 enumerator.
+
+Lists using Roman numerals must begin with "I"/"i" or a
+multi-character value, such as "II" or "XV".  Any other
+single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be
+interpreted as a letter of the alphabet, not as a Roman numeral.
+Likewise, lists using letters of the alphabet may not begin with
+"I"/"i", since these are recognized as Roman numeral 1.
+
+The second line of each enumerated list item is checked for validity.
+This is to prevent ordinary paragraphs from being mistakenly
+interpreted as list items, when they happen to begin with text
+identical to enumerators.  For example, this text is parsed as an
+ordinary paragraph::
+
+    A. Einstein was a really
+    smart dude.
+
+However, ambiguity cannot be avoided if the paragraph consists of only
+one line.  This text is parsed as an enumerated list item::
+
+    A. Einstein was a really smart dude.
+
+If a single-line paragraph begins with text identical to an enumerator
+("A.", "1.", "(b)", "I)", etc.), the first character will have to be
+escaped in order to have the line parsed as an ordinary paragraph::
+
+    \A. Einstein was a really smart dude.
+
+Examples of nested enumerated lists::
+
+    1. Item 1 initial text.
+
+       a) Item 1a.
+       b) Item 1b.
+
+    2. a) Item 2a.
+       b) Item 2b.
+
+Example syntax diagram::
+
+    +-------+----------------------+
+    | "1. " | list item            |
+    +-------| (body elements)+     |
+            +----------------------+
+
+
+Definition Lists
+----------------
+
+Doctree elements: definition_list, definition_list_item, term,
+classifier, definition.
+
+Each definition list item contains a term, optional classifiers, and a
+definition.  A term is a simple one-line word or phrase.  Optional
+classifiers may follow the term on the same line, each after an inline
+" : " (space, colon, space).  A definition is a block indented
+relative to the term, and may contain multiple paragraphs and other
+body elements.  There may be no blank line between a term line and a
+definition block (this distinguishes definition lists from `block
+quotes`_).  Blank lines are required before the first and after the
+last definition list item, but are optional in-between.  For example::
+
+    term 1
+        Definition 1.
+
+    term 2
+        Definition 2, paragraph 1.
+
+        Definition 2, paragraph 2.
+
+    term 3 : classifier
+        Definition 3.
+
+    term 4 : classifier one : classifier two
+        Definition 4.
+
+Inline markup is parsed in the term line before the classifier
+delimiter (" : ") is recognized.  The delimiter will only be
+recognized if it appears outside of any inline markup.
+
+A definition list may be used in various ways, including:
+
+- As a dictionary or glossary.  The term is the word itself, a
+  classifier may be used to indicate the usage of the term (noun,
+  verb, etc.), and the definition follows.
+
+- To describe program variables.  The term is the variable name, a
+  classifier may be used to indicate the type of the variable (string,
+  integer, etc.), and the definition describes the variable's use in
+  the program.  This usage of definition lists supports the classifier
+  syntax of Grouch_, a system for describing and enforcing a Python
+  object schema.
+
+Syntax diagram::
+
+    +----------------------------+
+    | term [ " : " classifier ]* |
+    +--+-------------------------+--+
+       | definition                 |
+       | (body elements)+           |
+       +----------------------------+
+
+
+Field Lists
+-----------
+
+Doctree elements: field_list, field, field_name, field_body.
+
+Field lists are used as part of an extension syntax, such as options
+for directives_, or database-like records meant for further
+processing.  They may also be used for two-column table-like
+structures resembling database records (label & data pairs).
+Applications of reStructuredText may recognize field names and
+transform fields or field bodies in certain contexts.  For examples,
+see `Bibliographic Fields`_ below, or the "image_" and "meta_"
+directives in `reStructuredText Directives`_.
+
+Field lists are mappings from field names to field bodies, modeled on
+RFC822_ headers.  A field name may consist of any characters, but
+colons (":") inside of field names must be escaped with a backslash.
+Inline markup is parsed in field names.  Field names are
+case-insensitive when further processed or transformed.  The field
+name, along with a single colon prefix and suffix, together form the
+field marker.  The field marker is followed by whitespace and the
+field body.  The field body may contain multiple body elements,
+indented relative to the field marker.  The first line after the field
+name marker determines the indentation of the field body.  For
+example::
+
+    :Date: 2001-08-16
+    :Version: 1
+    :Authors: - Me
+              - Myself
+              - I
+    :Indentation: Since the field marker may be quite long, the second
+       and subsequent lines of the field body do not have to line up
+       with the first line, but they must be indented relative to the
+       field name marker, and they must line up with each other.
+    :Parameter i: integer
+
+The interpretation of individual words in a multi-word field name is
+up to the application.  The application may specify a syntax for the
+field name.  For example, second and subsequent words may be treated
+as "arguments", quoted phrases may be treated as a single argument,
+and direct support for the "name=value" syntax may be added.
+
+Standard RFC822_ headers cannot be used for this construct because
+they are ambiguous.  A word followed by a colon at the beginning of a
+line is common in written text.  However, in well-defined contexts
+such as when a field list invariably occurs at the beginning of a
+document (PEPs and email messages), standard RFC822 headers could be
+used.
+
+Syntax diagram (simplified)::
+
+    +--------------------+----------------------+
+    | ":" field name ":" | field body           |
+    +-------+------------+                      |
+            | (body elements)+                  |
+            +-----------------------------------+
+
+
+Bibliographic Fields
+````````````````````
+
+Doctree elements: docinfo, author, authors, organization, contact,
+version, status, date, copyright, field, topic.
+
+When a field list is the first non-comment element in a document
+(after the document title, if there is one), it may have its fields
+transformed to document bibliographic data.  This bibliographic data
+corresponds to the front matter of a book, such as the title page and
+copyright page.
+
+Certain registered field names (listed below) are recognized and
+transformed to the corresponding doctree elements, most becoming child
+elements of the "docinfo" element.  No ordering is required of these
+fields, although they may be rearranged to fit the document structure,
+as noted.  Unless otherwise indicated below, each of the bibliographic
+elements' field bodies may contain a single paragraph only.  Field
+bodies may be checked for `RCS keywords`_ and cleaned up.  Any
+unrecognized fields will remain as generic fields in the docinfo
+element.
+
+The registered bibliographic field names and their corresponding
+doctree elements are as follows:
+
+- Field name "Author": author element.
+- "Authors": authors.
+- "Organization": organization.
+- "Contact": contact.
+- "Address": address.
+- "Version": version.
+- "Status": status.
+- "Date": date.
+- "Copyright": copyright.
+- "Dedication": topic.
+- "Abstract": topic.
+
+The "Authors" field may contain either: a single paragraph consisting
+of a list of authors, separated by ";" or ","; or a bullet list whose
+elements each contain a single paragraph per author.  ";" is checked
+first, so "Doe, Jane; Doe, John" will work.  In some languages
+(e.g. Swedish), there is no singular/plural distinction between
+"Author" and "Authors", so only an "Authors" field is provided, and a
+single name is interpreted as an "Author".  If a single name contains
+a comma, end it with a semicolon to disambiguate: ":Authors: Doe,
+Jane;".
+
+The "Address" field is for a multi-line surface mailing address.
+Newlines and whitespace will be preserved.
+
+The "Dedication" and "Abstract" fields may contain arbitrary body
+elements.  Only one of each is allowed.  They become topic elements
+with "Dedication" or "Abstract" titles (or language equivalents)
+immediately following the docinfo element.
+
+This field-name-to-element mapping can be replaced for other
+languages.  See the `DocInfo transform`_ implementation documentation
+for details.
+
+Unregistered/generic fields may contain one or more paragraphs or
+arbitrary body elements.
+
+
+RCS Keywords
+````````````
+
+`Bibliographic fields`_ recognized by the parser are normally checked
+for RCS [#]_ keywords and cleaned up [#]_.  RCS keywords may be
+entered into source files as "$keyword$", and once stored under RCS or
+CVS [#]_, they are expanded to "$keyword: expansion text $".  For
+example, a "Status" field will be transformed to a "status" element::
+
+    :Status: $keyword: expansion text $
+
+.. [#] Revision Control System.
+.. [#] RCS keyword processing can be turned off (unimplemented).
+.. [#] Concurrent Versions System.  CVS uses the same keywords as RCS.
+
+Processed, the "status" element's text will become simply "expansion
+text".  The dollar sign delimiters and leading RCS keyword name are
+removed.
+
+The RCS keyword processing only kicks in when the field list is in
+bibliographic context (first non-comment construct in the document,
+after a document title if there is one).
+
+
+Option Lists
+------------
+
+Doctree elements: option_list, option_list_item, option_group, option,
+option_string, option_argument, description.
+
+Option lists are two-column lists of command-line options and
+descriptions, documenting a program's options.  For example::
+
+    -a         Output all.
+    -b         Output both (this description is
+               quite long).
+    -c arg     Output just arg.
+    --long     Output all day long.
+
+    -p         This option has two paragraphs in the description.
+               This is the first.
+
+               This is the second.  Blank lines may be omitted between
+               options (as above) or left in (as here and below).
+
+    --very-long-option  A VMS-style option.  Note the adjustment for
+                        the required two spaces.
+
+    --an-even-longer-option
+               The description can also start on the next line.
+
+    -2, --two  This option has two variants.
+
+    -f FILE, --file=FILE  These two options are synonyms; both have
+                          arguments.
+
+    /V         A VMS/DOS-style option.
+
+There are several types of options recognized by reStructuredText:
+
+- Short POSIX options consist of one dash and an option letter.
+- Long POSIX options consist of two dashes and an option word; some
+  systems use a single dash.
+- Old GNU-style "plus" options consist of one plus and an option
+  letter ("plus" options are deprecated now, their use discouraged).
+- DOS/VMS options consist of a slash and an option letter or word.
+
+Please note that both POSIX-style and DOS/VMS-style options may be
+used by DOS or Windows software.  These and other variations are
+sometimes used mixed together.  The names above have been chosen for
+convenience only.
+
+The syntax for short and long POSIX options is based on the syntax
+supported by Python's getopt.py_ module, which implements an option
+parser similar to the `GNU libc getopt_long()`_ function but with some
+restrictions.  There are many variant option systems, and
+reStructuredText option lists do not support all of them.
+
+Although long POSIX and DOS/VMS option words may be allowed to be
+truncated by the operating system or the application when used on the
+command line, reStructuredText option lists do not show or support
+this with any special syntax.  The complete option word should be
+given, supported by notes about truncation if and when applicable.
+
+Options may be followed by an argument placeholder, whose role and
+syntax should be explained in the description text.  Either a space or
+an equals sign may be used as a delimiter between options and option
+argument placeholders; short options ("-" or "+" prefix only) may omit
+the delimiter.  Option arguments may take one of two forms:
+
+- Begins with a letter (``[a-zA-Z]``) and subsequently consists of
+  letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``).
+- Begins with an open-angle-bracket (``<``) and ends with a
+  close-angle-bracket (``>``); any characters except angle brackets
+  are allowed internally.
+
+Multiple option "synonyms" may be listed, sharing a single
+description.  They must be separated by comma-space.
+
+There must be at least two spaces between the option(s) and the
+description.  The description may contain multiple body elements.  The
+first line after the option marker determines the indentation of the
+description.  As with other types of lists, blank lines are required
+before the first option list item and after the last, but are optional
+between option entries.
+
+Syntax diagram (simplified)::
+
+    +----------------------------+-------------+
+    | option [" " argument] "  " | description |
+    +-------+--------------------+             |
+            | (body elements)+                 |
+            +----------------------------------+
+
+
+Literal Blocks
+--------------
+
+Doctree element: literal_block.
+
+A paragraph consisting of two colons ("::") signifies that the
+following text block(s) comprise a literal block.  The literal block
+must either be indented or quoted (see below).  No markup processing
+is done within a literal block.  It is left as-is, and is typically
+rendered in a monospaced typeface::
+
+    This is a typical paragraph.  An indented literal block follows.
+
+    ::
+
+        for a in [5,4,3,2,1]:   # this is program code, shown as-is
+            print a
+        print "it's..."
+        # a literal block continues until the indentation ends
+
+    This text has returned to the indentation of the first paragraph,
+    is outside of the literal block, and is therefore treated as an
+    ordinary paragraph.
+
+The paragraph containing only "::" will be completely removed from the
+output; no empty paragraph will remain.
+
+As a convenience, the "::" is recognized at the end of any paragraph.
+If immediately preceded by whitespace, both colons will be removed
+from the output (this is the "partially minimized" form).  When text
+immediately precedes the "::", *one* colon will be removed from the
+output, leaving only one colon visible (i.e., "::" will be replaced by
+":"; this is the "fully minimized" form).
+
+In other words, these are all equivalent (please pay attention to the
+colons after "Paragraph"):
+
+1. Expanded form::
+
+      Paragraph:
+
+      ::
+
+          Literal block
+
+2. Partially minimized form::
+
+      Paragraph: ::
+
+          Literal block
+
+3. Fully minimized form::
+
+      Paragraph::
+
+          Literal block
+
+All whitespace (including line breaks, but excluding minimum
+indentation for indented literal blocks) is preserved.  Blank lines
+are required before and after a literal block, but these blank lines
+are not included as part of the literal block.
+
+
+Indented Literal Blocks
+```````````````````````
+
+Indented literal blocks are indicated by indentation relative to the
+surrounding text (leading whitespace on each line).  The minimum
+indentation will be removed from each line of an indented literal
+block.  The literal block need not be contiguous; blank lines are
+allowed between sections of indented text.  The literal block ends
+with the end of the indentation.
+
+Syntax diagram::
+
+    +------------------------------+
+    | paragraph                    |
+    | (ends with "::")             |
+    +------------------------------+
+       +---------------------------+
+       | indented literal block    |
+       +---------------------------+
+
+
+Quoted Literal Blocks
+`````````````````````
+
+Quoted literal blocks are unindented contiguous blocks of text where
+each line begins with the same non-alphanumeric printable 7-bit ASCII
+character [#]_.  A blank line ends a quoted literal block.  The
+quoting characters are preserved in the processed document.
+
+.. [#]
+   The following are all valid quoting characters::
+
+       ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
+
+   Note that these are the same characters as are valid for title
+   adornment of sections_.
+
+Possible uses include literate programming in Haskell and email
+quoting::
+
+    John Doe wrote::
+
+    >> Great idea!
+    >
+    > Why didn't I think of that?
+
+    You just did!  ;-)
+
+Syntax diagram::
+
+    +------------------------------+
+    | paragraph                    |
+    | (ends with "::")             |
+    +------------------------------+
+    +------------------------------+
+    | ">" per-line-quoted          |
+    | ">" contiguous literal block |
+    +------------------------------+
+
+
+Line Blocks
+-----------
+
+Doctree elements: line_block, line.  (New in Docutils 0.3.5.)
+
+Line blocks are useful for address blocks, verse (poetry, song
+lyrics), and unadorned lists, where the structure of lines is
+significant.  Line blocks are groups of lines beginning with vertical
+bar ("|") prefixes.  Each vertical bar prefix indicates a new line, so
+line breaks are preserved.  Initial indents are also significant,
+resulting in a nested structure.  Inline markup is supported.
+Continuation lines are wrapped portions of long lines; they begin with
+a space in place of the vertical bar.  The left edge of a continuation
+line must be indented, but need not be aligned with the left edge of
+the text above it.  A line block ends with a blank line.
+
+This example illustrates continuation lines::
+
+    | Lend us a couple of bob till Thursday.
+    | I'm absolutely skint.
+    | But I'm expecting a postal order and I can pay you back
+      as soon as it comes.
+    | Love, Ewan.
+
+This example illustrates the nesting of line blocks, indicated by the
+initial indentation of new lines::
+
+    Take it away, Eric the Orchestra Leader!
+
+        | A one, two, a one two three four
+        |
+        | Half a bee, philosophically,
+        |     must, *ipso facto*, half not be.
+        | But half the bee has got to be,
+        |     *vis a vis* its entity.  D'you see?
+        |
+        | But can a bee be said to be
+        |     or not to be an entire bee,
+        |         when half the bee is not a bee,
+        |             due to some ancient injury?
+        |
+        | Singing...
+
+Syntax diagram::
+
+    +------+-----------------------+
+    | "| " | line                  |
+    +------| continuation line     |
+           +-----------------------+
+
+
+Block Quotes
+------------
+
+Doctree element: block_quote, attribution.
+
+A text block that is indented relative to the preceding text, without
+preceding markup indicating it to be a literal block or other content,
+is a block quote.  All markup processing (for body elements and inline
+markup) continues within the block quote::
+
+    This is an ordinary paragraph, introducing a block quote.
+
+        "It is my business to know things.  That is my trade."
+
+        -- Sherlock Holmes
+
+A block quote may end with an attribution: a text block beginning with
+"--", "---", or a true em-dash, flush left within the block quote.  If
+the attribution consists of multiple lines, the left edges of the
+second and subsequent lines must align.
+
+Multiple block quotes may occur consecutively if terminated with
+attributions.
+
+    Unindented paragraph.
+
+        Block quote 1.
+
+        -- Attribution 1
+
+        Block quote 2.
+
+`Empty comments`_ may be used to explicitly terminate preceding
+constructs that would otherwise consume a block quote::
+
+    * List item.
+
+    ..
+
+        Block quote 3.
+
+Empty comments may also be used to separate block quotes::
+
+        Block quote 4.
+
+    ..
+
+        Block quote 5.
+
+Blank lines are required before and after a block quote, but these
+blank lines are not included as part of the block quote.
+
+Syntax diagram::
+
+    +------------------------------+
+    | (current level of            |
+    | indentation)                 |
+    +------------------------------+
+       +---------------------------+
+       | block quote               |
+       | (body elements)+          |
+       |                           |
+       | -- attribution text       |
+       |    (optional)             |
+       +---------------------------+
+
+
+Doctest Blocks
+--------------
+
+Doctree element: doctest_block.
+
+Doctest blocks are interactive Python sessions cut-and-pasted into
+docstrings.  They are meant to illustrate usage by example, and
+provide an elegant and powerful testing environment via the `doctest
+module`_ in the Python standard library.
+
+Doctest blocks are text blocks which begin with ``">>> "``, the Python
+interactive interpreter main prompt, and end with a blank line.
+Doctest blocks are treated as a special case of literal blocks,
+without requiring the literal block syntax.  If both are present, the
+literal block syntax takes priority over Doctest block syntax::
+
+    This is an ordinary paragraph.
+
+    >>> print 'this is a Doctest block'
+    this is a Doctest block
+
+    The following is a literal block::
+
+        >>> This is not recognized as a doctest block by
+        reStructuredText.  It *will* be recognized by the doctest
+        module, though!
+
+Indentation is not required for doctest blocks.
+
+
+Tables
+------
+
+Doctree elements: table, tgroup, colspec, thead, tbody, row, entry.
+
+ReStructuredText provides two syntaxes for delineating table cells:
+`Grid Tables`_ and `Simple Tables`_.
+
+As with other body elements, blank lines are required before and after
+tables.  Tables' left edges should align with the left edge of
+preceding text blocks; if indented, the table is considered to be part
+of a block quote.
+
+Once isolated, each table cell is treated as a miniature document; the
+top and bottom cell boundaries act as delimiting blank lines.  Each
+cell contains zero or more body elements.  Cell contents may include
+left and/or right margins, which are removed before processing.
+
+
+Grid Tables
+```````````
+
+Grid tables provide a complete table representation via grid-like
+"ASCII art".  Grid tables allow arbitrary cell contents (body
+elements), and both row and column spans.  However, grid tables can be
+cumbersome to produce, especially for simple data sets.  The `Emacs
+table mode`_ is a tool that allows easy editing of grid tables, in
+Emacs.  See `Simple Tables`_ for a simpler (but limited)
+representation.
+
+Grid tables are described with a visual grid made up of the characters
+"-", "=", "|", and "+".  The hyphen ("-") is used for horizontal lines
+(row separators).  The equals sign ("=") may be used to separate
+optional header rows from the table body (not supported by the `Emacs
+table mode`_).  The vertical bar ("|") is used for vertical lines
+(column separators).  The plus sign ("+") is used for intersections of
+horizontal and vertical lines.  Example::
+
+    +------------------------+------------+----------+----------+
+    | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+    | (header rows optional) |            |          |          |
+    +========================+============+==========+==========+
+    | body row 1, column 1   | column 2   | column 3 | column 4 |
+    +------------------------+------------+----------+----------+
+    | body row 2             | Cells may span columns.          |
+    +------------------------+------------+---------------------+
+    | body row 3             | Cells may  | - Table cells       |
+    +------------------------+ span rows. | - contain           |
+    | body row 4             |            | - body elements.    |
+    +------------------------+------------+---------------------+
+
+Some care must be taken with grid tables to avoid undesired
+interactions with cell text in rare cases.  For example, the following
+table contains a cell in row 2 spanning from column 2 to column 4::
+
+    +--------------+----------+-----------+-----------+
+    | row 1, col 1 | column 2 | column 3  | column 4  |
+    +--------------+----------+-----------+-----------+
+    | row 2        |                                  |
+    +--------------+----------+-----------+-----------+
+    | row 3        |          |           |           |
+    +--------------+----------+-----------+-----------+
+
+If a vertical bar is used in the text of that cell, it could have
+unintended effects if accidentally aligned with column boundaries::
+
+    +--------------+----------+-----------+-----------+
+    | row 1, col 1 | column 2 | column 3  | column 4  |
+    +--------------+----------+-----------+-----------+
+    | row 2        | Use the command ``ls | more``.   |
+    +--------------+----------+-----------+-----------+
+    | row 3        |          |           |           |
+    +--------------+----------+-----------+-----------+
+
+Several solutions are possible.  All that is needed is to break the
+continuity of the cell outline rectangle.  One possibility is to shift
+the text by adding an extra space before::
+
+    +--------------+----------+-----------+-----------+
+    | row 1, col 1 | column 2 | column 3  | column 4  |
+    +--------------+----------+-----------+-----------+
+    | row 2        |  Use the command ``ls | more``.  |
+    +--------------+----------+-----------+-----------+
+    | row 3        |          |           |           |
+    +--------------+----------+-----------+-----------+
+
+Another possibility is to add an extra line to row 2::
+
+    +--------------+----------+-----------+-----------+
+    | row 1, col 1 | column 2 | column 3  | column 4  |
+    +--------------+----------+-----------+-----------+
+    | row 2        | Use the command ``ls | more``.   |
+    |              |                                  |
+    +--------------+----------+-----------+-----------+
+    | row 3        |          |           |           |
+    +--------------+----------+-----------+-----------+
+
+
+Simple Tables
+`````````````
+
+Simple tables provide a compact and easy to type but limited
+row-oriented table representation for simple data sets.  Cell contents
+are typically single paragraphs, although arbitrary body elements may
+be represented in most cells.  Simple tables allow multi-line rows (in
+all but the first column) and column spans, but not row spans.  See
+`Grid Tables`_ above for a complete table representation.
+
+Simple tables are described with horizontal borders made up of "=" and
+"-" characters.  The equals sign ("=") is used for top and bottom
+table borders, and to separate optional header rows from the table
+body.  The hyphen ("-") is used to indicate column spans in a single
+row by underlining the joined columns, and may optionally be used to
+explicitly and/or visually separate rows.
+
+A simple table begins with a top border of equals signs with one or
+more spaces at each column boundary (two or more spaces recommended).
+Regardless of spans, the top border *must* fully describe all table
+columns.  There must be at least two columns in the table (to
+differentiate it from section headers).  The top border may be
+followed by header rows, and the last of the optional header rows is
+underlined with '=', again with spaces at column boundaries.  There
+may not be a blank line below the header row separator; it would be
+interpreted as the bottom border of the table.  The bottom boundary of
+the table consists of '=' underlines, also with spaces at column
+boundaries.  For example, here is a truth table, a three-column table
+with one header row and four body rows::
+
+    =====  =====  =======
+      A      B    A and B
+    =====  =====  =======
+    False  False  False
+    True   False  False
+    False  True   False
+    True   True   True
+    =====  =====  =======
+
+Underlines of '-' may be used to indicate column spans by "filling in"
+column margins to join adjacent columns.  Column span underlines must
+be complete (they must cover all columns) and align with established
+column boundaries.  Text lines containing column span underlines may
+not contain any other text.  A column span underline applies only to
+one row immediately above it.  For example, here is a table with a
+column span in the header::
+
+    =====  =====  ======
+       Inputs     Output
+    ------------  ------
+      A      B    A or B
+    =====  =====  ======
+    False  False  False
+    True   False  True
+    False  True   True
+    True   True   True
+    =====  =====  ======
+
+Each line of text must contain spaces at column boundaries, except
+where cells have been joined by column spans.  Each line of text
+starts a new row, except when there is a blank cell in the first
+column.  In that case, that line of text is parsed as a continuation
+line.  For this reason, cells in the first column of new rows (*not*
+continuation lines) *must* contain some text; blank cells would lead
+to a misinterpretation (but see the tip below).  Also, this mechanism
+limits cells in the first column to only one line of text.  Use `grid
+tables`_ if this limitation is unacceptable.
+
+.. Tip::
+
+   To start a new row in a simple table without text in the first
+   column in the processed output, use one of these:
+
+   * an empty comment (".."), which may be omitted from the processed
+     output (see Comments_ below)
+
+   * a backslash escape ("``\``") followed by a space (see `Escaping
+     Mechanism`_ above)
+
+Underlines of '-' may also be used to visually separate rows, even if
+there are no column spans.  This is especially useful in long tables,
+where rows are many lines long.
+
+Blank lines are permitted within simple tables.  Their interpretation
+depends on the context.  Blank lines *between* rows are ignored.
+Blank lines *within* multi-line rows may separate paragraphs or other
+body elements within cells.
+
+The rightmost column is unbounded; text may continue past the edge of
+the table (as indicated by the table borders).  However, it is
+recommended that borders be made long enough to contain the entire
+text.
+
+The following example illustrates continuation lines (row 2 consists
+of two lines of text, and four lines for row 3), a blank line
+separating paragraphs (row 3, column 2), text extending past the right
+edge of the table, and a new row which will have no text in the first
+column in the processed output (row 4)::
+
+    =====  =====
+    col 1  col 2
+    =====  =====
+    1      Second column of row 1.
+    2      Second column of row 2.
+           Second line of paragraph.
+    3      - Second column of row 3.
+
+           - Second item in bullet
+             list (row 3, column 2).
+    \      Row 4; column 1 will be empty.
+    =====  =====
+
+
+Explicit Markup Blocks
+----------------------
+
+An explicit markup block is a text block:
+
+- whose first line begins with ".." followed by whitespace (the
+  "explicit markup start"),
+- whose second and subsequent lines (if any) are indented relative to
+  the first, and
+- which ends before an unindented line.
+
+Explicit markup blocks are analogous to bullet list items, with ".."
+as the bullet.  The text on the lines immediately after the explicit
+markup start determines the indentation of the block body.  The
+maximum common indentation is always removed from the second and
+subsequent lines of the block body.  Therefore if the first construct
+fits in one line, and the indentation of the first and second
+constructs should differ, the first construct should not begin on the
+same line as the explicit markup start.
+
+Blank lines are required between explicit markup blocks and other
+elements, but are optional between explicit markup blocks where
+unambiguous.
+
+The explicit markup syntax is used for footnotes, citations, hyperlink
+targets, directives, substitution definitions, and comments.
+
+
+Footnotes
+`````````
+
+Doctree elements: footnote, label.
+
+Each footnote consists of an explicit markup start (".. "), a left
+square bracket, the footnote label, a right square bracket, and
+whitespace, followed by indented body elements.  A footnote label can
+be:
+
+- a whole decimal number consisting of one or more digits,
+
+- a single "#" (denoting `auto-numbered footnotes`_),
+
+- a "#" followed by a simple reference name (an `autonumber label`_),
+  or
+
+- a single "*" (denoting `auto-symbol footnotes`_).
+
+The footnote content (body elements) must be consistently indented (by
+at least 3 spaces) and left-aligned.  The first body element within a
+footnote may often begin on the same line as the footnote label.
+However, if the first element fits on one line and the indentation of
+the remaining elements differ, the first element must begin on the
+line after the footnote label.  Otherwise, the difference in
+indentation will not be detected.
+
+Footnotes may occur anywhere in the document, not only at the end.
+Where and how they appear in the processed output depends on the
+processing system.
+
+Here is a manually numbered footnote::
+
+    .. [1] Body elements go here.
+
+Each footnote automatically generates a hyperlink target pointing to
+itself.  The text of the hyperlink target name is the same as that of
+the footnote label.  `Auto-numbered footnotes`_ generate a number as
+their footnote label and reference name.  See `Implicit Hyperlink
+Targets`_ for a complete description of the mechanism.
+
+Syntax diagram::
+
+    +-------+-------------------------+
+    | ".. " | "[" label "]" footnote  |
+    +-------+                         |
+            | (body elements)+        |
+            +-------------------------+
+
+
+Auto-Numbered Footnotes
+.......................
+
+A number sign ("#") may be used as the first character of a footnote
+label to request automatic numbering of the footnote or footnote
+reference.
+
+The first footnote to request automatic numbering is assigned the
+label "1", the second is assigned the label "2", and so on (assuming
+there are no manually numbered footnotes present; see `Mixed Manual
+and Auto-Numbered Footnotes`_ below).  A footnote which has
+automatically received a label "1" generates an implicit hyperlink
+target with name "1", just as if the label was explicitly specified.
+
+.. _autonumber label: `autonumber labels`_
+
+A footnote may specify a label explicitly while at the same time
+requesting automatic numbering: ``[#label]``.  These labels are called
+_`autonumber labels`.  Autonumber labels do two things:
+
+- On the footnote itself, they generate a hyperlink target whose name
+  is the autonumber label (doesn't include the "#").
+
+- They allow an automatically numbered footnote to be referred to more
+  than once, as a footnote reference or hyperlink reference.  For
+  example::
+
+      If [#note]_ is the first footnote reference, it will show up as
+      "[1]".  We can refer to it again as [#note]_ and again see
+      "[1]".  We can also refer to it as note_ (an ordinary internal
+      hyperlink reference).
+
+      .. [#note] This is the footnote labeled "note".
+
+The numbering is determined by the order of the footnotes, not by the
+order of the references.  For footnote references without autonumber
+labels (``[#]_``), the footnotes and footnote references must be in
+the same relative order but need not alternate in lock-step.  For
+example::
+
+    [#]_ is a reference to footnote 1, and [#]_ is a reference to
+    footnote 2.
+
+    .. [#] This is footnote 1.
+    .. [#] This is footnote 2.
+    .. [#] This is footnote 3.
+
+    [#]_ is a reference to footnote 3.
+
+Special care must be taken if footnotes themselves contain
+auto-numbered footnote references, or if multiple references are made
+in close proximity.  Footnotes and references are noted in the order
+they are encountered in the document, which is not necessarily the
+same as the order in which a person would read them.
+
+
+Auto-Symbol Footnotes
+.....................
+
+An asterisk ("*") may be used for footnote labels to request automatic
+symbol generation for footnotes and footnote references.  The asterisk
+may be the only character in the label.  For example::
+
+    Here is a symbolic footnote reference: [*]_.
+
+    .. [*] This is the footnote.
+
+A transform will insert symbols as labels into corresponding footnotes
+and footnote references.  The number of references must be equal to
+the number of footnotes.  One symbol footnote cannot have multiple
+references.
+
+The standard Docutils system uses the following symbols for footnote
+marks [#]_:
+
+- asterisk/star ("*")
+- dagger (HTML character entity "&dagger;", Unicode U+02020)
+- double dagger ("&Dagger;"/U+02021)
+- section mark ("&sect;"/U+000A7)
+- pilcrow or paragraph mark ("&para;"/U+000B6)
+- number sign ("#")
+- spade suit ("&spades;"/U+02660)
+- heart suit ("&hearts;"/U+02665)
+- diamond suit ("&diams;"/U+02666)
+- club suit ("&clubs;"/U+02663)
+
+.. [#] This list was inspired by the list of symbols for "Note
+   Reference Marks" in The Chicago Manual of Style, 14th edition,
+   section 12.51.  "Parallels" ("||") were given in CMoS instead of
+   the pilcrow.  The last four symbols (the card suits) were added
+   arbitrarily.
+
+If more than ten symbols are required, the same sequence will be
+reused, doubled and then tripled, and so on ("**" etc.).
+
+.. Note:: When using auto-symbol footnotes, the choice of output
+   encoding is important.  Many of the symbols used are not encodable
+   in certain common text encodings such as Latin-1 (ISO 8859-1).  The
+   use of UTF-8 for the output encoding is recommended.  An
+   alternative for HTML and XML output is to use the
+   "xmlcharrefreplace" `output encoding error handler`__.
+
+__ ../../user/config.html#output-encoding-error-handler
+
+
+Mixed Manual and Auto-Numbered Footnotes
+........................................
+
+Manual and automatic footnote numbering may both be used within a
+single document, although the results may not be expected.  Manual
+numbering takes priority.  Only unused footnote numbers are assigned
+to auto-numbered footnotes.  The following example should be
+illustrative::
+
+    [2]_ will be "2" (manually numbered),
+    [#]_ will be "3" (anonymous auto-numbered), and
+    [#label]_ will be "1" (labeled auto-numbered).
+
+    .. [2] This footnote is labeled manually, so its number is fixed.
+
+    .. [#label] This autonumber-labeled footnote will be labeled "1".
+       It is the first auto-numbered footnote and no other footnote
+       with label "1" exists.  The order of the footnotes is used to
+       determine numbering, not the order of the footnote references.
+
+    .. [#] This footnote will be labeled "3".  It is the second
+       auto-numbered footnote, but footnote label "2" is already used.
+
+
+Citations
+`````````
+
+Citations are identical to footnotes except that they use only
+non-numeric labels such as ``[note]`` or ``[GVR2001]``.  Citation
+labels are simple `reference names`_ (case-insensitive single words
+consisting of alphanumerics plus internal hyphens, underscores, and
+periods; no whitespace).  Citations may be rendered separately and
+differently from footnotes.  For example::
+
+    Here is a citation reference: [CIT2002]_.
+
+    .. [CIT2002] This is the citation.  It's just like a footnote,
+       except the label is textual.
+
+
+.. _hyperlinks:
+
+Hyperlink Targets
+`````````````````
+
+Doctree element: target.
+
+These are also called _`explicit hyperlink targets`, to differentiate
+them from `implicit hyperlink targets`_ defined below.
+
+Hyperlink targets identify a location within or outside of a document,
+which may be linked to by `hyperlink references`_.
+
+Hyperlink targets may be named or anonymous.  Named hyperlink targets
+consist of an explicit markup start (".. "), an underscore, the
+reference name (no trailing underscore), a colon, whitespace, and a
+link block::
+
+    .. _hyperlink-name: link-block
+
+Reference names are whitespace-neutral and case-insensitive.  See
+`Reference Names`_ for details and examples.
+
+Anonymous hyperlink targets consist of an explicit markup start
+(".. "), two underscores, a colon, whitespace, and a link block; there
+is no reference name::
+
+    .. __: anonymous-hyperlink-target-link-block
+
+An alternate syntax for anonymous hyperlinks consists of two
+underscores, a space, and a link block::
+
+    __ anonymous-hyperlink-target-link-block
+
+See `Anonymous Hyperlinks`_ below.
+
+There are three types of hyperlink targets: internal, external, and
+indirect.
+
+1. _`Internal hyperlink targets` have empty link blocks.  They provide
+   an end point allowing a hyperlink to connect one place to another
+   within a document.  An internal hyperlink target points to the
+   element following the target.  For example::
+
+       Clicking on this internal hyperlink will take us to the target_
+       below.
+
+       .. _target:
+
+       The hyperlink target above points to this paragraph.
+
+   Internal hyperlink targets may be "chained".  Multiple adjacent
+   internal hyperlink targets all point to the same element::
+
+       .. _target1:
+       .. _target2:
+
+       The targets "target1" and "target2" are synonyms; they both
+       point to this paragraph.
+
+   If the element "pointed to" is an external hyperlink target (with a
+   URI in its link block; see #2 below) the URI from the external
+   hyperlink target is propagated to the internal hyperlink targets;
+   they will all "point to" the same URI.  There is no need to
+   duplicate a URI.  For example, all three of the following hyperlink
+   targets refer to the same URI::
+
+       .. _Python DOC-SIG mailing list archive:
+       .. _archive:
+       .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/
+
+   An inline form of internal hyperlink target is available; see
+   `Inline Internal Targets`_.
+
+2. _`External hyperlink targets` have an absolute or relative URI or
+   email address in their link blocks.  For example, take the
+   following input::
+
+       See the Python_ home page for info.
+
+       `Write to me`_ with your questions.
+
+       .. _Python: http://www.python.org
+       .. _Write to me: [e-mail]
+
+   After processing into HTML, the hyperlinks might be expressed as::
+
+       See the <a href="http://www.python.org">Python</a> home page
+       for info.
+
+       <a href="mailto:[e-mail]">Write to me</a> with your
+       questions.
+
+   An external hyperlink's URI may begin on the same line as the
+   explicit markup start and target name, or it may begin in an
+   indented text block immediately following, with no intervening
+   blank lines.  If there are multiple lines in the link block, they
+   are concatenated.  Any whitespace is removed (whitespace is
+   permitted to allow for line wrapping).  The following external
+   hyperlink targets are equivalent::
+
+       .. _one-liner: http://docutils.sourceforge.net/rst.html
+
+       .. _starts-on-this-line: http://
+          docutils.sourceforge.net/rst.html
+
+       .. _entirely-below:
+          http://docutils.
+          sourceforge.net/rst.html
+
+   If an external hyperlink target's URI contains an underscore as its
+   last character, it must be escaped to avoid being mistaken for an
+   indirect hyperlink target::
+
+       This link_ refers to a file called ``underscore_``.
+
+       .. _link: underscore\_
+
+   It is possible (although not generally recommended) to include URIs
+   directly within hyperlink references.  See `Embedded URIs`_ below.
+
+3. _`Indirect hyperlink targets` have a hyperlink reference in their
+   link blocks.  In the following example, target "one" indirectly
+   references whatever target "two" references, and target "two"
+   references target "three", an internal hyperlink target.  In
+   effect, all three reference the same thing::
+
+       .. _one: two_
+       .. _two: three_
+       .. _three:
+
+   Just as with `hyperlink references`_ anywhere else in a document,
+   if a phrase-reference is used in the link block it must be enclosed
+   in backquotes.  As with `external hyperlink targets`_, the link
+   block of an indirect hyperlink target may begin on the same line as
+   the explicit markup start or the next line.  It may also be split
+   over multiple lines, in which case the lines are joined with
+   whitespace before being normalized.
+
+   For example, the following indirect hyperlink targets are
+   equivalent::
+
+       .. _one-liner: `A HYPERLINK`_
+       .. _entirely-below:
+          `a    hyperlink`_
+       .. _split: `A
+          Hyperlink`_
+
+If the reference name contains any colons, either:
+
+- the phrase must be enclosed in backquotes::
+
+      .. _`FAQTS: Computers: Programming: Languages: Python`:
+         http://python.faqts.com/
+
+- or the colon(s) must be backslash-escaped in the link target::
+
+      .. _Chapter One\: "Tadpole Days":
+
+      It's not easy being green...
+
+See `Implicit Hyperlink Targets`_ below for the resolution of
+duplicate reference names.
+
+Syntax diagram::
+
+    +-------+----------------------+
+    | ".. " | "_" name ":" link    |
+    +-------+ block                |
+            |                      |
+            +----------------------+
+
+
+Anonymous Hyperlinks
+....................
+
+The `World Wide Web Consortium`_ recommends in its `HTML Techniques
+for Web Content Accessibility Guidelines`_ that authors should
+"clearly identify the target of each link."  Hyperlink references
+should be as verbose as possible, but duplicating a verbose hyperlink
+name in the target is onerous and error-prone.  Anonymous hyperlinks
+are designed to allow convenient verbose hyperlink references, and are
+analogous to `Auto-Numbered Footnotes`_.  They are particularly useful
+in short or one-off documents.  However, this feature is easily abused
+and can result in unreadable plaintext and/or unmaintainable
+documents.  Caution is advised.
+
+Anonymous `hyperlink references`_ are specified with two underscores
+instead of one::
+
+    See `the web site of my favorite programming language`__.
+
+Anonymous targets begin with ".. __:"; no reference name is required
+or allowed::
+
+    .. __: http://www.python.org
+
+As a convenient alternative, anonymous targets may begin with "__"
+only::
+
+    __ http://www.python.org
+
+The reference name of the reference is not used to match the reference
+to its target.  Instead, the order of anonymous hyperlink references
+and targets within the document is significant: the first anonymous
+reference will link to the first anonymous target.  The number of
+anonymous hyperlink references in a document must match the number of
+anonymous targets.  For readability, it is recommended that targets be
+kept close to references.  Take care when editing text containing
+anonymous references; adding, removing, and rearranging references
+require attention to the order of corresponding targets.
+
+
+Directives
+``````````
+
+Doctree elements: depend on the directive.
+
+Directives are an extension mechanism for reStructuredText, a way of
+adding support for new constructs without adding new primary syntax
+(directives may support additional syntax locally).  All standard
+directives (those implemented and registered in the reference
+reStructuredText parser) are described in the `reStructuredText
+Directives`_ document, and are always available.  Any other directives
+are domain-specific, and may require special action to make them
+available when processing the document.
+
+For example, here's how an image_ may be placed::
+
+    .. image:: mylogo.jpeg
+
+A figure_ (a graphic with a caption) may placed like this::
+
+    .. figure:: larch.png
+
+       The larch.
+
+An admonition_ (note, caution, etc.) contains other body elements::
+
+    .. note:: This is a paragraph
+
+       - Here is a bullet list.
+
+Directives are indicated by an explicit markup start (".. ") followed
+by the directive type, two colons, and whitespace (together called the
+"directive marker").  Directive types are case-insensitive single
+words (alphanumerics plus isolated internal hyphens, underscores,
+plus signs, colons, and periods; no whitespace).  Two colons are used
+after the directive type for these reasons:
+
+- Two colons are distinctive, and unlikely to be used in common text.
+
+- Two colons avoids clashes with common comment text like::
+
+      .. Danger: modify at your own risk!
+
+- If an implementation of reStructuredText does not recognize a
+  directive (i.e., the directive-handler is not installed), a level-3
+  (error) system message is generated, and the entire directive block
+  (including the directive itself) will be included as a literal
+  block.  Thus "::" is a natural choice.
+
+The directive block is consists of any text on the first line of the
+directive after the directive marker, and any subsequent indented
+text.  The interpretation of the directive block is up to the
+directive code.  There are three logical parts to the directive block:
+
+1. Directive arguments.
+2. Directive options.
+3. Directive content.
+
+Individual directives can employ any combination of these parts.
+Directive arguments can be filesystem paths, URLs, title text, etc.
+Directive options are indicated using `field lists`_; the field names
+and contents are directive-specific.  Arguments and options must form
+a contiguous block beginning on the first or second line of the
+directive; a blank line indicates the beginning of the directive
+content block.  If either arguments and/or options are employed by the
+directive, a blank line must separate them from the directive content.
+The "figure" directive employs all three parts::
+
+    .. figure:: larch.png
+       :scale: 50
+
+       The larch.
+
+Simple directives may not require any content.  If a directive that
+does not employ a content block is followed by indented text anyway,
+it is an error.  If a block quote should immediately follow a
+directive, use an empty comment in-between (see Comments_ below).
+
+Actions taken in response to directives and the interpretation of text
+in the directive content block or subsequent text block(s) are
+directive-dependent.  See `reStructuredText Directives`_ for details.
+
+Directives are meant for the arbitrary processing of their contents,
+which can be transformed into something possibly unrelated to the
+original text.  It may also be possible for directives to be used as
+pragmas, to modify the behavior of the parser, such as to experiment
+with alternate syntax.  There is no parser support for this
+functionality at present; if a reasonable need for pragma directives
+is found, they may be supported.
+
+Directives do not generate "directive" elements; they are a *parser
+construct* only, and have no intrinsic meaning outside of
+reStructuredText.  Instead, the parser will transform recognized
+directives into (possibly specialized) document elements.  Unknown
+directives will trigger level-3 (error) system messages.
+
+Syntax diagram::
+
+    +-------+-------------------------------+
+    | ".. " | directive type "::" directive |
+    +-------+ block                         |
+            |                               |
+            +-------------------------------+
+
+
+Substitution Definitions
+````````````````````````
+
+Doctree element: substitution_definition.
+
+Substitution definitions are indicated by an explicit markup start
+(".. ") followed by a vertical bar, the substitution text, another
+vertical bar, whitespace, and the definition block.  Substitution text
+may not begin or end with whitespace.  A substitution definition block
+contains an embedded inline-compatible directive (without the leading
+".. "), such as "image_" or "replace_".  For example::
+
+    The |biohazard| symbol must be used on containers used to
+    dispose of medical waste.
+
+    .. |biohazard| image:: biohazard.png
+
+It is an error for a substitution definition block to directly or
+indirectly contain a circular substitution reference.
+
+`Substitution references`_ are replaced in-line by the processed
+contents of the corresponding definition (linked by matching
+substitution text).  Matches are case-sensitive but forgiving; if no
+exact match is found, a case-insensitive comparison is attempted.
+
+Substitution definitions allow the power and flexibility of
+block-level directives_ to be shared by inline text.  They are a way
+to include arbitrarily complex inline structures within text, while
+keeping the details out of the flow of text.  They are the equivalent
+of SGML/XML's named entities or programming language macros.
+
+Without the substitution mechanism, every time someone wants an
+application-specific new inline structure, they would have to petition
+for a syntax change.  In combination with existing directive syntax,
+any inline structure can be coded without new syntax (except possibly
+a new directive).
+
+Syntax diagram::
+
+    +-------+-----------------------------------------------------+
+    | ".. " | "|" substitution text "| " directive type "::" data |
+    +-------+ directive block                                     |
+            |                                                     |
+            +-----------------------------------------------------+
+
+Following are some use cases for the substitution mechanism.  Please
+note that most of the embedded directives shown are examples only and
+have not been implemented.
+
+Objects
+    Substitution references may be used to associate ambiguous text
+    with a unique object identifier.
+
+    For example, many sites may wish to implement an inline "user"
+    directive::
+
+        |Michael| and |Jon| are our widget-wranglers.
+
+        .. |Michael| user:: mjones
+        .. |Jon|     user:: jhl
+
+    Depending on the needs of the site, this may be used to index the
+    document for later searching, to hyperlink the inline text in
+    various ways (mailto, homepage, mouseover Javascript with profile
+    and contact information, etc.), or to customize presentation of
+    the text (include username in the inline text, include an icon
+    image with a link next to the text, make the text bold or a
+    different color, etc.).
+
+    The same approach can be used in documents which frequently refer
+    to a particular type of objects with unique identifiers but
+    ambiguous common names.  Movies, albums, books, photos, court
+    cases, and laws are possible.  For example::
+
+        |The Transparent Society| offers a fascinating alternate view
+        on privacy issues.
+
+        .. |The Transparent Society| book:: isbn=0738201448
+
+    Classes or functions, in contexts where the module or class names
+    are unclear and/or interpreted text cannot be used, are another
+    possibility::
+
+        4XSLT has the convenience method |runString|, so you don't
+        have to mess with DOM objects if all you want is the
+        transformed output.
+
+        .. |runString| function:: module=xml.xslt class=Processor
+
+Images
+    Images are a common use for substitution references::
+
+        West led the |H| 3, covered by dummy's |H| Q, East's |H| K,
+        and trumped in hand with the |S| 2.
+
+        .. |H| image:: /images/heart.png
+           :height: 11
+           :width: 11
+        .. |S| image:: /images/spade.png
+           :height: 11
+           :width: 11
+
+        * |Red light| means stop.
+        * |Green light| means go.
+        * |Yellow light| means go really fast.
+
+        .. |Red light|    image:: red_light.png
+        .. |Green light|  image:: green_light.png
+        .. |Yellow light| image:: yellow_light.png
+
+        |-><-| is the official symbol of POEE_.
+
+        .. |-><-| image:: discord.png
+        .. _POEE: http://www.poee.org/
+
+    The "image_" directive has been implemented.
+
+Styles [#]_
+    Substitution references may be used to associate inline text with
+    an externally defined presentation style::
+
+        Even |the text in Texas| is big.
+
+        .. |the text in Texas| style:: big
+
+    The style name may be meaningful in the context of some particular
+    output format (CSS class name for HTML output, LaTeX style name
+    for LaTeX, etc), or may be ignored for other output formats (such
+    as plaintext).
+
+    .. @@@ This needs to be rethought & rewritten or removed:
+
+       Interpreted text is unsuitable for this purpose because the set
+       of style names cannot be predefined - it is the domain of the
+       content author, not the author of the parser and output
+       formatter - and there is no way to associate a style name
+       argument with an interpreted text style role.  Also, it may be
+       desirable to use the same mechanism for styling blocks::
+
+           .. style:: motto
+              At Bob's Underwear Shop, we'll do anything to get in
+              your pants.
+
+           .. style:: disclaimer
+              All rights reversed.  Reprint what you like.
+
+    .. [#] There may be sufficient need for a "style" mechanism to
+       warrant simpler syntax such as an extension to the interpreted
+       text role syntax.  The substitution mechanism is cumbersome for
+       simple text styling.
+
+Templates
+    Inline markup may be used for later processing by a template
+    engine.  For example, a Zope_ author might write::
+
+        Welcome back, |name|!
+
+        .. |name| tal:: replace user/getUserName
+
+    After processing, this ZPT output would result::
+
+        Welcome back,
+        <span tal:replace="user/getUserName">name</span>!
+
+    Zope would then transform this to something like "Welcome back,
+    David!" during a session with an actual user.
+
+Replacement text
+    The substitution mechanism may be used for simple macro
+    substitution.  This may be appropriate when the replacement text
+    is repeated many times throughout one or more documents,
+    especially if it may need to change later.  A short example is
+    unavoidably contrived::
+
+        |RST|_ is a little annoying to type over and over, especially
+        when writing about |RST| itself, and spelling out the
+        bicapitalized word |RST| every time isn't really necessary for
+        |RST| source readability.
+
+        .. |RST| replace:: reStructuredText
+        .. _RST: http://docutils.sourceforge.net/rst.html
+
+    Note the trailing underscore in the first use of a substitution
+    reference.  This indicates a reference to the corresponding
+    hyperlink target.
+
+    Substitution is also appropriate when the replacement text cannot
+    be represented using other inline constructs, or is obtrusively
+    long::
+
+        But still, that's nothing compared to a name like
+        |j2ee-cas|__.
+
+        .. |j2ee-cas| replace::
+           the Java `TM`:super: 2 Platform, Enterprise Edition Client
+           Access Services
+        __ http://developer.java.sun.com/developer/earlyAccess/
+           j2eecas/
+
+    The "replace_" directive has been implemented.
+
+
+Comments
+````````
+
+Doctree element: comment.
+
+Arbitrary indented text may follow the explicit markup start and will
+be processed as a comment element.  No further processing is done on
+the comment block text; a comment contains a single "text blob".
+Depending on the output formatter, comments may be removed from the
+processed output.  The only restriction on comments is that they not
+use the same syntax as any of the other explicit markup constructs:
+substitution definitions, directives, footnotes, citations, or
+hyperlink targets.  To ensure that none of the other explicit markup
+constructs is recognized, leave the ".." on a line by itself::
+
+    .. This is a comment
+    ..
+       _so: is this!
+    ..
+       [and] this!
+    ..
+       this:: too!
+    ..
+       |even| this:: !
+
+.. _empty comments:
+
+An explicit markup start followed by a blank line and nothing else
+(apart from whitespace) is an "_`empty comment`".  It serves to
+terminate a preceding construct, and does **not** consume any indented
+text following.  To have a block quote follow a list or any indented
+construct, insert an unindented empty comment in-between.
+
+Syntax diagram::
+
+    +-------+----------------------+
+    | ".. " | comment              |
+    +-------+ block                |
+            |                      |
+            +----------------------+
+
+
+Implicit Hyperlink Targets
+==========================
+
+Implicit hyperlink targets are generated by section titles, footnotes,
+and citations, and may also be generated by extension constructs.
+Implicit hyperlink targets otherwise behave identically to explicit
+`hyperlink targets`_.
+
+Problems of ambiguity due to conflicting duplicate implicit and
+explicit reference names are avoided by following this procedure:
+
+1. `Explicit hyperlink targets`_ override any implicit targets having
+   the same reference name.  The implicit hyperlink targets are
+   removed, and level-1 (info) system messages are inserted.
+
+2. Duplicate implicit hyperlink targets are removed, and level-1
+   (info) system messages inserted.  For example, if two or more
+   sections have the same title (such as "Introduction" subsections of
+   a rigidly-structured document), there will be duplicate implicit
+   hyperlink targets.
+
+3. Duplicate explicit hyperlink targets are removed, and level-2
+   (warning) system messages are inserted.  Exception: duplicate
+   `external hyperlink targets`_ (identical hyperlink names and
+   referenced URIs) do not conflict, and are not removed.
+
+System messages are inserted where target links have been removed.
+See "Error Handling" in `PEP 258`_.
+
+The parser must return a set of *unique* hyperlink targets.  The
+calling software (such as the Docutils_) can warn of unresolvable
+links, giving reasons for the messages.
+
+
+Inline Markup
+=============
+
+In reStructuredText, inline markup applies to words or phrases within
+a text block.  The same whitespace and punctuation that serves to
+delimit words in written text is used to delimit the inline markup
+syntax constructs.  The text within inline markup may not begin or end
+with whitespace.  Arbitrary `character-level inline markup`_ is
+supported although not encouraged.  Inline markup cannot be nested.
+
+There are nine inline markup constructs.  Five of the constructs use
+identical start-strings and end-strings to indicate the markup:
+
+- emphasis_: "*"
+- `strong emphasis`_: "**"
+- `interpreted text`_: "`"
+- `inline literals`_: "``"
+- `substitution references`_: "|"
+
+Three constructs use different start-strings and end-strings:
+
+- `inline internal targets`_: "_`" and "`"
+- `footnote references`_: "[" and "]_"
+- `hyperlink references`_: "`" and "\`_" (phrases), or just a
+  trailing "_" (single words)
+
+`Standalone hyperlinks`_ are recognized implicitly, and use no extra
+markup.
+
+Inline markup recognition rules
+-------------------------------
+
+Inline markup start-strings and end-strings are only recognized if all of
+the following conditions are met:
+
+1. Inline markup start-strings must start a text block or be
+   immediately preceded by
+
+   * whitespace,
+   * one of the ASCII characters ``- : / ' " < ( [ {`` or
+   * a non-ASCII punctuation character with `Unicode category`_
+     `Pd` (Dash),
+     `Po` (Other),
+     `Ps` (Open),
+     `Pi` (Initial quote), or
+     `Pf` (Final quote) [#PiPf]_.
+
+2. Inline markup start-strings must be immediately followed by
+   non-whitespace.
+
+3. Inline markup end-strings must be immediately preceded by
+   non-whitespace.
+
+4. Inline markup end-strings must end a text block or be immediately
+   followed by
+
+   * whitespace,
+   * one of the ASCII characters ``- . , : ; ! ? \ / ' " ) ] } >`` or
+   * a non-ASCII punctuation character with `Unicode category`_
+     `Pd` (Dash),
+     `Po` (Other),
+     `Pe` (Close),
+     `Pf` (Final quote), or
+     `Pi` (Initial quote) [#PiPf]_.
+
+5. If an inline markup start-string is immediately preceded by one of the
+   ASCII characters ``' " < ( [ {``, or a character with Unicode character
+   category `Ps`, `Pi`, or `Pf`, it must not be followed by the
+   corresponding [#corresponding-quotes]_ closing character from
+   ``' " ) ] } >`` or the categories `Pe`, `Pf`, or `Pi`.
+
+6. An inline markup end-string must be separated by at least one
+   character from the start-string.
+
+7. An unescaped backslash preceding a start-string or end-string will
+   disable markup recognition, except for the end-string of `inline
+   literals`_.  See `Escaping Mechanism`_ above for details.
+
+.. [#PiPf] `Pi` (Punctuation, Initial quote) characters are "usually
+   closing, sometimes opening". `Pf` (Punctuation, Final quote)
+   characters are "usually closing, sometimes opening".
+
+.. [#corresponding-quotes] For quotes, corresponding characters can be
+   any of the `quotation marks in international usage`_
+
+.. _Unicode category:
+   http://www.unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values
+
+.. _quotation marks in international usage:
+   http://en.wikipedia.org/wiki/Quotation_mark,_non-English_usage
+
+The inline markup recognition rules were devised to allow 90% of non-markup
+uses of "*", "`", "_", and "|" without escaping. For example, none of the
+following terms are recognized as containing inline markup strings:
+
+- 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* (breaks 1)
+- 2 * x  a ** b  (* BOM32_* ` `` _ __ | (breaks 2)
+- "*" '|' (*) [*] {*} <*>
+  ‘*’ ‚*‘ ‘*‚ ’*’ ‚*’
+  “*” „*“ “*„ ”*” „*”
+  »*« ›*‹ «*» »*» ›*› (breaks 5)
+- || (breaks 6)
+- __init__ __init__()
+
+No escaping is required inside the following inline markup examples:
+
+- *2 * x  *a **b *.txt* (breaks 3)
+- *2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)* (breaks 4)
+
+It may be desirable to use `inline literals`_ for some of these anyhow,
+especially if they represent code snippets.  It's a judgment call.
+
+These cases *do* require either literal-quoting or escaping to avoid
+misinterpretation:
+
+    \*4, class\_, \*args, \**kwargs, \`TeX-quoted', \*ML, \*.txt
+
+In most use cases, `inline literals`_ or `literal blocks`_ are the best
+choice (by default, this also selects a monospaced font)::
+
+    *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt
+
+Recognition order
+-----------------
+
+Inline markup delimiter characters are used for multiple constructs,
+so to avoid ambiguity there must be a specific recognition order for
+each character.  The inline markup recognition order is as follows:
+
+- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_
+  ("*").
+
+- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_
+  (leading "_`", trailing "`"), are mutually independent, and are
+  recognized before phrase `hyperlink references`_ (leading "`",
+  trailing "\`_") and `interpreted text`_ ("`").
+
+- Trailing underscores: Footnote references ("[" + label + "]_") and
+  simple `hyperlink references`_ (name + trailing "_") are mutually
+  independent.
+
+- Vertical bars: `Substitution references`_ ("|") are independently
+  recognized.
+
+- `Standalone hyperlinks`_ are the last to be recognized.
+
+
+Character-Level Inline Markup
+-----------------------------
+
+It is possible to mark up individual characters within a word with
+backslash escapes (see `Escaping Mechanism`_ above).  Backslash
+escapes can be used to allow arbitrary text to immediately follow
+inline markup::
+
+    Python ``list``\s use square bracket syntax.
+
+The backslash will disappear from the processed document.  The word
+"list" will appear as inline literal text, and the letter "s" will
+immediately follow it as normal text, with no space in-between.
+
+Arbitrary text may immediately precede inline markup using
+backslash-escaped whitespace::
+
+    Possible in *re*\ ``Structured``\ *Text*, though not encouraged.
+
+The backslashes and spaces separating "re", "Structured", and "Text"
+above will disappear from the processed document.
+
+.. CAUTION::
+
+   The use of backslash-escapes for character-level inline markup is
+   not encouraged.  Such use is ugly and detrimental to the
+   unprocessed document's readability.  Please use this feature
+   sparingly and only where absolutely necessary.
+
+
+Emphasis
+--------
+
+Doctree element: emphasis.
+
+Start-string = end-string = "*".
+
+Text enclosed by single asterisk characters is emphasized::
+
+    This is *emphasized text*.
+
+Emphasized text is typically displayed in italics.
+
+
+Strong Emphasis
+---------------
+
+Doctree element: strong.
+
+Start-string = end-string = "**".
+
+Text enclosed by double-asterisks is emphasized strongly::
+
+    This is **strong text**.
+
+Strongly emphasized text is typically displayed in boldface.
+
+
+Interpreted Text
+----------------
+
+Doctree element: depends on the explicit or implicit role and
+processing.
+
+Start-string = end-string = "`".
+
+Interpreted text is text that is meant to be related, indexed, linked,
+summarized, or otherwise processed, but the text itself is typically
+left alone.  Interpreted text is enclosed by single backquote
+characters::
+
+    This is `interpreted text`.
+
+The "role" of the interpreted text determines how the text is
+interpreted.  The role may be inferred implicitly (as above; the
+"default role" is used) or indicated explicitly, using a role marker.
+A role marker consists of a colon, the role name, and another colon.
+A role name is a single word consisting of alphanumerics plus isolated
+internal hyphens, underscores, plus signs, colons, and periods;
+no whitespace or other characters are allowed.  A role marker is
+either a prefix or a suffix to the interpreted text, whichever reads
+better; it's up to the author::
+
+    :role:`interpreted text`
+
+    `interpreted text`:role:
+
+Interpreted text allows extensions to the available inline descriptive
+markup constructs.  To emphasis_, `strong emphasis`_, `inline
+literals`_, and `hyperlink references`_, we can add "title reference",
+"index entry", "acronym", "class", "red", "blinking" or anything else
+we want.  Only pre-determined roles are recognized; unknown roles will
+generate errors.  A core set of standard roles is implemented in the
+reference parser; see `reStructuredText Interpreted Text Roles`_ for
+individual descriptions.  The role_ directive can be used to define
+custom interpreted text roles.  In addition, applications may support
+specialized roles.
+
+
+Inline Literals
+---------------
+
+Doctree element: literal.
+
+Start-string = end-string = "``".
+
+Text enclosed by double-backquotes is treated as inline literals::
+
+    This text is an example of ``inline literals``.
+
+Inline literals may contain any characters except two adjacent
+backquotes in an end-string context (according to the recognition
+rules above).  No markup interpretation (including backslash-escape
+interpretation) is done within inline literals.
+
+Line breaks are *not* preserved in inline literals.  Although a
+reStructuredText parser will preserve runs of spaces in its output,
+the final representation of the processed document is dependent on the
+output formatter, thus the preservation of whitespace cannot be
+guaranteed.  If the preservation of line breaks and/or other
+whitespace is important, `literal blocks`_ should be used.
+
+Inline literals are useful for short code snippets.  For example::
+
+    The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches
+    floating-point numbers (without exponents).
+
+
+Hyperlink References
+--------------------
+
+Doctree element: reference.
+
+- Named hyperlink references:
+
+  - Start-string = "" (empty string), end-string = "_".
+  - Start-string = "`", end-string = "\`_".  (Phrase references.)
+
+- Anonymous hyperlink references:
+
+  - Start-string = "" (empty string), end-string = "__".
+  - Start-string = "`", end-string = "\`__".  (Phrase references.)
+
+Hyperlink references are indicated by a trailing underscore, "_",
+except for `standalone hyperlinks`_ which are recognized
+independently.  The underscore can be thought of as a right-pointing
+arrow.  The trailing underscores point away from hyperlink references,
+and the leading underscores point toward `hyperlink targets`_.
+
+Hyperlinks consist of two parts.  In the text body, there is a source
+link, a reference name with a trailing underscore (or two underscores
+for `anonymous hyperlinks`_)::
+
+    See the Python_ home page for info.
+
+A target link with a matching reference name must exist somewhere else
+in the document.  See `Hyperlink Targets`_ for a full description).
+
+`Anonymous hyperlinks`_ (which see) do not use reference names to
+match references to targets, but otherwise behave similarly to named
+hyperlinks.
+
+
+Embedded URIs
+`````````````
+
+A hyperlink reference may directly embed a target URI inline, within
+angle brackets ("<...>") as follows::
+
+    See the `Python home page <http://www.python.org>`_ for info.
+
+This is exactly equivalent to::
+
+    See the `Python home page`_ for info.
+
+    .. _Python home page: http://www.python.org
+
+The bracketed URI must be preceded by whitespace and be the last text
+before the end string.  With a single trailing underscore, the
+reference is named and the same target URI may be referred to again.
+
+With two trailing underscores, the reference and target are both
+anonymous, and the target cannot be referred to again.  These are
+"one-off" hyperlinks.  For example::
+
+    `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
+    2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
+    define the syntax of URIs.
+
+Equivalent to::
+
+    `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs.
+
+    __ http://www.rfc-editor.org/rfc/rfc2396.txt
+    __ http://www.rfc-editor.org/rfc/rfc2732.txt
+
+If reference text happens to end with angle-bracketed text that is
+*not* a URI, the open-angle-bracket needs to be backslash-escaped.
+For example, here is a reference to a title describing a tag::
+
+    See `HTML Element: \<a>`_ below.
+
+The reference text may also be omitted, in which case the URI will be
+duplicated for use as the reference text.  This is useful for relative
+URIs where the address or file name is also the desired reference
+text::
+
+    See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__
+    for details.
+
+.. CAUTION::
+
+   This construct offers easy authoring and maintenance of hyperlinks
+   at the expense of general readability.  Inline URIs, especially
+   long ones, inevitably interrupt the natural flow of text.  For
+   documents meant to be read in source form, the use of independent
+   block-level `hyperlink targets`_ is **strongly recommended**.  The
+   embedded URI construct is most suited to documents intended *only*
+   to be read in processed form.
+
+
+Inline Internal Targets
+------------------------
+
+Doctree element: target.
+
+Start-string = "_`", end-string = "`".
+
+Inline internal targets are the equivalent of explicit `internal
+hyperlink targets`_, but may appear within running text.  The syntax
+begins with an underscore and a backquote, is followed by a hyperlink
+name or phrase, and ends with a backquote.  Inline internal targets
+may not be anonymous.
+
+For example, the following paragraph contains a hyperlink target named
+"Norwegian Blue"::
+
+    Oh yes, the _`Norwegian Blue`.  What's, um, what's wrong with it?
+
+See `Implicit Hyperlink Targets`_ for the resolution of duplicate
+reference names.
+
+
+Footnote References
+-------------------
+
+Doctree element: footnote_reference.
+
+Start-string = "[", end-string = "]_".
+
+Each footnote reference consists of a square-bracketed label followed
+by a trailing underscore.  Footnote labels are one of:
+
+- one or more digits (i.e., a number),
+
+- a single "#" (denoting `auto-numbered footnotes`_),
+
+- a "#" followed by a simple reference name (an `autonumber label`_),
+  or
+
+- a single "*" (denoting `auto-symbol footnotes`_).
+
+For example::
+
+    Please RTFM [1]_.
+
+    .. [1] Read The Fine Manual
+
+
+Citation References
+-------------------
+
+Doctree element: citation_reference.
+
+Start-string = "[", end-string = "]_".
+
+Each citation reference consists of a square-bracketed label followed
+by a trailing underscore.  Citation labels are simple `reference
+names`_ (case-insensitive single words, consisting of alphanumerics
+plus internal hyphens, underscores, and periods; no whitespace).
+
+For example::
+
+    Here is a citation reference: [CIT2002]_.
+
+See Citations_ for the citation itself.
+
+
+Substitution References
+-----------------------
+
+Doctree element: substitution_reference, reference.
+
+Start-string = "|", end-string = "|" (optionally followed by "_" or
+"__").
+
+Vertical bars are used to bracket the substitution reference text.  A
+substitution reference may also be a hyperlink reference by appending
+a "_" (named) or "__" (anonymous) suffix; the substitution text is
+used for the reference text in the named case.
+
+The processing system replaces substitution references with the
+processed contents of the corresponding `substitution definitions`_
+(which see for the definition of "correspond").  Substitution
+definitions produce inline-compatible elements.
+
+Examples::
+
+    This is a simple |substitution reference|.  It will be replaced by
+    the processing system.
+
+    This is a combination |substitution and hyperlink reference|_.  In
+    addition to being replaced, the replacement text or element will
+    refer to the "substitution and hyperlink reference" target.
+
+
+Standalone Hyperlinks
+---------------------
+
+Doctree element: reference.
+
+Start-string = end-string = "" (empty string).
+
+A URI (absolute URI [#URI]_ or standalone email address) within a text
+block is treated as a general external hyperlink with the URI itself
+as the link's text.  For example::
+
+    See http://www.python.org for info.
+
+would be marked up in HTML as::
+
+    See <a href="http://www.python.org">http://www.python.org</a> for
+    info.
+
+Two forms of URI are recognized:
+
+1. Absolute URIs.  These consist of a scheme, a colon (":"), and a
+   scheme-specific part whose interpretation depends on the scheme.
+
+   The scheme is the name of the protocol, such as "http", "ftp",
+   "mailto", or "telnet".  The scheme consists of an initial letter,
+   followed by letters, numbers, and/or "+", "-", ".".  Recognition is
+   limited to known schemes, per the `Official IANA Registry of URI
+   Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_.
+
+   The scheme-specific part of the resource identifier may be either
+   hierarchical or opaque:
+
+   - Hierarchical identifiers begin with one or two slashes and may
+     use slashes to separate hierarchical components of the path.
+     Examples are web pages and FTP sites::
+
+         http://www.python.org
+
+         ftp://ftp.python.org/pub/python
+
+   - Opaque identifiers do not begin with slashes.  Examples are
+     email addresses and newsgroups::
+
+         mailto:[e-mail]
+
+         news:comp.lang.python
+
+   With queries, fragments, and %-escape sequences, URIs can become
+   quite complicated.  A reStructuredText parser must be able to
+   recognize any absolute URI, as defined in RFC2396_ and RFC2732_.
+
+2. Standalone email addresses, which are treated as if they were
+   absolute URIs with a "mailto:" scheme.  Example::
+
+       [e-mail]
+
+Punctuation at the end of a URI is not considered part of the URI,
+unless the URI is terminated by a closing angle bracket (">").
+Backslashes may be used in URIs to escape markup characters,
+specifically asterisks ("*") and underscores ("_") which are vaid URI
+characters (see `Escaping Mechanism`_ above).
+
+.. [#URI] Uniform Resource Identifier.  URIs are a general form of
+   URLs (Uniform Resource Locators).  For the syntax of URIs see
+   RFC2396_ and RFC2732_.
+
+
+Units
+=====
+
+(New in Docutils 0.3.10.)
+
+All measures consist of a positive floating point number in standard
+(non-scientific) notation and a unit, possibly separated by one or
+more spaces.
+
+Units are only supported where explicitly mentioned in the reference
+manuals.
+
+
+Length Units
+------------
+
+The following length units are supported by the reStructuredText
+parser:
+
+* em (ems, the height of the element's font)
+* ex (x-height, the height of the letter "x")
+* px (pixels, relative to the canvas resolution)
+* in (inches; 1in=2.54cm)
+* cm (centimeters; 1cm=10mm)
+* mm (millimeters)
+* pt (points; 1pt=1/72in)
+* pc (picas; 1pc=12pt)
+
+This set corresponds to the `length units in CSS`_.
+
+(List and explanations taken from
+http://www.htmlhelp.com/reference/css/units.html#length.)
+
+The following are all valid length values: "1.5em", "20 mm", ".5in".
+
+Length values without unit are completed with a writer-dependent
+default (e.g. px with `html4css1`, pt with `latex2e`). See the writer
+specific documentation in the `user doc`__ for details.
+
+.. _length units in CSS:
+   http://www.w3.org/TR/CSS2/syndata.html#length-units
+
+__ ../../user/
+
+Percentage Units
+----------------
+
+Percentage values have a percent sign ("%") as unit.  Percentage
+values are relative to other values, depending on the context in which
+they occur.
+
+
+----------------
+ Error Handling
+----------------
+
+Doctree element: system_message, problematic.
+
+Markup errors are handled according to the specification in `PEP
+258`_.
+
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _The Docutils Document Tree: ../doctree.html
+.. _Docutils Generic DTD: ../docutils.dtd
+.. _transforms:
+   http://docutils.sourceforge.net/docutils/transforms/
+.. _Grouch: http://www.mems-exchange.org/software/grouch/
+.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt
+.. _DocTitle transform:
+.. _DocInfo transform:
+   http://docutils.sourceforge.net/docutils/transforms/frontmatter.py
+.. _getopt.py:
+   http://www.python.org/doc/current/lib/module-getopt.html
+.. _GNU libc getopt_long():
+   http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html
+.. _doctest module:
+   http://www.python.org/doc/current/lib/module-doctest.html
+.. _Emacs table mode: http://table.sourceforge.net/
+.. _Official IANA Registry of URI Schemes:
+   http://www.iana.org/assignments/uri-schemes
+.. _Retired Index of WWW Addressing Schemes:
+   http://www.w3.org/Addressing/schemes.html
+.. _World Wide Web Consortium: http://www.w3.org/
+.. _HTML Techniques for Web Content Accessibility Guidelines:
+   http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text
+.. _image: directives.html#image
+.. _replace: directives.html#replace
+.. _meta: directives.html#meta
+.. _figure: directives.html#figure
+.. _admonition: directives.html#admonitions
+.. _role: directives.html#custom-interpreted-text-roles
+.. _reStructuredText Directives: directives.html
+.. _reStructuredText Interpreted Text Roles: roles.html
+.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt
+.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt
+.. _Zope: http://www.zope.com/
+.. _PEP 258: ../../peps/pep-0258.html
+
+

+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

=== added directory '.pc/support-aliases-in-references.diff/docutils'
=== added directory '.pc/support-aliases-in-references.diff/docutils/parsers'
=== added directory '.pc/support-aliases-in-references.diff/docutils/parsers/rst'
=== added file '.pc/support-aliases-in-references.diff/docutils/parsers/rst/states.py'
--- .pc/support-aliases-in-references.diff/docutils/parsers/rst/states.py	1970-01-01 00:00:00 +0000
+++ .pc/support-aliases-in-references.diff/docutils/parsers/rst/states.py	2013-03-19 07:30:29 +0000
@@ -0,0 +1,3052 @@
+# $Id: states.py 7495 2012-08-16 14:50:57Z milde $
+# Author: David Goodger <[e-mail]>
+# Copyright: This module has been placed in the public domain.
+
+"""
+This is the ``docutils.parsers.rst.states`` module, the core of
+the reStructuredText parser.  It defines the following:
+
+:Classes:
+    - `RSTStateMachine`: reStructuredText parser's entry point.
+    - `NestedStateMachine`: recursive StateMachine.
+    - `RSTState`: reStructuredText State superclass.
+    - `Inliner`: For parsing inline markup.
+    - `Body`: Generic classifier of the first line of a block.
+    - `SpecializedBody`: Superclass for compound element members.
+    - `BulletList`: Second and subsequent bullet_list list_items
+    - `DefinitionList`: Second+ definition_list_items.
+    - `EnumeratedList`: Second+ enumerated_list list_items.
+    - `FieldList`: Second+ fields.
+    - `OptionList`: Second+ option_list_items.
+    - `RFC2822List`: Second+ RFC2822-style fields.
+    - `ExtensionOptions`: Parses directive option fields.
+    - `Explicit`: Second+ explicit markup constructs.
+    - `SubstitutionDef`: For embedded directives in substitution definitions.
+    - `Text`: Classifier of second line of a text block.
+    - `SpecializedText`: Superclass for continuation lines of Text-variants.
+    - `Definition`: Second line of potential definition_list_item.
+    - `Line`: Second line of overlined section title or transition marker.
+    - `Struct`: An auxiliary collection class.
+
+:Exception classes:
+    - `MarkupError`
+    - `ParserError`
+    - `MarkupMismatch`
+
+:Functions:
+    - `escape2null()`: Return a string, escape-backslashes converted to nulls.
+    - `unescape()`: Return a string, nulls removed or restored to backslashes.
+
+:Attributes:
+    - `state_classes`: set of State classes used with `RSTStateMachine`.
+
+Parser Overview
+===============
+
+The reStructuredText parser is implemented as a recursive state machine,
+examining its input one line at a time.  To understand how the parser works,
+please first become familiar with the `docutils.statemachine` module.  In the
+description below, references are made to classes defined in this module;
+please see the individual classes for details.
+
+Parsing proceeds as follows:
+
+1. The state machine examines each line of input, checking each of the
+   transition patterns of the state `Body`, in order, looking for a match.
+   The implicit transitions (blank lines and indentation) are checked before
+   any others.  The 'text' transition is a catch-all (matches anything).
+
+2. The method associated with the matched transition pattern is called.
+
+   A. Some transition methods are self-contained, appending elements to the
+      document tree (`Body.doctest` parses a doctest block).  The parser's
+      current line index is advanced to the end of the element, and parsing
+      continues with step 1.
+
+   B. Other transition methods trigger the creation of a nested state machine,
+      whose job is to parse a compound construct ('indent' does a block quote,
+      'bullet' does a bullet list, 'overline' does a section [first checking
+      for a valid section header], etc.).
+
+      - In the case of lists and explicit markup, a one-off state machine is
+        created and run to parse contents of the first item.
+
+      - A new state machine is created and its initial state is set to the
+        appropriate specialized state (`BulletList` in the case of the
+        'bullet' transition; see `SpecializedBody` for more detail).  This
+        state machine is run to parse the compound element (or series of
+        explicit markup elements), and returns as soon as a non-member element
+        is encountered.  For example, the `BulletList` state machine ends as
+        soon as it encounters an element which is not a list item of that
+        bullet list.  The optional omission of inter-element blank lines is
+        enabled by this nested state machine.
+
+      - The current line index is advanced to the end of the elements parsed,
+        and parsing continues with step 1.
+
+   C. The result of the 'text' transition depends on the next line of text.
+      The current state is changed to `Text`, under which the second line is
+      examined.  If the second line is:
+
+      - Indented: The element is a definition list item, and parsing proceeds
+        similarly to step 2.B, using the `DefinitionList` state.
+
+      - A line of uniform punctuation characters: The element is a section
+        header; again, parsing proceeds as in step 2.B, and `Body` is still
+        used.
+
+      - Anything else: The element is a paragraph, which is examined for
+        inline markup and appended to the parent element.  Processing
+        continues with step 1.
+"""
+
+__docformat__ = 'reStructuredText'
+
+
+import sys
+import re
+try:
+    import roman
+except ImportError:
+    import docutils.utils.roman as roman
+from types import FunctionType, MethodType
+
+from docutils import nodes, statemachine, utils
+from docutils import ApplicationError, DataError
+from docutils.statemachine import StateMachineWS, StateWS
+from docutils.nodes import fully_normalize_name as normalize_name
+from docutils.nodes import whitespace_normalize_name
+import docutils.parsers.rst
+from docutils.parsers.rst import directives, languages, tableparser, roles
+from docutils.parsers.rst.languages import en as _fallback_language_module
+from docutils.utils import escape2null, unescape, column_width
+from docutils.utils import punctuation_chars, urischemes
+
+class MarkupError(DataError): pass
+class UnknownInterpretedRoleError(DataError): pass
+class InterpretedRoleNotImplementedError(DataError): pass
+class ParserError(ApplicationError): pass
+class MarkupMismatch(Exception): pass
+
+
+class Struct:
+
+    """Stores data attributes for dotted-attribute access."""
+
+    def __init__(self, **keywordargs):
+        self.__dict__.update(keywordargs)
+
+
+class RSTStateMachine(StateMachineWS):
+
+    """
+    reStructuredText's master StateMachine.
+
+    The entry point to reStructuredText parsing is the `run()` method.
+    """
+
+    def run(self, input_lines, document, input_offset=0, match_titles=True,
+            inliner=None):
+        """
+        Parse `input_lines` and modify the `document` node in place.
+
+        Extend `StateMachineWS.run()`: set up parse-global data and
+        run the StateMachine.
+        """
+        self.language = languages.get_language(
+            document.settings.language_code)
+        self.match_titles = match_titles
+        if inliner is None:
+            inliner = Inliner()
+        inliner.init_customizations(document.settings)
+        self.memo = Struct(document=document,
+                           reporter=document.reporter,
+                           language=self.language,
+                           title_styles=[],
+                           section_level=0,
+                           section_bubble_up_kludge=False,
+                           inliner=inliner)
+        self.document = document
+        self.attach_observer(document.note_source)
+        self.reporter = self.memo.reporter
+        self.node = document
+        results = StateMachineWS.run(self, input_lines, input_offset,
+                                     input_source=document['source'])
+        assert results == [], 'RSTStateMachine.run() results should be empty!'
+        self.node = self.memo = None    # remove unneeded references
+
+
+class NestedStateMachine(StateMachineWS):
+
+    """
+    StateMachine run from within other StateMachine runs, to parse nested
+    document structures.
+    """
+
+    def run(self, input_lines, input_offset, memo, node, match_titles=True):
+        """
+        Parse `input_lines` and populate a `docutils.nodes.document` instance.
+
+        Extend `StateMachineWS.run()`: set up document-wide data.
+        """
+        self.match_titles = match_titles
+        self.memo = memo
+        self.document = memo.document
+        self.attach_observer(self.document.note_source)
+        self.reporter = memo.reporter
+        self.language = memo.language
+        self.node = node
+        results = StateMachineWS.run(self, input_lines, input_offset)
+        assert results == [], ('NestedStateMachine.run() results should be '
+                               'empty!')
+        return results
+
+
+class RSTState(StateWS):
+
+    """
+    reStructuredText State superclass.
+
+    Contains methods used by all State subclasses.
+    """
+
+    nested_sm = NestedStateMachine
+    nested_sm_cache = []
+
+    def __init__(self, state_machine, debug=False):
+        self.nested_sm_kwargs = {'state_classes': state_classes,
+                                 'initial_state': 'Body'}
+        StateWS.__init__(self, state_machine, debug)
+
+    def runtime_init(self):
+        StateWS.runtime_init(self)
+        memo = self.state_machine.memo
+        self.memo = memo
+        self.reporter = memo.reporter
+        self.inliner = memo.inliner
+        self.document = memo.document
+        self.parent = self.state_machine.node
+        # enable the reporter to determine source and source-line
+        if not hasattr(self.reporter, 'get_source_and_line'):
+            self.reporter.get_source_and_line = self.state_machine.get_source_and_line
+            # print "adding get_source_and_line to reporter", self.state_machine.input_offset
+
+
+    def goto_line(self, abs_line_offset):
+        """
+        Jump to input line `abs_line_offset`, ignoring jumps past the end.
+        """
+        try:
+            self.state_machine.goto_line(abs_line_offset)
+        except EOFError:
+            pass
+
+    def no_match(self, context, transitions):
+        """
+        Override `StateWS.no_match` to generate a system message.
+
+        This code should never be run.
+        """
+        self.reporter.severe(
+            'Internal error: no transition pattern match.  State: "%s"; '
+            'transitions: %s; context: %s; current line: %r.'
+            % (self.__class__.__name__, transitions, context,
+               self.state_machine.line))
+        return context, None, []
+
+    def bof(self, context):
+        """Called at beginning of file."""
+        return [], []
+
+    def nested_parse(self, block, input_offset, node, match_titles=False,
+                     state_machine_class=None, state_machine_kwargs=None):
+        """
+        Create a new StateMachine rooted at `node` and run it over the input
+        `block`.
+        """
+        use_default = 0
+        if state_machine_class is None:
+            state_machine_class = self.nested_sm
+            use_default += 1
+        if state_machine_kwargs is None:
+            state_machine_kwargs = self.nested_sm_kwargs
+            use_default += 1
+        block_length = len(block)
+
+        state_machine = None
+        if use_default == 2:
+            try:
+                state_machine = self.nested_sm_cache.pop()
+            except IndexError:
+                pass
+        if not state_machine:
+            state_machine = state_machine_class(debug=self.debug,
+                                                **state_machine_kwargs)
+        state_machine.run(block, input_offset, memo=self.memo,
+                          node=node, match_titles=match_titles)
+        if use_default == 2:
+            self.nested_sm_cache.append(state_machine)
+        else:
+            state_machine.unlink()
+        new_offset = state_machine.abs_line_offset()
+        # No `block.parent` implies disconnected -- lines aren't in sync:
+        if block.parent and (len(block) - block_length) != 0:
+            # Adjustment for block if modified in nested parse:
+            self.state_machine.next_line(len(block) - block_length)
+        return new_offset
+
+    def nested_list_parse(self, block, input_offset, node, initial_state,
+                          blank_finish,
+                          blank_finish_state=None,
+                          extra_settings={},
+                          match_titles=False,
+                          state_machine_class=None,
+                          state_machine_kwargs=None):
+        """
+        Create a new StateMachine rooted at `node` and run it over the input
+        `block`. Also keep track of optional intermediate blank lines and the
+        required final one.
+        """
+        if state_machine_class is None:
+            state_machine_class = self.nested_sm
+        if state_machine_kwargs is None:
+            state_machine_kwargs = self.nested_sm_kwargs.copy()
+        state_machine_kwargs['initial_state'] = initial_state
+        state_machine = state_machine_class(debug=self.debug,
+                                            **state_machine_kwargs)
+        if blank_finish_state is None:
+            blank_finish_state = initial_state
+        state_machine.states[blank_finish_state].blank_finish = blank_finish
+        for key, value in extra_settings.items():
+            setattr(state_machine.states[initial_state], key, value)
+        state_machine.run(block, input_offset, memo=self.memo,
+                          node=node, match_titles=match_titles)
+        blank_finish = state_machine.states[blank_finish_state].blank_finish
+        state_machine.unlink()
+        return state_machine.abs_line_offset(), blank_finish
+
+    def section(self, title, source, style, lineno, messages):
+        """Check for a valid subsection and create one if it checks out."""
+        if self.check_subsection(source, style, lineno):
+            self.new_subsection(title, lineno, messages)
+
+    def check_subsection(self, source, style, lineno):
+        """
+        Check for a valid subsection header.  Return 1 (true) or None (false).
+
+        When a new section is reached that isn't a subsection of the current
+        section, back up the line count (use ``previous_line(-x)``), then
+        ``raise EOFError``.  The current StateMachine will finish, then the
+        calling StateMachine can re-examine the title.  This will work its way
+        back up the calling chain until the correct section level isreached.
+
+        @@@ Alternative: Evaluate the title, store the title info & level, and
+        back up the chain until that level is reached.  Store in memo? Or
+        return in results?
+
+        :Exception: `EOFError` when a sibling or supersection encountered.
+        """
+        memo = self.memo
+        title_styles = memo.title_styles
+        mylevel = memo.section_level
+        try:                            # check for existing title style
+            level = title_styles.index(style) + 1
+        except ValueError:              # new title style
+            if len(title_styles) == memo.section_level: # new subsection
+                title_styles.append(style)
+                return 1
+            else:                       # not at lowest level
+                self.parent += self.title_inconsistent(source, lineno)
+                return None
+        if level <= mylevel:            # sibling or supersection
+            memo.section_level = level   # bubble up to parent section
+            if len(style) == 2:
+                memo.section_bubble_up_kludge = True
+            # back up 2 lines for underline title, 3 for overline title
+            self.state_machine.previous_line(len(style) + 1)
+            raise EOFError              # let parent section re-evaluate
+        if level == mylevel + 1:        # immediate subsection
+            return 1
+        else:                           # invalid subsection
+            self.parent += self.title_inconsistent(source, lineno)
+            return None
+
+    def title_inconsistent(self, sourcetext, lineno):
+        error = self.reporter.severe(
+            'Title level inconsistent:', nodes.literal_block('', sourcetext),
+            line=lineno)
+        return error
+
+    def new_subsection(self, title, lineno, messages):
+        """Append new subsection to document tree. On return, check level."""
+        memo = self.memo
+        mylevel = memo.section_level
+        memo.section_level += 1
+        section_node = nodes.section()
+        self.parent += section_node
+        textnodes, title_messages = self.inline_text(title, lineno)
+        titlenode = nodes.title(title, '', *textnodes)
+        name = normalize_name(titlenode.astext())
+        section_node['names'].append(name)
+        section_node += titlenode
+        section_node += messages
+        section_node += title_messages
+        self.document.note_implicit_target(section_node, section_node)
+        offset = self.state_machine.line_offset + 1
+        absoffset = self.state_machine.abs_line_offset() + 1
+        newabsoffset = self.nested_parse(
+              self.state_machine.input_lines[offset:], input_offset=absoffset,
+              node=section_node, match_titles=True)
+        self.goto_line(newabsoffset)
+        if memo.section_level <= mylevel: # can't handle next section?
+            raise EOFError              # bubble up to supersection
+        # reset section_level; next pass will detect it properly
+        memo.section_level = mylevel
+
+    def paragraph(self, lines, lineno):
+        """
+        Return a list (paragraph & messages) & a boolean: literal_block next?
+        """
+        data = '\n'.join(lines).rstrip()
+        if re.search(r'(?<!\\)(\\\\)*::$', data):
+            if len(data) == 2:
+                return [], 1
+            elif data[-3] in ' \n':
+                text = data[:-3].rstrip()
+            else:
+                text = data[:-1]
+            literalnext = 1
+        else:
+            text = data
+            literalnext = 0
+        textnodes, messages = self.inline_text(text, lineno)
+        p = nodes.paragraph(data, '', *textnodes)
+        p.source, p.line = self.state_machine.get_source_and_line(lineno)
+        return [p] + messages, literalnext
+
+    def inline_text(self, text, lineno):
+        """
+        Return 2 lists: nodes (text and inline elements), and system_messages.
+        """
+        return self.inliner.parse(text, lineno, self.memo, self.parent)
+
+    def unindent_warning(self, node_name):
+        # the actual problem is one line below the current line
+        lineno = self.state_machine.abs_line_number()+1
+        return self.reporter.warning('%s ends without a blank line; '
+                                     'unexpected unindent.' % node_name,
+                                     line=lineno)
+
+
+def build_regexp(definition, compile=True):
+    """
+    Build, compile and return a regular expression based on `definition`.
+
+    :Parameter: `definition`: a 4-tuple (group name, prefix, suffix, parts),
+        where "parts" is a list of regular expressions and/or regular
+        expression definitions to be joined into an or-group.
+    """
+    name, prefix, suffix, parts = definition
+    part_strings = []
+    for part in parts:
+        if type(part) is tuple:
+            part_strings.append(build_regexp(part, None))
+        else:
+            part_strings.append(part)
+    or_group = '|'.join(part_strings)
+    regexp = '%(prefix)s(?P<%(name)s>%(or_group)s)%(suffix)s' % locals()
+    if compile:
+        return re.compile(regexp, re.UNICODE)
+    else:
+        return regexp
+
+
+class Inliner:
+
+    """
+    Parse inline markup; call the `parse()` method.
+    """
+
+    def __init__(self):
+        self.implicit_dispatch = [(self.patterns.uri, self.standalone_uri),]
+        """List of (pattern, bound method) tuples, used by
+        `self.implicit_inline`."""
+
+    def init_customizations(self, settings):
+        """Setting-based customizations; run when parsing begins."""
+        if settings.pep_references:
+            self.implicit_dispatch.append((self.patterns.pep,
+                                           self.pep_reference))
+        if settings.rfc_references:
+            self.implicit_dispatch.append((self.patterns.rfc,
+                                           self.rfc_reference))
+
+    def parse(self, text, lineno, memo, parent):
+        # Needs to be refactored for nested inline markup.
+        # Add nested_parse() method?
+        """
+        Return 2 lists: nodes (text and inline elements), and system_messages.
+
+        Using `self.patterns.initial`, a pattern which matches start-strings
+        (emphasis, strong, interpreted, phrase reference, literal,
+        substitution reference, and inline target) and complete constructs
+        (simple reference, footnote reference), search for a candidate.  When
+        one is found, check for validity (e.g., not a quoted '*' character).
+        If valid, search for the corresponding end string if applicable, and
+        check it for validity.  If not found or invalid, generate a warning
+        and ignore the start-string.  Implicit inline markup (e.g. standalone
+        URIs) is found last.
+        """
+        self.reporter = memo.reporter
+        self.document = memo.document
+        self.language = memo.language
+        self.parent = parent
+        pattern_search = self.patterns.initial.search
+        dispatch = self.dispatch
+        remaining = escape2null(text)
+        processed = []
+        unprocessed = []
+        messages = []
+        while remaining:
+            match = pattern_search(remaining)
+            if match:
+                groups = match.groupdict()
+                method = dispatch[groups['start'] or groups['backquote']
+                                  or groups['refend'] or groups['fnend']]
+                before, inlines, remaining, sysmessages = method(self, match,
+                                                                 lineno)
+                unprocessed.append(before)
+                messages += sysmessages
+                if inlines:
+                    processed += self.implicit_inline(''.join(unprocessed),
+                                                      lineno)
+                    processed += inlines
+                    unprocessed = []
+            else:
+                break
+        remaining = ''.join(unprocessed) + remaining
+        if remaining:
+            processed += self.implicit_inline(remaining, lineno)
+        return processed, messages
+
+    # Inline object recognition
+    # -------------------------
+    # lookahead and look-behind expressions for inline markup rules
+    start_string_prefix = (u'(^|(?<=\\s|[%s%s]))' %
+                           (punctuation_chars.openers,
+                            punctuation_chars.delimiters))
+    end_string_suffix = (u'($|(?=\\s|[\x00%s%s%s]))' %
+                         (punctuation_chars.closing_delimiters,
+                          punctuation_chars.delimiters,
+                          punctuation_chars.closers))
+    # print start_string_prefix.encode('utf8')
+    # TODO: support non-ASCII whitespace in the following 4 patterns?
+    non_whitespace_before = r'(?<![ \n])'
+    non_whitespace_escape_before = r'(?<![ \n\x00])'
+    non_unescaped_whitespace_escape_before = r'(?<!(?<!\x00)[ \n\x00])'
+    non_whitespace_after = r'(?![ \n])'
+    # Alphanumerics with isolated internal [-._+:] chars (i.e. not 2 together):
+    simplename = r'(?:(?!_)\w)+(?:[-._+:](?:(?!_)\w)+)*'
+    # Valid URI characters (see RFC 2396 & RFC 2732);
+    # final \x00 allows backslash escapes in URIs:
+    uric = r"""[-_.!~*'()[\];/:@&=+$,%a-zA-Z0-9\x00]"""
+    # Delimiter indicating the end of a URI (not part of the URI):
+    uri_end_delim = r"""[>]"""
+    # Last URI character; same as uric but no punctuation:
+    urilast = r"""[_~*/=+a-zA-Z0-9]"""
+    # End of a URI (either 'urilast' or 'uric followed by a
+    # uri_end_delim'):
+    uri_end = r"""(?:%(urilast)s|%(uric)s(?=%(uri_end_delim)s))""" % locals()
+    emailc = r"""[-_!~*'{|}/#?^`&=+$%a-zA-Z0-9\x00]"""
+    email_pattern = r"""
+          %(emailc)s+(?:\.%(emailc)s+)*   # name
+          (?<!\x00)@                      # at
+          %(emailc)s+(?:\.%(emailc)s*)*   # host
+          %(uri_end)s                     # final URI char
+          """
+    parts = ('initial_inline', start_string_prefix, '',
+             [('start', '', non_whitespace_after,  # simple start-strings
+               [r'\*\*',                # strong
+                r'\*(?!\*)',            # emphasis but not strong
+                r'``',                  # literal
+                r'_`',                  # inline internal target
+                r'\|(?!\|)']            # substitution reference
+               ),
+              ('whole', '', end_string_suffix, # whole constructs
+               [# reference name & end-string
+                r'(?P<refname>%s)(?P<refend>__?)' % simplename,
+                ('footnotelabel', r'\[', r'(?P<fnend>\]_)',
+                 [r'[0-9]+',               # manually numbered
+                  r'\#(%s)?' % simplename, # auto-numbered (w/ label?)
+                  r'\*',                   # auto-symbol
+                  r'(?P<citationlabel>%s)' % simplename] # citation reference
+                 )
+                ]
+               ),
+              ('backquote',             # interpreted text or phrase reference
+               '(?P<role>(:%s:)?)' % simplename, # optional role
+               non_whitespace_after,
+               ['`(?!`)']               # but not literal
+               )
+              ]
+             )
+    patterns = Struct(
+          initial=build_regexp(parts),
+          emphasis=re.compile(non_whitespace_escape_before
+                              + r'(\*)' + end_string_suffix, re.UNICODE),
+          strong=re.compile(non_whitespace_escape_before
+                            + r'(\*\*)' + end_string_suffix, re.UNICODE),
+          interpreted_or_phrase_ref=re.compile(
+              r"""
+              %(non_unescaped_whitespace_escape_before)s
+              (
+                `
+                (?P<suffix>
+                  (?P<role>:%(simplename)s:)?
+                  (?P<refend>__?)?
+                )
+              )
+              %(end_string_suffix)s
+              """ % locals(), re.VERBOSE | re.UNICODE),
+          embedded_uri=re.compile(
+              r"""
+              (
+                (?:[ \n]+|^)            # spaces or beginning of line/string
+                <                       # open bracket
+                %(non_whitespace_after)s
+                ([^<>\x00]+)            # anything but angle brackets & nulls
+                %(non_whitespace_before)s
+                >                       # close bracket w/o whitespace before
+              )
+              $                         # end of string
+              """ % locals(), re.VERBOSE | re.UNICODE),
+          literal=re.compile(non_whitespace_before + '(``)'
+                             + end_string_suffix),
+          target=re.compile(non_whitespace_escape_before
+                            + r'(`)' + end_string_suffix),
+          substitution_ref=re.compile(non_whitespace_escape_before
+                                      + r'(\|_{0,2})'
+                                      + end_string_suffix),
+          email=re.compile(email_pattern % locals() + '$',
+                           re.VERBOSE | re.UNICODE),
+          uri=re.compile(
+                (r"""
+                %(start_string_prefix)s
+                (?P<whole>
+                  (?P<absolute>           # absolute URI
+                    (?P<scheme>             # scheme (http, ftp, mailto)
+                      [a-zA-Z][a-zA-Z0-9.+-]*
+                    )
+                    :
+                    (
+                      (                       # either:
+                        (//?)?                  # hierarchical URI
+                        %(uric)s*               # URI characters
+                        %(uri_end)s             # final URI char
+                      )
+                      (                       # optional query
+                        \?%(uric)s*
+                        %(uri_end)s
+                      )?
+                      (                       # optional fragment
+                        \#%(uric)s*
+                        %(uri_end)s
+                      )?
+                    )
+                  )
+                |                       # *OR*
+                  (?P<email>              # email address
+                    """ + email_pattern + r"""
+                  )
+                )
+                %(end_string_suffix)s
+                """) % locals(), re.VERBOSE | re.UNICODE),
+          pep=re.compile(
+                r"""
+                %(start_string_prefix)s
+                (
+                  (pep-(?P<pepnum1>\d+)(.txt)?) # reference to source file
+                |
+                  (PEP\s+(?P<pepnum2>\d+))      # reference by name
+                )
+                %(end_string_suffix)s""" % locals(), re.VERBOSE | re.UNICODE),
+          rfc=re.compile(
+                r"""
+                %(start_string_prefix)s
+                (RFC(-|\s+)?(?P<rfcnum>\d+))
+                %(end_string_suffix)s""" % locals(), re.VERBOSE | re.UNICODE))
+
+    def quoted_start(self, match):
+        """Test if inline markup start-string is 'quoted'.
+
+        'Quoted' in this context means the start-string is enclosed in a pair
+        of matching opening/closing delimiters (not necessarily quotes)
+        or at the end of the match.
+        """
+        string = match.string
+        start = match.start()
+        if start == 0:                  # start-string at beginning of text
+            return False
+        prestart = string[start - 1]
+        try:
+            poststart = string[match.end()]
+        except IndexError:          # start-string at end of text
+            return True  # not "quoted" but no markup start-string either
+        return punctuation_chars.match_chars(prestart, poststart)
+
+    def inline_obj(self, match, lineno, end_pattern, nodeclass,
+                   restore_backslashes=False):
+        string = match.string
+        matchstart = match.start('start')
+        matchend = match.end('start')
+        if self.quoted_start(match):
+            return (string[:matchend], [], string[matchend:], [], '')
+        endmatch = end_pattern.search(string[matchend:])
+        if endmatch and endmatch.start(1):  # 1 or more chars
+            text = unescape(endmatch.string[:endmatch.start(1)],
+                            restore_backslashes)
+            textend = matchend + endmatch.end(1)
+            rawsource = unescape(string[matchstart:textend], 1)
+            return (string[:matchstart], [nodeclass(rawsource, text)],
+                    string[textend:], [], endmatch.group(1))
+        msg = self.reporter.warning(
+              'Inline %s start-string without end-string.'
+              % nodeclass.__name__, line=lineno)
+        text = unescape(string[matchstart:matchend], 1)
+        rawsource = unescape(string[matchstart:matchend], 1)
+        prb = self.problematic(text, rawsource, msg)
+        return string[:matchstart], [prb], string[matchend:], [msg], ''
+
+    def problematic(self, text, rawsource, message):
+        msgid = self.document.set_id(message, self.parent)
+        problematic = nodes.problematic(rawsource, text, refid=msgid)
+        prbid = self.document.set_id(problematic)
+        message.add_backref(prbid)
+        return problematic
+
+    def emphasis(self, match, lineno):
+        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
+              match, lineno, self.patterns.emphasis, nodes.emphasis)
+        return before, inlines, remaining, sysmessages
+
+    def strong(self, match, lineno):
+        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
+              match, lineno, self.patterns.strong, nodes.strong)
+        return before, inlines, remaining, sysmessages
+
+    def interpreted_or_phrase_ref(self, match, lineno):
+        end_pattern = self.patterns.interpreted_or_phrase_ref
+        string = match.string
+        matchstart = match.start('backquote')
+        matchend = match.end('backquote')
+        rolestart = match.start('role')
+        role = match.group('role')
+        position = ''
+        if role:
+            role = role[1:-1]
+            position = 'prefix'
+        elif self.quoted_start(match):
+            return (string[:matchend], [], string[matchend:], [])
+        endmatch = end_pattern.search(string[matchend:])
+        if endmatch and endmatch.start(1):  # 1 or more chars
+            textend = matchend + endmatch.end()
+            if endmatch.group('role'):
+                if role:
+                    msg = self.reporter.warning(
+                        'Multiple roles in interpreted text (both '
+                        'prefix and suffix present; only one allowed).',
+                        line=lineno)
+                    text = unescape(string[rolestart:textend], 1)
+                    prb = self.problematic(text, text, msg)
+                    return string[:rolestart], [prb], string[textend:], [msg]
+                role = endmatch.group('suffix')[1:-1]
+                position = 'suffix'
+            escaped = endmatch.string[:endmatch.start(1)]
+            rawsource = unescape(string[matchstart:textend], 1)
+            if rawsource[-1:] == '_':
+                if role:
+                    msg = self.reporter.warning(
+                          'Mismatch: both interpreted text role %s and '
+                          'reference suffix.' % position, line=lineno)
+                    text = unescape(string[rolestart:textend], 1)
+                    prb = self.problematic(text, text, msg)
+                    return string[:rolestart], [prb], string[textend:], [msg]
+                return self.phrase_ref(string[:matchstart], string[textend:],
+                                       rawsource, escaped, unescape(escaped))
+            else:
+                rawsource = unescape(string[rolestart:textend], 1)
+                nodelist, messages = self.interpreted(rawsource, escaped, role,
+                                                      lineno)
+                return (string[:rolestart], nodelist,
+                        string[textend:], messages)
+        msg = self.reporter.warning(
+              'Inline interpreted text or phrase reference start-string '
+              'without end-string.', line=lineno)
+        text = unescape(string[matchstart:matchend], 1)
+        prb = self.problematic(text, text, msg)
+        return string[:matchstart], [prb], string[matchend:], [msg]
+
+    def phrase_ref(self, before, after, rawsource, escaped, text):
+        match = self.patterns.embedded_uri.search(escaped)
+        if match:
+            text = unescape(escaped[:match.start(0)])
+            uri_text = match.group(2)
+            uri = ''.join(uri_text.split())
+            uri = self.adjust_uri(uri)
+            if uri:
+                target = nodes.target(match.group(1), refuri=uri)
+                target.referenced = 1
+            else:
+                raise ApplicationError('problem with URI: %r' % uri_text)
+            if not text:
+                text = uri
+        else:
+            target = None
+        refname = normalize_name(text)
+        reference = nodes.reference(rawsource, text,
+                                    name=whitespace_normalize_name(text))
+        node_list = [reference]
+        if rawsource[-2:] == '__':
+            if target:
+                reference['refuri'] = uri
+            else:
+                reference['anonymous'] = 1
+        else:
+            if target:
+                reference['refuri'] = uri
+                target['names'].append(refname)
+                self.document.note_explicit_target(target, self.parent)
+                node_list.append(target)
+            else:
+                reference['refname'] = refname
+                self.document.note_refname(reference)
+        return before, node_list, after, []
+
+    def adjust_uri(self, uri):
+        match = self.patterns.email.match(uri)
+        if match:
+            return 'mailto:' + uri
+        else:
+            return uri
+
+    def interpreted(self, rawsource, text, role, lineno):
+        role_fn, messages = roles.role(role, self.language, lineno,
+                                       self.reporter)
+        if role_fn:
+            nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
+            return nodes, messages + messages2
+        else:
+            msg = self.reporter.error(
+                'Unknown interpreted text role "%s".' % role,
+                line=lineno)
+            return ([self.problematic(rawsource, rawsource, msg)],
+                    messages + [msg])
+
+    def literal(self, match, lineno):
+        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
+              match, lineno, self.patterns.literal, nodes.literal,
+              restore_backslashes=True)
+        return before, inlines, remaining, sysmessages
+
+    def inline_internal_target(self, match, lineno):
+        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
+              match, lineno, self.patterns.target, nodes.target)
+        if inlines and isinstance(inlines[0], nodes.target):
+            assert len(inlines) == 1
+            target = inlines[0]
+            name = normalize_name(target.astext())
+            target['names'].append(name)
+            self.document.note_explicit_target(target, self.parent)
+        return before, inlines, remaining, sysmessages
+
+    def substitution_reference(self, match, lineno):
+        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
+              match, lineno, self.patterns.substitution_ref,
+              nodes.substitution_reference)
+        if len(inlines) == 1:
+            subref_node = inlines[0]
+            if isinstance(subref_node, nodes.substitution_reference):
+                subref_text = subref_node.astext()
+                self.document.note_substitution_ref(subref_node, subref_text)
+                if endstring[-1:] == '_':
+                    reference_node = nodes.reference(
+                        '|%s%s' % (subref_text, endstring), '')
+                    if endstring[-2:] == '__':
+                        reference_node['anonymous'] = 1
+                    else:
+                        reference_node['refname'] = normalize_name(subref_text)
+                        self.document.note_refname(reference_node)
+                    reference_node += subref_node
+                    inlines = [reference_node]
+        return before, inlines, remaining, sysmessages
+
+    def footnote_reference(self, match, lineno):
+        """
+        Handles `nodes.footnote_reference` and `nodes.citation_reference`
+        elements.
+        """
+        label = match.group('footnotelabel')
+        refname = normalize_name(label)
+        string = match.string
+        before = string[:match.start('whole')]
+        remaining = string[match.end('whole'):]
+        if match.group('citationlabel'):
+            refnode = nodes.citation_reference('[%s]_' % label,
+                                               refname=refname)
+            refnode += nodes.Text(label)
+            self.document.note_citation_ref(refnode)
+        else:
+            refnode = nodes.footnote_reference('[%s]_' % label)
+            if refname[0] == '#':
+                refname = refname[1:]
+                refnode['auto'] = 1
+                self.document.note_autofootnote_ref(refnode)
+            elif refname == '*':
+                refname = ''
+                refnode['auto'] = '*'
+                self.document.note_symbol_footnote_ref(
+                      refnode)
+            else:
+                refnode += nodes.Text(label)
+            if refname:
+                refnode['refname'] = refname
+                self.document.note_footnote_ref(refnode)
+            if utils.get_trim_footnote_ref_space(self.document.settings):
+                before = before.rstrip()
+        return (before, [refnode], remaining, [])
+
+    def reference(self, match, lineno, anonymous=False):
+        referencename = match.group('refname')
+        refname = normalize_name(referencename)
+        referencenode = nodes.reference(
+            referencename + match.group('refend'), referencename,
+            name=whitespace_normalize_name(referencename))
+        if anonymous:
+            referencenode['anonymous'] = 1
+        else:
+            referencenode['refname'] = refname
+            self.document.note_refname(referencenode)
+        string = match.string
+        matchstart = match.start('whole')
+        matchend = match.end('whole')
+        return (string[:matchstart], [referencenode], string[matchend:], [])
+
+    def anonymous_reference(self, match, lineno):
+        return self.reference(match, lineno, anonymous=1)
+
+    def standalone_uri(self, match, lineno):
+        if (not match.group('scheme')
+                or match.group('scheme').lower() in urischemes.schemes):
+            if match.group('email'):
+                addscheme = 'mailto:'
+            else:
+                addscheme = ''
+            text = match.group('whole')
+            unescaped = unescape(text, 0)
+            return [nodes.reference(unescape(text, 1), unescaped,
+                                    refuri=addscheme + unescaped)]
+        else:                   # not a valid scheme
+            raise MarkupMismatch
+
+    def pep_reference(self, match, lineno):
+        text = match.group(0)
+        if text.startswith('pep-'):
+            pepnum = int(match.group('pepnum1'))
+        elif text.startswith('PEP'):
+            pepnum = int(match.group('pepnum2'))
+        else:
+            raise MarkupMismatch
+        ref = (self.document.settings.pep_base_url
+               + self.document.settings.pep_file_url_template % pepnum)
+        unescaped = unescape(text, 0)
+        return [nodes.reference(unescape(text, 1), unescaped, refuri=ref)]
+
+    rfc_url = 'rfc%d.html'
+
+    def rfc_reference(self, match, lineno):
+        text = match.group(0)
+        if text.startswith('RFC'):
+            rfcnum = int(match.group('rfcnum'))
+            ref = self.document.settings.rfc_base_url + self.rfc_url % rfcnum
+        else:
+            raise MarkupMismatch
+        unescaped = unescape(text, 0)
+        return [nodes.reference(unescape(text, 1), unescaped, refuri=ref)]
+
+    def implicit_inline(self, text, lineno):
+        """
+        Check each of the patterns in `self.implicit_dispatch` for a match,
+        and dispatch to the stored method for the pattern.  Recursively check
+        the text before and after the match.  Return a list of `nodes.Text`
+        and inline element nodes.
+        """
+        if not text:
+            return []
+        for pattern, method in self.implicit_dispatch:
+            match = pattern.search(text)
+            if match:
+                try:
+                    # Must recurse on strings before *and* after the match;
+                    # there may be multiple patterns.
+                    return (self.implicit_inline(text[:match.start()], lineno)
+                            + method(match, lineno) +
+                            self.implicit_inline(text[match.end():], lineno))
+                except MarkupMismatch:
+                    pass
+        return [nodes.Text(unescape(text), rawsource=unescape(text, 1))]
+
+    dispatch = {'*': emphasis,
+                '**': strong,
+                '`': interpreted_or_phrase_ref,
+                '``': literal,
+                '_`': inline_internal_target,
+                ']_': footnote_reference,
+                '|': substitution_reference,
+                '_': reference,
+                '__': anonymous_reference}
+
+
+def _loweralpha_to_int(s, _zero=(ord('a')-1)):
+    return ord(s) - _zero
+
+def _upperalpha_to_int(s, _zero=(ord('A')-1)):
+    return ord(s) - _zero
+
+def _lowerroman_to_int(s):
+    return roman.fromRoman(s.upper())
+
+
+class Body(RSTState):
+
+    """
+    Generic classifier of the first line of a block.
+    """
+
+    double_width_pad_char = tableparser.TableParser.double_width_pad_char
+    """Padding character for East Asian double-width text."""
+
+    enum = Struct()
+    """Enumerated list parsing information."""
+
+    enum.formatinfo = {
+          'parens': Struct(prefix='(', suffix=')', start=1, end=-1),
+          'rparen': Struct(prefix='', suffix=')', start=0, end=-1),
+          'period': Struct(prefix='', suffix='.', start=0, end=-1)}
+    enum.formats = enum.formatinfo.keys()
+    enum.sequences = ['arabic', 'loweralpha', 'upperalpha',
+                      'lowerroman', 'upperroman'] # ORDERED!
+    enum.sequencepats = {'arabic': '[0-9]+',
+                         'loweralpha': '[a-z]',
+                         'upperalpha': '[A-Z]',
+                         'lowerroman': '[ivxlcdm]+',
+                         'upperroman': '[IVXLCDM]+',}
+    enum.converters = {'arabic': int,
+                       'loweralpha': _loweralpha_to_int,
+                       'upperalpha': _upperalpha_to_int,
+                       'lowerroman': _lowerroman_to_int,
+                       'upperroman': roman.fromRoman}
+
+    enum.sequenceregexps = {}
+    for sequence in enum.sequences:
+        enum.sequenceregexps[sequence] = re.compile(
+              enum.sequencepats[sequence] + '$', re.UNICODE)
+
+    grid_table_top_pat = re.compile(r'\+-[-+]+-\+ *$')
+    """Matches the top (& bottom) of a full table)."""
+
+    simple_table_top_pat = re.compile('=+( +=+)+ *$')
+    """Matches the top of a simple table."""
+
+    simple_table_border_pat = re.compile('=+[ =]*$')
+    """Matches the bottom & header bottom of a simple table."""
+
+    pats = {}
+    """Fragments of patterns used by transitions."""
+
+    pats['nonalphanum7bit'] = '[!-/:-@[-`{-~]'
+    pats['alpha'] = '[a-zA-Z]'
+    pats['alphanum'] = '[a-zA-Z0-9]'
+    pats['alphanumplus'] = '[a-zA-Z0-9_-]'
+    pats['enum'] = ('(%(arabic)s|%(loweralpha)s|%(upperalpha)s|%(lowerroman)s'
+                    '|%(upperroman)s|#)' % enum.sequencepats)
+    pats['optname'] = '%(alphanum)s%(alphanumplus)s*' % pats
+    # @@@ Loosen up the pattern?  Allow Unicode?
+    pats['optarg'] = '(%(alpha)s%(alphanumplus)s*|<[^<>]+>)' % pats
+    pats['shortopt'] = r'(-|\+)%(alphanum)s( ?%(optarg)s)?' % pats
+    pats['longopt'] = r'(--|/)%(optname)s([ =]%(optarg)s)?' % pats
+    pats['option'] = r'(%(shortopt)s|%(longopt)s)' % pats
+
+    for format in enum.formats:
+        pats[format] = '(?P<%s>%s%s%s)' % (
+              format, re.escape(enum.formatinfo[format].prefix),
+              pats['enum'], re.escape(enum.formatinfo[format].suffix))
+
+    patterns = {
+          'bullet': u'[-+*\u2022\u2023\u2043]( +|$)',
+          'enumerator': r'(%(parens)s|%(rparen)s|%(period)s)( +|$)' % pats,
+          'field_marker': r':(?![: ])([^:\\]|\\.)*(?<! ):( +|$)',
+          'option_marker': r'%(option)s(, %(option)s)*(  +| ?$)' % pats,
+          'doctest': r'>>>( +|$)',
+          'line_block': r'\|( +|$)',
+          'grid_table_top': grid_table_top_pat,
+          'simple_table_top': simple_table_top_pat,
+          'explicit_markup': r'\.\.( +|$)',
+          'anonymous': r'__( +|$)',
+          'line': r'(%(nonalphanum7bit)s)\1* *$' % pats,
+          'text': r''}
+    initial_transitions = (
+          'bullet',
+          'enumerator',
+          'field_marker',
+          'option_marker',
+          'doctest',
+          'line_block',
+          'grid_table_top',
+          'simple_table_top',
+          'explicit_markup',
+          'anonymous',
+          'line',
+          'text')
+
+    def indent(self, match, context, next_state):
+        """Block quote."""
+        indented, indent, line_offset, blank_finish = \
+              self.state_machine.get_indented()
+        elements = self.block_quote(indented, line_offset)
+        self.parent += elements
+        if not blank_finish:
+            self.parent += self.unindent_warning('Block quote')
+        return context, next_state, []
+
+    def block_quote(self, indented, line_offset):
+        elements = []
+        while indented:
+            (blockquote_lines,
+             attribution_lines,
+             attribution_offset,
+             indented,
+             new_line_offset) = self.split_attribution(indented, line_offset)
+            blockquote = nodes.block_quote()
+            self.nested_parse(blockquote_lines, line_offset, blockquote)
+            elements.append(blockquote)
+            if attribution_lines:
+                attribution, messages = self.parse_attribution(
+                    attribution_lines, attribution_offset)
+                blockquote += attribution
+                elements += messages
+            line_offset = new_line_offset
+            while indented and not indented[0]:
+                indented = indented[1:]
+                line_offset += 1
+        return elements
+
+    # U+2014 is an em-dash:
+    attribution_pattern = re.compile(u'(---?(?!-)|\u2014) *(?=[^ \\n])',
+                                     re.UNICODE)
+
+    def split_attribution(self, indented, line_offset):
+        """
+        Check for a block quote attribution and split it off:
+
+        * First line after a blank line must begin with a dash ("--", "---",
+          em-dash; matches `self.attribution_pattern`).
+        * Every line after that must have consistent indentation.
+        * Attributions must be preceded by block quote content.
+
+        Return a tuple of: (block quote content lines, content offset,
+        attribution lines, attribution offset, remaining indented lines).
+        """
+        blank = None
+        nonblank_seen = False
+        for i in range(len(indented)):
+            line = indented[i].rstrip()
+            if line:
+                if nonblank_seen and blank == i - 1: # last line blank
+                    match = self.attribution_pattern.match(line)
+                    if match:
+                        attribution_end, indent = self.check_attribution(
+                            indented, i)
+                        if attribution_end:
+                            a_lines = indented[i:attribution_end]
+                            a_lines.trim_left(match.end(), end=1)
+                            a_lines.trim_left(indent, start=1)
+                            return (indented[:i], a_lines,
+                                    i, indented[attribution_end:],
+                                    line_offset + attribution_end)
+                nonblank_seen = True
+            else:
+                blank = i
+        else:
+            return (indented, None, None, None, None)
+
+    def check_attribution(self, indented, attribution_start):
+        """
+        Check attribution shape.
+        Return the index past the end of the attribution, and the indent.
+        """
+        indent = None
+        i = attribution_start + 1
+        for i in range(attribution_start + 1, len(indented)):
+            line = indented[i].rstrip()
+            if not line:
+                break
+            if indent is None:
+                indent = len(line) - len(line.lstrip())
+            elif len(line) - len(line.lstrip()) != indent:
+                return None, None       # bad shape; not an attribution
+        else:
+            # return index of line after last attribution line:
+            i += 1
+        return i, (indent or 0)
+
+    def parse_attribution(self, indented, line_offset):
+        text = '\n'.join(indented).rstrip()
+        lineno = self.state_machine.abs_line_number() + line_offset
+        textnodes, messages = self.inline_text(text, lineno)
+        node = nodes.attribution(text, '', *textnodes)
+        node.source, node.line = self.state_machine.get_source_and_line(lineno)
+        return node, messages
+
+    def bullet(self, match, context, next_state):
+        """Bullet list item."""
+        bulletlist = nodes.bullet_list()
+        self.parent += bulletlist
+        bulletlist['bullet'] = match.string[0]
+        i, blank_finish = self.list_item(match.end())
+        bulletlist += i
+        offset = self.state_machine.line_offset + 1   # next line
+        new_line_offset, blank_finish = self.nested_list_parse(
+              self.state_machine.input_lines[offset:],
+              input_offset=self.state_machine.abs_line_offset() + 1,
+              node=bulletlist, initial_state='BulletList',
+              blank_finish=blank_finish)
+        self.goto_line(new_line_offset)
+        if not blank_finish:
+            self.parent += self.unindent_warning('Bullet list')
+        return [], next_state, []
+
+    def list_item(self, indent):
+        if self.state_machine.line[indent:]:
+            indented, line_offset, blank_finish = (
+                self.state_machine.get_known_indented(indent))
+        else:
+            indented, indent, line_offset, blank_finish = (
+                self.state_machine.get_first_known_indented(indent))
+        listitem = nodes.list_item('\n'.join(indented))
+        if indented:
+            self.nested_parse(indented, input_offset=line_offset,
+                              node=listitem)
+        return listitem, blank_finish
+
+    def enumerator(self, match, context, next_state):
+        """Enumerated List Item"""
+        format, sequence, text, ordinal = self.parse_enumerator(match)
+        if not self.is_enumerated_list_item(ordinal, sequence, format):
+            raise statemachine.TransitionCorrection('text')
+        enumlist = nodes.enumerated_list()
+        self.parent += enumlist
+        if sequence == '#':
+            enumlist['enumtype'] = 'arabic'
+        else:
+            enumlist['enumtype'] = sequence
+        enumlist['prefix'] = self.enum.formatinfo[format].prefix
+        enumlist['suffix'] = self.enum.formatinfo[format].suffix
+        if ordinal != 1:
+            enumlist['start'] = ordinal
+            msg = self.reporter.info(
+                'Enumerated list start value not ordinal-1: "%s" (ordinal %s)'
+                % (text, ordinal))
+            self.parent += msg
+        listitem, blank_finish = self.list_item(match.end())
+        enumlist += listitem
+        offset = self.state_machine.line_offset + 1   # next line
+        newline_offset, blank_finish = self.nested_list_parse(
+              self.state_machine.input_lines[offset:],
+              input_offset=self.state_machine.abs_line_offset() + 1,
+              node=enumlist, initial_state='EnumeratedList',
+              blank_finish=blank_finish,
+              extra_settings={'lastordinal': ordinal,
+                              'format': format,
+                              'auto': sequence == '#'})
+        self.goto_line(newline_offset)
+        if not blank_finish:
+            self.parent += self.unindent_warning('Enumerated list')
+        return [], next_state, []
+
+    def parse_enumerator(self, match, expected_sequence=None):
+        """
+        Analyze an enumerator and return the results.
+
+        :Return:
+            - the enumerator format ('period', 'parens', or 'rparen'),
+            - the sequence used ('arabic', 'loweralpha', 'upperroman', etc.),
+            - the text of the enumerator, stripped of formatting, and
+            - the ordinal value of the enumerator ('a' -> 1, 'ii' -> 2, etc.;
+              ``None`` is returned for invalid enumerator text).
+
+        The enumerator format has already been determined by the regular
+        expression match. If `expected_sequence` is given, that sequence is
+        tried first. If not, we check for Roman numeral 1. This way,
+        single-character Roman numerals (which are also alphabetical) can be
+        matched. If no sequence has been matched, all sequences are checked in
+        order.
+        """
+        groupdict = match.groupdict()
+        sequence = ''
+        for format in self.enum.formats:
+            if groupdict[format]:       # was this the format matched?
+                break                   # yes; keep `format`
+        else:                           # shouldn't happen
+            raise ParserError('enumerator format not matched')
+        text = groupdict[format][self.enum.formatinfo[format].start
+                                 :self.enum.formatinfo[format].end]
+        if text == '#':
+            sequence = '#'
+        elif expected_sequence:
+            try:
+                if self.enum.sequenceregexps[expected_sequence].match(text):
+                    sequence = expected_sequence
+            except KeyError:            # shouldn't happen
+                raise ParserError('unknown enumerator sequence: %s'
+                                  % sequence)
+        elif text == 'i':
+            sequence = 'lowerroman'
+        elif text == 'I':
+            sequence = 'upperroman'
+        if not sequence:
+            for sequence in self.enum.sequences:
+                if self.enum.sequenceregexps[sequence].match(text):
+                    break
+            else:                       # shouldn't happen
+                raise ParserError('enumerator sequence not matched')
+        if sequence == '#':
+            ordinal = 1
+        else:
+            try:
+                ordinal = self.enum.converters[sequence](text)
+            except roman.InvalidRomanNumeralError:
+                ordinal = None
+        return format, sequence, text, ordinal
+
+    def is_enumerated_list_item(self, ordinal, sequence, format):
+        """
+        Check validity based on the ordinal value and the second line.
+
+        Return true if the ordinal is valid and the second line is blank,
+        indented, or starts with the next enumerator or an auto-enumerator.
+        """
+        if ordinal is None:
+            return None
+        try:
+            next_line = self.state_machine.next_line()
+        except EOFError:              # end of input lines
+            self.state_machine.previous_line()
+            return 1
+        else:
+            self.state_machine.previous_line()
+        if not next_line[:1].strip():   # blank or indented
+            return 1
+        result = self.make_enumerator(ordinal + 1, sequence, format)
+        if result:
+            next_enumerator, auto_enumerator = result
+            try:
+                if ( next_line.startswith(next_enumerator) or
+                     next_line.startswith(auto_enumerator) ):
+                    return 1
+            except TypeError:
+                pass
+        return None
+
+    def make_enumerator(self, ordinal, sequence, format):
+        """
+        Construct and return the next enumerated list item marker, and an
+        auto-enumerator ("#" instead of the regular enumerator).
+
+        Return ``None`` for invalid (out of range) ordinals.
+        """ #"
+        if sequence == '#':
+            enumerator = '#'
+        elif sequence == 'arabic':
+            enumerator = str(ordinal)
+        else:
+            if sequence.endswith('alpha'):
+                if ordinal > 26:
+                    return None
+                enumerator = chr(ordinal + ord('a') - 1)
+            elif sequence.endswith('roman'):
+                try:
+                    enumerator = roman.toRoman(ordinal)
+                except roman.RomanError:
+                    return None
+            else:                       # shouldn't happen
+                raise ParserError('unknown enumerator sequence: "%s"'
+                                  % sequence)
+            if sequence.startswith('lower'):
+                enumerator = enumerator.lower()
+            elif sequence.startswith('upper'):
+                enumerator = enumerator.upper()
+            else:                       # shouldn't happen
+                raise ParserError('unknown enumerator sequence: "%s"'
+                                  % sequence)
+        formatinfo = self.enum.formatinfo[format]
+        next_enumerator = (formatinfo.prefix + enumerator + formatinfo.suffix
+                           + ' ')
+        auto_enumerator = formatinfo.prefix + '#' + formatinfo.suffix + ' '
+        return next_enumerator, auto_enumerator
+
+    def field_marker(self, match, context, next_state):
+        """Field list item."""
+        field_list = nodes.field_list()
+        self.parent += field_list
+        field, blank_finish = self.field(match)
+        field_list += field
+        offset = self.state_machine.line_offset + 1   # next line
+        newline_offset, blank_finish = self.nested_list_parse(
+              self.state_machine.input_lines[offset:],
+              input_offset=self.state_machine.abs_line_offset() + 1,
+              node=field_list, initial_state='FieldList',
+              blank_finish=blank_finish)
+        self.goto_line(newline_offset)
+        if not blank_finish:
+            self.parent += self.unindent_warning('Field list')
+        return [], next_state, []
+
+    def field(self, match):
+        name = self.parse_field_marker(match)
+        src, srcline = self.state_machine.get_source_and_line()
+        lineno = self.state_machine.abs_line_number()
+        indented, indent, line_offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end())
+        field_node = nodes.field()
+        field_node.source = src
+        field_node.line = srcline
+        name_nodes, name_messages = self.inline_text(name, lineno)
+        field_node += nodes.field_name(name, '', *name_nodes)
+        field_body = nodes.field_body('\n'.join(indented), *name_messages)
+        field_node += field_body
+        if indented:
+            self.parse_field_body(indented, line_offset, field_body)
+        return field_node, blank_finish
+
+    def parse_field_marker(self, match):
+        """Extract & return field name from a field marker match."""
+        field = match.group()[1:]        # strip off leading ':'
+        field = field[:field.rfind(':')] # strip off trailing ':' etc.
+        return field
+
+    def parse_field_body(self, indented, offset, node):
+        self.nested_parse(indented, input_offset=offset, node=node)
+
+    def option_marker(self, match, context, next_state):
+        """Option list item."""
+        optionlist = nodes.option_list()
+        try:
+            listitem, blank_finish = self.option_list_item(match)
+        except MarkupError, error:
+            # This shouldn't happen; pattern won't match.
+            msg = self.reporter.error(u'Invalid option list marker: %s' %
+                                      error)
+            self.parent += msg
+            indented, indent, line_offset, blank_finish = \
+                  self.state_machine.get_first_known_indented(match.end())
+            elements = self.block_quote(indented, line_offset)
+            self.parent += elements
+            if not blank_finish:
+                self.parent += self.unindent_warning('Option list')
+            return [], next_state, []
+        self.parent += optionlist
+        optionlist += listitem
+        offset = self.state_machine.line_offset + 1   # next line
+        newline_offset, blank_finish = self.nested_list_parse(
+              self.state_machine.input_lines[offset:],
+              input_offset=self.state_machine.abs_line_offset() + 1,
+              node=optionlist, initial_state='OptionList',
+              blank_finish=blank_finish)
+        self.goto_line(newline_offset)
+        if not blank_finish:
+            self.parent += self.unindent_warning('Option list')
+        return [], next_state, []
+
+    def option_list_item(self, match):
+        offset = self.state_machine.abs_line_offset()
+        options = self.parse_option_marker(match)
+        indented, indent, line_offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end())
+        if not indented:                # not an option list item
+            self.goto_line(offset)
+            raise statemachine.TransitionCorrection('text')
+        option_group = nodes.option_group('', *options)
+        description = nodes.description('\n'.join(indented))
+        option_list_item = nodes.option_list_item('', option_group,
+                                                  description)
+        if indented:
+            self.nested_parse(indented, input_offset=line_offset,
+                              node=description)
+        return option_list_item, blank_finish
+
+    def parse_option_marker(self, match):
+        """
+        Return a list of `node.option` and `node.option_argument` objects,
+        parsed from an option marker match.
+
+        :Exception: `MarkupError` for invalid option markers.
+        """
+        optlist = []
+        optionstrings = match.group().rstrip().split(', ')
+        for optionstring in optionstrings:
+            tokens = optionstring.split()
+            delimiter = ' '
+            firstopt = tokens[0].split('=', 1)
+            if len(firstopt) > 1:
+                # "--opt=value" form
+                tokens[:1] = firstopt
+                delimiter = '='
+            elif (len(tokens[0]) > 2
+                  and ((tokens[0].startswith('-')
+                        and not tokens[0].startswith('--'))
+                       or tokens[0].startswith('+'))):
+                # "-ovalue" form
+                tokens[:1] = [tokens[0][:2], tokens[0][2:]]
+                delimiter = ''
+            if len(tokens) > 1 and (tokens[1].startswith('<')
+                                    and tokens[-1].endswith('>')):
+                # "-o <value1 value2>" form; join all values into one token
+                tokens[1:] = [' '.join(tokens[1:])]
+            if 0 < len(tokens) <= 2:
+                option = nodes.option(optionstring)
+                option += nodes.option_string(tokens[0], tokens[0])
+                if len(tokens) > 1:
+                    option += nodes.option_argument(tokens[1], tokens[1],
+                                                    delimiter=delimiter)
+                optlist.append(option)
+            else:
+                raise MarkupError(
+                    'wrong number of option tokens (=%s), should be 1 or 2: '
+                    '"%s"' % (len(tokens), optionstring))
+        return optlist
+
+    def doctest(self, match, context, next_state):
+        data = '\n'.join(self.state_machine.get_text_block())
+        self.parent += nodes.doctest_block(data, data)
+        return [], next_state, []
+
+    def line_block(self, match, context, next_state):
+        """First line of a line block."""
+        block = nodes.line_block()
+        self.parent += block
+        lineno = self.state_machine.abs_line_number()
+        line, messages, blank_finish = self.line_block_line(match, lineno)
+        block += line
+        self.parent += messages
+        if not blank_finish:
+            offset = self.state_machine.line_offset + 1   # next line
+            new_line_offset, blank_finish = self.nested_list_parse(
+                  self.state_machine.input_lines[offset:],
+                  input_offset=self.state_machine.abs_line_offset() + 1,
+                  node=block, initial_state='LineBlock',
+                  blank_finish=0)
+            self.goto_line(new_line_offset)
+        if not blank_finish:
+            self.parent += self.reporter.warning(
+                'Line block ends without a blank line.',
+                line=lineno+1)
+        if len(block):
+            if block[0].indent is None:
+                block[0].indent = 0
+            self.nest_line_block_lines(block)
+        return [], next_state, []
+
+    def line_block_line(self, match, lineno):
+        """Return one line element of a line_block."""
+        indented, indent, line_offset, blank_finish = \
+            self.state_machine.get_first_known_indented(match.end(),
+                                                        until_blank=True)
+        text = u'\n'.join(indented)
+        text_nodes, messages = self.inline_text(text, lineno)
+        line = nodes.line(text, '', *text_nodes)
+        if match.string.rstrip() != '|': # not empty
+            line.indent = len(match.group(1)) - 1
+        return line, messages, blank_finish
+
+    def nest_line_block_lines(self, block):
+        for index in range(1, len(block)):
+            if block[index].indent is None:
+                block[index].indent = block[index - 1].indent
+        self.nest_line_block_segment(block)
+
+    def nest_line_block_segment(self, block):
+        indents = [item.indent for item in block]
+        least = min(indents)
+        new_items = []
+        new_block = nodes.line_block()
+        for item in block:
+            if item.indent > least:
+                new_block.append(item)
+            else:
+                if len(new_block):
+                    self.nest_line_block_segment(new_block)
+                    new_items.append(new_block)
+                    new_block = nodes.line_block()
+                new_items.append(item)
+        if len(new_block):
+            self.nest_line_block_segment(new_block)
+            new_items.append(new_block)
+        block[:] = new_items
+
+    def grid_table_top(self, match, context, next_state):
+        """Top border of a full table."""
+        return self.table_top(match, context, next_state,
+                              self.isolate_grid_table,
+                              tableparser.GridTableParser)
+
+    def simple_table_top(self, match, context, next_state):
+        """Top border of a simple table."""
+        return self.table_top(match, context, next_state,
+                              self.isolate_simple_table,
+                              tableparser.SimpleTableParser)
+
+    def table_top(self, match, context, next_state,
+                  isolate_function, parser_class):
+        """Top border of a generic table."""
+        nodelist, blank_finish = self.table(isolate_function, parser_class)
+        self.parent += nodelist
+        if not blank_finish:
+            msg = self.reporter.warning(
+                'Blank line required after table.',
+                line=self.state_machine.abs_line_number()+1)
+            self.parent += msg
+        return [], next_state, []
+
+    def table(self, isolate_function, parser_class):
+        """Parse a table."""
+        block, messages, blank_finish = isolate_function()
+        if block:
+            try:
+                parser = parser_class()
+                tabledata = parser.parse(block)
+                tableline = (self.state_machine.abs_line_number() - len(block)
+                             + 1)
+                table = self.build_table(tabledata, tableline)
+                nodelist = [table] + messages
+            except tableparser.TableMarkupError, err:
+                nodelist = self.malformed_table(block, ' '.join(err.args),
+                                                offset=err.offset) + messages
+        else:
+            nodelist = messages
+        return nodelist, blank_finish
+
+    def isolate_grid_table(self):
+        messages = []
+        blank_finish = 1
+        try:
+            block = self.state_machine.get_text_block(flush_left=True)
+        except statemachine.UnexpectedIndentationError, err:
+            block, src, srcline = err.args
+            messages.append(self.reporter.error('Unexpected indentation.',
+                                                source=src, line=srcline))
+            blank_finish = 0
+        block.disconnect()
+        # for East Asian chars:
+        block.pad_double_width(self.double_width_pad_char)
+        width = len(block[0].strip())
+        for i in range(len(block)):
+            block[i] = block[i].strip()
+            if block[i][0] not in '+|': # check left edge
+                blank_finish = 0
+                self.state_machine.previous_line(len(block) - i)
+                del block[i:]
+                break
+        if not self.grid_table_top_pat.match(block[-1]): # find bottom
+            blank_finish = 0
+            # from second-last to third line of table:
+            for i in range(len(block) - 2, 1, -1):
+                if self.grid_table_top_pat.match(block[i]):
+                    self.state_machine.previous_line(len(block) - i + 1)
+                    del block[i+1:]
+                    break
+            else:
+                messages.extend(self.malformed_table(block))
+                return [], messages, blank_finish
+        for i in range(len(block)):     # check right edge
+            if len(block[i]) != width or block[i][-1] not in '+|':
+                messages.extend(self.malformed_table(block))
+                return [], messages, blank_finish
+        return block, messages, blank_finish
+
+    def isolate_simple_table(self):
+        start = self.state_machine.line_offset
+        lines = self.state_machine.input_lines
+        limit = len(lines) - 1
+        toplen = len(lines[start].strip())
+        pattern_match = self.simple_table_border_pat.match
+        found = 0
+        found_at = None
+        i = start + 1
+        while i <= limit:
+            line = lines[i]
+            match = pattern_match(line)
+            if match:
+                if len(line.strip()) != toplen:
+                    self.state_machine.next_line(i - start)
+                    messages = self.malformed_table(
+                        lines[start:i+1], 'Bottom/header table border does '
+                        'not match top border.')
+                    return [], messages, i == limit or not lines[i+1].strip()
+                found += 1
+                found_at = i
+                if found == 2 or i == limit or not lines[i+1].strip():
+                    end = i
+                    break
+            i += 1
+        else:                           # reached end of input_lines
+            if found:
+                extra = ' or no blank line after table bottom'
+                self.state_machine.next_line(found_at - start)
+                block = lines[start:found_at+1]
+            else:
+                extra = ''
+                self.state_machine.next_line(i - start - 1)
+                block = lines[start:]
+            messages = self.malformed_table(
+                block, 'No bottom table border found%s.' % extra)
+            return [], messages, not extra
+        self.state_machine.next_line(end - start)
+        block = lines[start:end+1]
+        # for East Asian chars:
+        block.pad_double_width(self.double_width_pad_char)
+        return block, [], end == limit or not lines[end+1].strip()
+
+    def malformed_table(self, block, detail='', offset=0):
+        block.replace(self.double_width_pad_char, '')
+        data = '\n'.join(block)
+        message = 'Malformed table.'
+        startline = self.state_machine.abs_line_number() - len(block) + 1
+        if detail:
+            message += '\n' + detail
+        error = self.reporter.error(message, nodes.literal_block(data, data),
+                                    line=startline+offset)
+        return [error]
+
+    def build_table(self, tabledata, tableline, stub_columns=0):
+        colwidths, headrows, bodyrows = tabledata
+        table = nodes.table()
+        tgroup = nodes.tgroup(cols=len(colwidths))
+        table += tgroup
+        for colwidth in colwidths:
+            colspec = nodes.colspec(colwidth=colwidth)
+            if stub_columns:
+                colspec.attributes['stub'] = 1
+                stub_columns -= 1
+            tgroup += colspec
+        if headrows:
+            thead = nodes.thead()
+            tgroup += thead
+            for row in headrows:
+                thead += self.build_table_row(row, tableline)
+        tbody = nodes.tbody()
+        tgroup += tbody
+        for row in bodyrows:
+            tbody += self.build_table_row(row, tableline)
+        return table
+
+    def build_table_row(self, rowdata, tableline):
+        row = nodes.row()
+        for cell in rowdata:
+            if cell is None:
+                continue
+            morerows, morecols, offset, cellblock = cell
+            attributes = {}
+            if morerows:
+                attributes['morerows'] = morerows
+            if morecols:
+                attributes['morecols'] = morecols
+            entry = nodes.entry(**attributes)
+            row += entry
+            if ''.join(cellblock):
+                self.nested_parse(cellblock, input_offset=tableline+offset,
+                                  node=entry)
+        return row
+
+
+    explicit = Struct()
+    """Patterns and constants used for explicit markup recognition."""
+
+    explicit.patterns = Struct(
+          target=re.compile(r"""
+                            (
+                              _               # anonymous target
+                            |               # *OR*
+                              (?!_)           # no underscore at the beginning
+                              (?P<quote>`?)   # optional open quote
+                              (?![ `])        # first char. not space or
+                                              # backquote
+                              (?P<name>       # reference name
+                                .+?
+                              )
+                              %(non_whitespace_escape_before)s
+                              (?P=quote)      # close quote if open quote used
+                            )
+                            (?<!(?<!\x00):) # no unescaped colon at end
+                            %(non_whitespace_escape_before)s
+                            [ ]?            # optional space
+                            :               # end of reference name
+                            ([ ]+|$)        # followed by whitespace
+                            """ % vars(Inliner), re.VERBOSE | re.UNICODE),
+          reference=re.compile(r"""
+                               (
+                                 (?P<simple>%(simplename)s)_
+                               |                  # *OR*
+                                 `                  # open backquote
+                                 (?![ ])            # not space
+                                 (?P<phrase>.+?)    # hyperlink phrase
+                                 %(non_whitespace_escape_before)s
+                                 `_                 # close backquote,
+                                                    # reference mark
+                               )
+                               $                  # end of string
+                               """ % vars(Inliner), re.VERBOSE | re.UNICODE),
+          substitution=re.compile(r"""
+                                  (
+                                    (?![ ])          # first char. not space
+                                    (?P<name>.+?)    # substitution text
+                                    %(non_whitespace_escape_before)s
+                                    \|               # close delimiter
+                                  )
+                                  ([ ]+|$)           # followed by whitespace
+                                  """ % vars(Inliner),
+                                  re.VERBOSE | re.UNICODE),)
+
+    def footnote(self, match):
+        src, srcline = self.state_machine.get_source_and_line()
+        indented, indent, offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end())
+        label = match.group(1)
+        name = normalize_name(label)
+        footnote = nodes.footnote('\n'.join(indented))
+        footnote.source = src
+        footnote.line = srcline
+        if name[0] == '#':              # auto-numbered
+            name = name[1:]             # autonumber label
+            footnote['auto'] = 1
+            if name:
+                footnote['names'].append(name)
+            self.document.note_autofootnote(footnote)
+        elif name == '*':               # auto-symbol
+            name = ''
+            footnote['auto'] = '*'
+            self.document.note_symbol_footnote(footnote)
+        else:                           # manually numbered
+            footnote += nodes.label('', label)
+            footnote['names'].append(name)
+            self.document.note_footnote(footnote)
+        if name:
+            self.document.note_explicit_target(footnote, footnote)
+        else:
+            self.document.set_id(footnote, footnote)
+        if indented:
+            self.nested_parse(indented, input_offset=offset, node=footnote)
+        return [footnote], blank_finish
+
+    def citation(self, match):
+        src, srcline = self.state_machine.get_source_and_line()
+        indented, indent, offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end())
+        label = match.group(1)
+        name = normalize_name(label)
+        citation = nodes.citation('\n'.join(indented))
+        citation.source = src
+        citation.line = srcline
+        citation += nodes.label('', label)
+        citation['names'].append(name)
+        self.document.note_citation(citation)
+        self.document.note_explicit_target(citation, citation)
+        if indented:
+            self.nested_parse(indented, input_offset=offset, node=citation)
+        return [citation], blank_finish
+
+    def hyperlink_target(self, match):
+        pattern = self.explicit.patterns.target
+        lineno = self.state_machine.abs_line_number()
+        block, indent, offset, blank_finish = \
+              self.state_machine.get_first_known_indented(
+              match.end(), until_blank=True, strip_indent=False)
+        blocktext = match.string[:match.end()] + '\n'.join(block)
+        block = [escape2null(line) for line in block]
+        escaped = block[0]
+        blockindex = 0
+        while True:
+            targetmatch = pattern.match(escaped)
+            if targetmatch:
+                break
+            blockindex += 1
+            try:
+                escaped += block[blockindex]
+            except IndexError:
+                raise MarkupError('malformed hyperlink target.')
+        del block[:blockindex]
+        block[0] = (block[0] + ' ')[targetmatch.end()-len(escaped)-1:].strip()
+        target = self.make_target(block, blocktext, lineno,
+                                  targetmatch.group('name'))
+        return [target], blank_finish
+
+    def make_target(self, block, block_text, lineno, target_name):
+        target_type, data = self.parse_target(block, block_text, lineno)
+        if target_type == 'refname':
+            target = nodes.target(block_text, '', refname=normalize_name(data))
+            target.indirect_reference_name = data
+            self.add_target(target_name, '', target, lineno)
+            self.document.note_indirect_target(target)
+            return target
+        elif target_type == 'refuri':
+            target = nodes.target(block_text, '')
+            self.add_target(target_name, data, target, lineno)
+            return target
+        else:
+            return data
+
+    def parse_target(self, block, block_text, lineno):
+        """
+        Determine the type of reference of a target.
+
+        :Return: A 2-tuple, one of:
+
+            - 'refname' and the indirect reference name
+            - 'refuri' and the URI
+            - 'malformed' and a system_message node
+        """
+        if block and block[-1].strip()[-1:] == '_': # possible indirect target
+            reference = ' '.join([line.strip() for line in block])
+            refname = self.is_reference(reference)
+            if refname:
+                return 'refname', refname
+        reference = ''.join([''.join(line.split()) for line in block])
+        return 'refuri', unescape(reference)
+
+    def is_reference(self, reference):
+        match = self.explicit.patterns.reference.match(
+            whitespace_normalize_name(reference))
+        if not match:
+            return None
+        return unescape(match.group('simple') or match.group('phrase'))
+
+    def add_target(self, targetname, refuri, target, lineno):
+        target.line = lineno
+        if targetname:
+            name = normalize_name(unescape(targetname))
+            target['names'].append(name)
+            if refuri:
+                uri = self.inliner.adjust_uri(refuri)
+                if uri:
+                    target['refuri'] = uri
+                else:
+                    raise ApplicationError('problem with URI: %r' % refuri)
+            self.document.note_explicit_target(target, self.parent)
+        else:                       # anonymous target
+            if refuri:
+                target['refuri'] = refuri
+            target['anonymous'] = 1
+            self.document.note_anonymous_target(target)
+
+    def substitution_def(self, match):
+        pattern = self.explicit.patterns.substitution
+        src, srcline = self.state_machine.get_source_and_line()
+        block, indent, offset, blank_finish = \
+              self.state_machine.get_first_known_indented(match.end(),
+                                                          strip_indent=False)
+        blocktext = (match.string[:match.end()] + '\n'.join(block))
+        block.disconnect()
+        escaped = escape2null(block[0].rstrip())
+        blockindex = 0
+        while True:
+            subdefmatch = pattern.match(escaped)
+            if subdefmatch:
+                break
+            blockindex += 1
+            try:
+                escaped = escaped + ' ' + escape2null(block[blockindex].strip())
+            except IndexError:
+                raise MarkupError('malformed substitution definition.')
+        del block[:blockindex]          # strip out the substitution marker
+        block[0] = (block[0].strip() + ' ')[subdefmatch.end()-len(escaped)-1:-1]
+        if not block[0]:
+            del block[0]
+            offset += 1
+        while block and not block[-1].strip():
+            block.pop()
+        subname = subdefmatch.group('name')
+        substitution_node = nodes.substitution_definition(blocktext)
+        substitution_node.source = src
+        substitution_node.line = srcline
+        if not block:
+            msg = self.reporter.warning(
+                'Substitution definition "%s" missing contents.' % subname,
+                nodes.literal_block(blocktext, blocktext),
+                source=src, line=srcline)
+            return [msg], blank_finish
+        block[0] = block[0].strip()
+        substitution_node['names'].append(
+            nodes.whitespace_normalize_name(subname))
+        new_abs_offset, blank_finish = self.nested_list_parse(
+              block, input_offset=offset, node=substitution_node,
+              initial_state='SubstitutionDef', blank_finish=blank_finish)
+        i = 0
+        for node in substitution_node[:]:
+            if not (isinstance(node, nodes.Inline) or
+                    isinstance(node, nodes.Text)):