Release 0.4: tagging released revisiondocutils-0.4

git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.4@4268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 0 insertions, 4001 deletions

diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt
deleted file mode 100644
index 12874c5fb..000000000
--- a/docutils/docs/dev/rst/alternatives.txt
+++ /dev/null
@@ -1,3129 +0,0 @@
-==================================================
- A Record of reStructuredText Syntax Alternatives
-==================================================
-
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: This document has been placed in the public domain.
-
-The following are ideas, alternatives, and justifications that were
-considered for reStructuredText syntax, which did not originate with
-Setext_ or StructuredText_.  For an analysis of constructs which *did*
-originate with StructuredText or Setext, please see `Problems With
-StructuredText`_.  See the `reStructuredText Markup Specification`_
-for full details of the established syntax.
-
-The ideas are divided into sections:
-
-* Implemented_: already done.  The issues and alternatives are
-  recorded here for posterity.
-
-* `Not Implemented`_: these ideas won't be implemented.
-
-* Tabled_: these ideas should be revisited in the future.
-
-* `To Do`_: these ideas should be implemented.  They're just waiting
-  for a champion to resolve issues and get them done.
-
-* `... Or Not To Do?`_: possible but questionable.  These probably
-  won't be implemented, but you never know.
-
-.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
-.. _StructuredText:
-   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
-.. _Problems with StructuredText: problems.html
-.. _reStructuredText Markup Specification:
-   ../../ref/rst/restructuredtext.html
-
-
-.. contents::
-
--------------
- Implemented
--------------
-
-Field Lists
-===========
-
-Prior to the syntax for field lists being finalized, several
-alternatives were proposed.
-
-1. Unadorned RFC822_ everywhere::
-
-       Author: Me
-       Version: 1
-
-   Advantages: clean, precedent (RFC822-compliant).  Disadvantage:
-   ambiguous (these paragraphs are a prime example).
-
-   Conclusion: rejected.
-
-2. Special case: use unadorned RFC822_ for the very first or very last
-   text block of a document::
-
-       """
-       Author: Me
-       Version: 1
-
-       The rest of the document...
-       """
-
-   Advantages: clean, precedent (RFC822-compliant).  Disadvantages:
-   special case, flat (unnested) field lists only, still ambiguous::
-
-       """
-       Usage: cmdname [options] arg1 arg2 ...
-
-       We obviously *don't* want the like above to be interpreted as a
-       field list item.  Or do we?
-       """
-
-   Conclusion: rejected for the general case, accepted for specific
-   contexts (PEPs, email).
-
-3. Use a directive::
-
-       .. fields::
-
-          Author: Me
-          Version: 1
-
-   Advantages: explicit and unambiguous, RFC822-compliant.
-   Disadvantage: cumbersome.
-
-   Conclusion: rejected for the general case (but such a directive
-   could certainly be written).
-
-4. Use Javadoc-style::
-
-       @Author: Me
-       @Version: 1
-       @param a: integer
-
-   Advantages: unambiguous, precedent, flexible.  Disadvantages:
-   non-intuitive, ugly, not RFC822-compliant.
-
-   Conclusion: rejected.
-
-5. Use leading colons::
-
-       :Author: Me
-       :Version: 1
-
-   Advantages: unambiguous, obvious (*almost* RFC822-compliant),
-   flexible, perhaps even elegant.  Disadvantages: no precedent, not
-   quite RFC822-compliant.
-
-   Conclusion: accepted!
-
-6. Use double colons::
-
-       Author:: Me
-       Version:: 1
-
-   Advantages: unambiguous, obvious? (*almost* RFC822-compliant),
-   flexible, similar to syntax already used for literal blocks and
-   directives.  Disadvantages: no precedent, not quite
-   RFC822-compliant, similar to syntax already used for literal blocks
-   and directives.
-
-   Conclusion: rejected because of the syntax similarity & conflicts.
-
-Why is RFC822 compliance important?  It's a universal Internet
-standard, and super obvious.  Also, I'd like to support the PEP format
-(ulterior motive: get PEPs to use reStructuredText as their standard).
-But it *would* be easy to get used to an alternative (easy even to
-convert PEPs; probably harder to convert python-deviants ;-).
-
-Unfortunately, without well-defined context (such as in email headers:
-RFC822 only applies before any blank lines), the RFC822 format is
-ambiguous.  It is very common in ordinary text.  To implement field
-lists unambiguously, we need explicit syntax.
-
-The following question was posed in a footnote:
-
-   Should "bibliographic field lists" be defined at the parser level,
-   or at the DPS transformation level?  In other words, are they
-   reStructuredText-specific, or would they also be applicable to
-   another (many/every other?) syntax?
-
-The answer is that bibliographic fields are a
-reStructuredText-specific markup convention.  Other syntaxes may
-implement the bibliographic elements explicitly.  For example, there
-would be no need for such a transformation for an XML-based markup
-syntax.
-
-.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt
-
-
-Interpreted Text "Roles"
-========================
-
-The original purpose of interpreted text was as a mechanism for
-descriptive markup, to describe the nature or role of a word or
-phrase.  For example, in XML we could say "<function>len</function>"
-to mark up "len" as a function.  It is envisaged that within Python
-docstrings (inline documentation in Python module source files, the
-primary market for reStructuredText) the role of a piece of
-interpreted text can be inferred implicitly from the context of the
-docstring within the program source.  For other applications, however,
-the role may have to be indicated explicitly.
-
-Interpreted text is enclosed in single backquotes (`).
-
-1. Initially, it was proposed that an explicit role could be indicated
-   as a word or phrase within the enclosing backquotes:
-
-   - As a prefix, separated by a colon and whitespace::
-
-         `role: interpreted text`
-
-   - As a suffix, separated by whitespace and a colon::
-
-         `interpreted text :role`
-
-   There are problems with the initial approach:
-
-   - There could be ambiguity with interpreted text containing colons.
-     For example, an index entry of "Mission: Impossible" would
-     require a backslash-escaped colon.
-
-   - The explicit role is descriptive markup, not content, and will
-     not be visible in the processed output.  Putting it inside the
-     backquotes doesn't feel right; the *role* isn't being quoted.
-
-2. Tony Ibbs suggested that the role be placed outside the
-   backquotes::
-
-       role:`prefix` or `suffix`:role
-
-   This removes the embedded-colons ambiguity, but limits the role
-   identifier to be a single word (whitespace would be illegal).
-   Since roles are not meant to be visible after processing, the lack
-   of whitespace support is not important.
-
-   The suggested syntax remains ambiguous with respect to ratios and
-   some writing styles.  For example, suppose there is a "signal"
-   identifier, and we write::
-
-       ...calculate the `signal`:noise ratio.
-
-   "noise" looks like a role.
-
-3. As an improvement on #2, we can bracket the role with colons::
-
-       :role:`prefix` or `suffix`:role:
-
-   This syntax is similar to that of field lists, which is fine since
-   both are doing similar things: describing.
-
-   This is the syntax chosen for reStructuredText.
-
-4. Another alternative is two colons instead of one::
-
-       role::`prefix` or `suffix`::role
-
-   But this is used for analogies ("A:B::C:D": "A is to B as C is to
-   D").
-
-   Both alternative #2 and #4 lack delimiters on both sides of the
-   role, making it difficult to parse (by the reader).
-
-5. Some kind of bracketing could be used:
-
-   - Parentheses::
-
-         (role)`prefix` or `suffix`(role)
-
-   - Braces::
-
-         {role}`prefix` or `suffix`{role}
-
-   - Square brackets::
-
-         [role]`prefix` or `suffix`[role]
-
-   - Angle brackets::
-
-         <role>`prefix` or `suffix`<role>
-
-     (The overlap of \*ML tags with angle brackets would be too
-     confusing and precludes their use.)
-
-Syntax #3 was chosen for reStructuredText.
-
-
-Comments
-========
-
-A problem with comments (actually, with all indented constructs) is
-that they cannot be followed by an indented block -- a block quote --
-without swallowing it up.
-
-I thought that perhaps comments should be one-liners only.  But would
-this mean that footnotes, hyperlink targets, and directives must then
-also be one-liners?  Not a good solution.
-
-Tony Ibbs suggested a "comment" directive.  I added that we could
-limit a comment to a single text block, and that a "multi-block
-comment" could use "comment-start" and "comment-end" directives.  This
-would remove the indentation incompatibility.  A "comment" directive
-automatically suggests "footnote" and (hyperlink) "target" directives
-as well.  This could go on forever!  Bad choice.
-
-Garth Kidd suggested that an "empty comment", a ".." explicit markup
-start with nothing on the first line (except possibly whitespace) and
-a blank line immediately following, could serve as an "unindent".  An
-empty comment does **not** swallow up indented blocks following it,
-so block quotes are safe.  "A tiny but practical wart."  Accepted.
-
-
-Anonymous Hyperlinks
-====================
-
-Alan Jaffray came up with this idea, along with the following syntax::
-
-    Search the `Python DOC-SIG mailing list archives`{}_.
-
-    .. _: http://mail.python.org/pipermail/doc-sig/
-
-The idea is sound and useful.  I suggested a "double underscore"
-syntax::
-
-    Search the `Python DOC-SIG mailing list archives`__.
-
-    .. __: http://mail.python.org/pipermail/doc-sig/
-
-But perhaps single underscores are okay?  The syntax looks better, but
-the hyperlink itself doesn't explicitly say "anonymous"::
-
-    Search the `Python DOC-SIG mailing list archives`_.
-
-    .. _: http://mail.python.org/pipermail/doc-sig/
-
-Mixing anonymous and named hyperlinks becomes confusing.  The order of
-targets is not significant for named hyperlinks, but it is for
-anonymous hyperlinks::
-
-    Hyperlinks: anonymous_, named_, and another anonymous_.
-
-    .. _named: named
-    .. _: anonymous1
-    .. _: anonymous2
-
-Without the extra syntax of double underscores, determining which
-hyperlink references are anonymous may be difficult.  We'd have to
-check which references don't have corresponding targets, and match
-those up with anonymous targets.  Keeping to a simple consistent
-ordering (as with auto-numbered footnotes) seems simplest.
-
-reStructuredText will use the explicit double-underscore syntax for
-anonymous hyperlinks.  An alternative (see `Reworking Explicit Markup
-(Round 1)`_ below) for the somewhat awkward ".. __:" syntax is "__"::
-
-    An anonymous__ reference.
-
-    __ http://anonymous
-
-
-Reworking Explicit Markup (Round 1)
-===================================
-
-Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added
-to reStructuredText.  Subsequently it was asserted that hyperlinks
-(especially anonymous hyperlinks) would play an increasingly important
-role in reStructuredText documents, and therefore they require a
-simpler and more concise syntax.  This prompted a review of the
-current and proposed explicit markup syntaxes with regards to
-improving usability.
-
-1. Original syntax::
-
-       .. _blah:                     internal hyperlink target
-       .. _blah: http://somewhere    external hyperlink target
-       .. _blah: blahblah_           indirect hyperlink target
-       .. __:                        anonymous internal target
-       .. __: http://somewhere       anonymous external target
-       .. __: blahblah_              anonymous indirect target
-       .. [blah] http://somewhere    footnote
-       .. blah:: http://somewhere    directive
-       .. blah: http://somewhere     comment
-
-   .. Note::
-
-      The comment text was intentionally made to look like a hyperlink
-      target.
-
-   Origins:
-
-   * Except for the colon (a delimiter necessary to allow for
-     phrase-links), hyperlink target ``.. _blah:`` comes from Setext.
-   * Comment syntax from Setext.
-   * Footnote syntax from StructuredText ("named links").
-   * Directives and anonymous hyperlinks original to reStructuredText.
-
-   Advantages:
-
-   + Consistent explicit markup indicator: "..".
-   + Consistent hyperlink syntax: ".. _" & ":".
-
-   Disadvantages:
-
-   - Anonymous target markup is awkward: ".. __:".
-   - The explicit markup indicator ("..") is excessively overloaded?
-   - Comment text is limited (can't look like a footnote, hyperlink,
-     or directive).  But this is probably not important.
-
-2. Alan Jaffray's proposed syntax #1::
-
-       __ _blah                      internal hyperlink target
-       __ blah: http://somewhere     external hyperlink target
-       __ blah: blahblah_            indirect hyperlink target
-       __                            anonymous internal target
-       __ http://somewhere           anonymous external target
-       __ blahblah_                  anonymous indirect target
-       __ [blah] http://somewhere    footnote
-       .. blah:: http://somewhere    directive
-       .. blah: http://somewhere     comment
-
-   The hyperlink-connoted underscores have become first-level syntax.
-
-   Advantages:
-
-   + Anonymous targets are simpler.
-   + All hyperlink targets are one character shorter.
-
-   Disadvantages:
-
-   - Inconsistent internal hyperlink targets.  Unlike all other named
-     hyperlink targets, there's no colon.  There's an extra leading
-     underscore, but we can't drop it because without it, "blah" looks
-     like a relative URI.  Unless we restore the colon::
-
-         __ blah:                      internal hyperlink target
-
-   - Obtrusive markup?
-
-3. Alan Jaffray's proposed syntax #2::
-
-       .. _blah                      internal hyperlink target
-       .. blah: http://somewhere     external hyperlink target
-       .. blah: blahblah_            indirect hyperlink target
-       ..                            anonymous internal target
-       .. http://somewhere           anonymous external target
-       .. blahblah_                  anonymous indirect target
-       .. [blah] http://somewhere    footnote
-       !! blah: http://somewhere     directive
-       ## blah: http://somewhere     comment
-
-   Leading underscores have been (almost) replaced by "..", while
-   comments and directives have gained their own syntax.
-
-   Advantages:
-
-   + Anonymous hyperlinks are simpler.
-   + Unique syntax for comments.  Connotation of "comment" from
-     some programming languages (including our favorite).
-   + Unique syntax for directives.  Connotation of "action!".
-
-   Disadvantages:
-
-   - Inconsistent internal hyperlink targets.  Again, unlike all other
-     named hyperlink targets, there's no colon.  There's a leading
-     underscore, matching the trailing underscores of references,
-     which no other hyperlink targets have.  We can't drop that one
-     leading underscore though: without it, "blah" looks like a
-     relative URI.  Again, unless we restore the colon::
-
-         .. blah:                      internal hyperlink target
-
-   - All (except for internal) hyperlink targets lack their leading
-     underscores, losing the "hyperlink" connotation.
-
-   - Obtrusive syntax for comments.  Alternatives::
-
-         ;; blah: http://somewhere
-            (also comment syntax in Lisp & others)
-         ,, blah: http://somewhere
-            ("comma comma": sounds like "comment"!)
-
-   - Iffy syntax for directives.  Alternatives?
-
-4. Tony Ibbs' proposed syntax::
-
-       .. _blah:                     internal hyperlink target
-       .. _blah: http://somewhere    external hyperlink target
-       .. _blah: blahblah_           indirect hyperlink target
-       ..                            anonymous internal target
-       .. http://somewhere           anonymous external target
-       .. blahblah_                  anonymous indirect target
-       .. [blah] http://somewhere    footnote
-       .. blah:: http://somewhere    directive
-       .. blah: http://somewhere     comment
-
-   This is the same as the current syntax, except for anonymous
-   targets which drop their "__: ".
-
-   Advantage:
-
-   + Anonymous targets are simpler.
-
-   Disadvantages:
-
-   - Anonymous targets lack their leading underscores, losing the
-     "hyperlink" connotation.
-   - Anonymous targets are almost indistinguishable from comments.
-     (Better to know "up front".)
-
-5. David Goodger's proposed syntax: Perhaps going back to one of
-   Alan's earlier suggestions might be the best solution.  How about
-   simply adding "__ " as a synonym for ".. __: " in the original
-   syntax?  These would become equivalent::
-
-       .. __:                        anonymous internal target
-       .. __: http://somewhere       anonymous external target
-       .. __: blahblah_              anonymous indirect target
-
-       __                            anonymous internal target
-       __ http://somewhere           anonymous external target
-       __ blahblah_                  anonymous indirect target
-
-Alternative 5 has been adopted.
-
-
-Backquotes in Phrase-Links
-==========================
-
-[From a 2001-06-05 Doc-SIG post in reply to questions from Doug
-Hellmann.]
-
-The first draft of the spec, posted to the Doc-SIG in November 2000,
-used square brackets for phrase-links.  I changed my mind because:
-
-1. In the first draft, I had already decided on single-backquotes for
-   inline literal text.
-
-2. However, I wanted to minimize the necessity for backslash escapes,
-   for example when quoting Python repr-equivalent syntax that uses
-   backquotes.
-
-3. The processing of identifiers (function/method/attribute/module
-   etc. names) into hyperlinks is a useful feature.  PyDoc recognizes
-   identifiers heuristically, but it doesn't take much imagination to
-   come up with counter-examples where PyDoc's heuristics would result
-   in embarassing failure.  I wanted to do it deterministically, and
-   that called for syntax.  I called this construct "interpreted
-   text".
-
-4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the
-   idea of using double-backquotes as syntax.
-
-5. I worked out some rules for inline markup recognition.
-
-6. In combination with #5, double backquotes lent themselves to inline
-   literals, neatly satisfying #2, minimizing backslash escapes.  In
-   fact, the spec says that no interpretation of any kind is done
-   within double-backquote inline literal text; backslashes do *no*
-   escaping within literal text.
-
-7. Single backquotes are then freed up for interpreted text.
-
-8. I already had square brackets required for footnote references.
-
-9. Since interpreted text will typically turn into hyperlinks, it was
-   a natural fit to use backquotes as the phrase-quoting syntax for
-   trailing-underscore hyperlinks.
-
-The original inspiration for the trailing underscore hyperlink syntax
-was Setext.  But for phrases Setext used a very cumbersome
-``underscores_between_words_like_this_`` syntax.
-
-The underscores can be viewed as if they were right-pointing arrows:
-``-->``.  So ``hyperlink_`` points away from the reference, and
-``.. _hyperlink:`` points toward the target.
-
-
-Substitution Mechanism
-======================
-
-Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by
-Alan Jaffray, "reStructuredText inline markup".  It reminded me of a
-missing piece of the reStructuredText puzzle, first referred to in my
-contribution to "Documentation markup & processing / PEPs" (Doc-SIG
-2001-06-21).
-
-Substitutions allow the power and flexibility of directives to be
-shared by inline text.  They are a way to allow arbitrarily complex
-inline objects, while keeping the details out of the flow of text.
-They are the equivalent of SGML/XML's named entities.  For example, an
-inline image (using reference syntax alternative 4d (vertical bars)
-and definition alternative 3, the alternatives chosen for inclusion in
-the spec)::
-
-    The |biohazard| symbol must be used on containers used to dispose
-    of medical waste.
-
-    .. |biohazard| image:: biohazard.png
-       [height=20 width=20]
-
-The ``|biohazard|`` substitution reference will be replaced in-line by
-whatever the ``.. |biohazard|`` substitution definition generates (in
-this case, an image).  A substitution definition contains the
-substitution text bracketed with vertical bars, followed by a an
-embedded inline-compatible directive, such as "image".  A transform is
-required to complete the substitution.
-
-Syntax alternatives for the reference:
-
-1. Use the existing interpreted text syntax, with a predefined role
-   such as "sub"::
-
-       The `biohazard`:sub: symbol...
-
-   Advantages: existing syntax, explicit.  Disadvantages: verbose,
-   obtrusive.
-
-2. Use a variant of the interpreted text syntax, with a new suffix
-   akin to the underscore in phrase-link references::
-
-       (a) `name`@
-       (b) `name`#
-       (c) `name`&
-       (d) `name`/
-       (e) `name`<
-       (f) `name`::
-       (g) `name`:
-
-
-   Due to incompatibility with other constructs and ordinary text
-   usage, (f) and (g) are not possible.
-
-3. Use interpreted text syntax with a fixed internal format::
-
-       (a) `:name:`
-       (b) `name:`
-       (c) `name::`
-       (d) `::name::`
-       (e) `%name%`
-       (f) `#name#`
-       (g) `/name/`
-       (h) `&name&`
-       (i) `|name|`
-       (j) `[name]`
-       (k) `<name>`
-       (l) `&name;`
-       (m) `'name'`
-
-   To avoid ML confusion (k) and (l) are definitely out.  Square
-   brackets (j) won't work in the target (the substitution definition
-   would be indistinguishable from a footnote).
-
-   The ```/name/``` syntax (g) is reminiscent of "s/find/sub"
-   substitution syntax in ed-like languages.  However, it may have a
-   misleading association with regexps, and looks like an absolute
-   POSIX path.  (i) is visually equivalent and lacking the
-   connotations.
-
-   A disadvantage of all of these is that they limit interpreted text,
-   albeit only slightly.
-
-4. Use specialized syntax, something new::
-
-       (a) #name#
-       (b) @name@
-       (c) /name/
-       (d) |name|
-       (e) <<name>>
-       (f) //name//
-       (g) ||name||
-       (h) ^name^
-       (i) [[name]]
-       (j) ~name~
-       (k) !name!
-       (l) =name=
-       (m) ?name?
-       (n) >name<
-
-   "#" (a) and "@" (b) are obtrusive.  "/" (c) without backquotes
-   looks just like a POSIX path; it is likely for such usage to appear
-   in text.
-
-   "|" (d) and "^" (h) are feasible.
-
-5. Redefine the trailing underscore syntax.  See definition syntax
-   alternative 4, below.
-
-Syntax alternatives for the definition:
-
-1. Use the existing directive syntax, with a predefined directive such
-   as "sub".  It contains a further embedded directive resolving to an
-   inline-compatible object::
-
-       .. sub:: biohazard
-          .. image:: biohazard.png
-             [height=20 width=20]
-
-       .. sub:: parrot
-          That bird wouldn't *voom* if you put 10,000,000 volts
-          through it!
-
-   The advantages and disadvantages are the same as in inline
-   alternative 1.
-
-2. Use syntax as in #1, but with an embedded directivecompressed::
-
-       .. sub:: biohazard image:: biohazard.png
-          [height=20 width=20]
-
-   This is a bit better than alternative 1, but still too much.
-
-3. Use a variant of directive syntax, incorporating the substitution
-   text, obviating the need for a special "sub" directive name.  If we
-   assume reference alternative 4d (vertical bars), the matching
-   definition would look like this::
-
-       .. |biohazard| image:: biohazard.png
-          [height=20 width=20]
-
-4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.)
-
-   Instead of adding new syntax, redefine the trailing underscore
-   syntax to mean "substitution reference" instead of "hyperlink
-   reference".  Alan's example::
-
-       I had lunch with Jonathan_ today.  We talked about Zope_.
-
-       .. _Jonathan: lj [user=jhl]
-       .. _Zope: http://www.zope.org/
-
-   A problem with the proposed syntax is that URIs which look like
-   simple reference names (alphanum plus ".", "-", "_") would be
-   indistinguishable from substitution directive names.  A more
-   consistent syntax would be::
-
-       I had lunch with Jonathan_ today.  We talked about Zope_.
-
-       .. _Jonathan: lj:: user=jhl
-       .. _Zope: http://www.zope.org/
-
-   (``::`` after ``.. _Jonathan: lj``.)
-
-   The "Zope" target is a simple external hyperlink, but the
-   "Jonathan" target contains a directive.  Alan proposed is that the
-   reference text be replaced by whatever the referenced directive
-   (the "directive target") produces.  A directive reference becomes a
-   hyperlink reference if the contents of the directive target resolve
-   to a hyperlink.  If the directive target resolves to an icon, the
-   reference is replaced by an inline icon.  If the directive target
-   resolves to a hyperlink, the directive reference becomes a
-   hyperlink reference.
-
-   This seems too indirect and complicated for easy comprehension.
-
-   The reference in the text will sometimes become a link, sometimes
-   not.  Sometimes the reference text will remain, sometimes not.  We
-   don't know *at the reference*::
-
-       This is a `hyperlink reference`_; its text will remain.
-       This is an `inline icon`_; its text will disappear.
-
-   That's a problem.
-
-The syntax that has been incorporated into the spec and parser is
-reference alternative 4d with definition alternative 3::
-
-    The |biohazard| symbol...
-
-    .. |biohazard| image:: biohazard.png
-       [height=20 width=20]
-
-We can also combine substitution references with hyperlink references,
-by appending a "_" (named hyperlink reference) or "__" (anonymous
-hyperlink reference) suffix to the substitution reference.  This
-allows us to click on an image-link::
-
-    The |biohazard|_ symbol...
-
-    .. |biohazard| image:: biohazard.png
-       [height=20 width=20]
-    .. _biohazard: http://www.cdc.gov/
-
-There have been several suggestions for the naming of these
-constructs, originally called "substitution references" and
-"substitutions".
-
-1. Candidate names for the reference construct:
-
-   (a) substitution reference
-   (b) tagging reference
-   (c) inline directive reference
-   (d) directive reference
-   (e) indirect inline directive reference
-   (f) inline directive placeholder
-   (g) inline directive insertion reference
-   (h) directive insertion reference
-   (i) insertion reference
-   (j) directive macro reference
-   (k) macro reference
-   (l) substitution directive reference
-
-2. Candidate names for the definition construct:
-
-   (a) substitution
-   (b) substitution directive
-   (c) tag
-   (d) tagged directive
-   (e) directive target
-   (f) inline directive
-   (g) inline directive definition
-   (h) referenced directive
-   (i) indirect directive
-   (j) indirect directive definition
-   (k) directive definition
-   (l) indirect inline directive
-   (m) named directive definition
-   (n) inline directive insertion definition
-   (o) directive insertion definition
-   (p) insertion definition
-   (q) insertion directive
-   (r) substitution definition
-   (s) directive macro definition
-   (t) macro definition
-   (u) substitution directive definition
-   (v) substitution definition
-
-"Inline directive reference" (1c) seems to be an appropriate term at
-first, but the term "inline" is redundant in the case of the
-reference.  Its counterpart "inline directive definition" (2g) is
-awkward, because the directive definition itself is not inline.
-
-"Directive reference" (1d) and "directive definition" (2k) are too
-vague.  "Directive definition" could be used to refer to any
-directive, not just those used for inline substitutions.
-
-One meaning of the term "macro" (1k, 2s, 2t) is too
-programming-language-specific.  Also, macros are typically simple text
-substitution mechanisms: the text is substituted first and evaluated
-later.  reStructuredText substitution definitions are evaluated in
-place at parse time and substituted afterwards.
-
-"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that
-something new is getting added rather than one construct being
-replaced by another.
-
-Which brings us back to "substitution".  The overall best names are
-"substitution reference" (1a) and "substitution definition" (2v).  A
-long way to go to add one word!
-
-
-Inline External Targets
-=======================
-
-Currently reStructuredText has two hyperlink syntax variations:
-
-* Named hyperlinks::
-
-      This is a named reference_ of one word ("reference").  Here is
-      a `phrase reference`_.  Phrase references may even cross `line
-      boundaries`_.
-
-      .. _reference: http://www.example.org/reference/
-      .. _phrase reference: http://www.example.org/phrase_reference/
-      .. _line boundaries: http://www.example.org/line_boundaries/
-
-  + Advantages:
-
-    - The plaintext is readable.
-    - Each target may be reused multiple times (e.g., just write
-      ``"reference_"`` again).
-    - No syncronized ordering of references and targets is necessary.
-
-  + Disadvantages:
-
-    - The reference text must be repeated as target names; could lead
-      to mistakes.
-    - The target URLs may be located far from the references, and hard
-      to find in the plaintext.
-
-* Anonymous hyperlinks (in current reStructuredText)::
-
-      This is an anonymous reference__.  Here is an anonymous
-      `phrase reference`__.  Phrase references may even cross `line
-      boundaries`__.
-
-      __ http://www.example.org/reference/
-      __ http://www.example.org/phrase_reference/
-      __ http://www.example.org/line_boundaries/
-
-  + Advantages:
-
-    - The plaintext is readable.
-    - The reference text does not have to be repeated.
-
-  + Disadvantages:
-
-    - References and targets must be kept in sync.
-    - Targets cannot be reused.
-    - The target URLs may be located far from the references.
-
-For comparison and historical background, StructuredText also has two
-syntaxes for hyperlinks:
-
-* First, ``"reference text":URL``::
-
-      This is a "reference":http://www.example.org/reference/
-      of one word ("reference").  Here is a "phrase
-      reference":http://www.example.org/phrase_reference/.
-
-* Second, ``"reference text", http://example.com/absolute_URL``::
-
-      This is a "reference", http://www.example.org/reference/
-      of one word ("reference").  Here is a "phrase reference",
-      http://www.example.org/phrase_reference/.
-
-Both syntaxes share advantages and disadvantages:
-
-+ Advantages:
-
-  - The target is specified immediately adjacent to the reference.
-
-+ Disadvantages:
-
-  - Poor plaintext readability.
-  - Targets cannot be reused.
-  - Both syntaxes use double quotes, common in ordinary text.
-  - In the first syntax, the URL and the last word are stuck
-    together, exacerbating the line wrap problem.
-  - The second syntax is too magical; text could easily be written
-    that way by accident (although only absolute URLs are recognized
-    here, perhaps because of the potential for ambiguity).
-
-A new type of "inline external hyperlink" has been proposed.
-
-1. On 2002-06-28, Simon Budig proposed__ a new syntax for
-   reStructuredText hyperlinks::
-
-       This is a reference_(http://www.example.org/reference/) of one
-       word ("reference").  Here is a `phrase
-       reference`_(http://www.example.org/phrase_reference/).  Are
-       these examples, (single-underscore), named?  If so, `anonymous
-       references`__(http://www.example.org/anonymous/) using two
-       underscores would probably be preferable.
-
-   __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html
-
-   The syntax, advantages, and disadvantages are similar to those of
-   StructuredText.
-
-   + Advantages:
-
-     - The target is specified immediately adjacent to the reference.
-
-   + Disadvantages:
-
-     - Poor plaintext readability.
-     - Targets cannot be reused (unless named, but the semantics are
-       unclear).
-
-   + Problems:
-
-     - The ``"`ref`_(URL)"`` syntax forces the last word of the
-       reference text to be joined to the URL, making a potentially
-       very long word that can't be wrapped (URLs can be very long).
-       The reference and the URL should be separate.  This is a
-       symptom of the following point:
-
-     - The syntax produces a single compound construct made up of two
-       equally important parts, *with syntax in the middle*, *between*
-       the reference and the target.  This is unprecedented in
-       reStructuredText.
-
-     - The "inline hyperlink" text is *not* a named reference (there's
-       no lookup by name), so it shouldn't look like one.
-
-     - According to the IETF standards RFC 2396 and RFC 2732,
-       parentheses are legal URI characters and curly braces are legal
-       email characters, making their use prohibitively difficult.
-
-     - The named/anonymous semantics are unclear.
-
-2. After an analysis__ of the syntax of (1) above, we came up with the
-   following compromise syntax::
-
-       This is an anonymous reference__
-       __<http://www.example.org/reference/> of one word
-       ("reference").  Here is a `phrase reference`__
-       __<http://www.example.org/phrase_reference/>.  `Named
-       references`_ _<http://www.example.org/anonymous/> use single
-       underscores.
-
-   __ http://mail.python.org/pipermail/doc-sig/2002-July/002670.html
-
-   The syntax builds on that of the existing "inline internal
-   targets": ``an _`inline internal target`.``
-
-   + Advantages:
-
-     - The target is specified immediately adjacent to the reference,
-       improving maintainability:
-
-       - References and targets are easily kept in sync.
-       - The reference text does not have to be repeated.
-
-     - The construct is executed in two parts: references identical to
-       existing references, and targets that are new but not too big a
-       stretch from current syntax.
-
-     - There's overwhelming precedent for quoting URLs with angle
-       brackets [#]_.
-
-   + Disadvantages:
-
-     - Poor plaintext readability.
-     - Lots of "line noise".
-     - Targets cannot be reused (unless named; see below).
-
-   To alleviate the readability issue slightly, we could allow the
-   target to appear later, such as after the end of the sentence::
-
-       This is a named reference__ of one word ("reference").
-       __<http://www.example.org/reference/>  Here is a `phrase
-       reference`__.  __<http://www.example.org/phrase_reference/>
-
-   Problem: this could only work for one reference at a time
-   (reference/target pairs must be proximate [refA trgA refB trgB],
-   not interleaved [refA refB trgA trgB] or nested [refA refB trgB
-   trgA]).  This variation is too problematic; references and inline
-   external targets will have to be kept imediately adjacent (see (3)
-   below).
-
-   The ``"reference__ __<target>"`` syntax is actually for "anonymous
-   inline external targets", emphasized by the double underscores.  It
-   follows that single trailing and leading underscores would lead to
-   *implicitly named* inline external targets.  This would allow the
-   reuse of targets by name.  So after ``"reference_ _<target>"``,
-   another ``"reference_"`` would point to the same target.
-
-   .. [#]
-      From RFC 2396 (URI syntax):
-
-          The angle-bracket "<" and ">" and double-quote (")
-          characters are excluded [from URIs] because they are often
-          used as the delimiters around URI in text documents and
-          protocol fields.
-
-          Using <> angle brackets around each URI is especially
-          recommended as a delimiting style for URI that contain
-          whitespace.
-
-      From RFC 822 (email headers):
-
-          Angle brackets ("<" and ">") are generally used to indicate
-          the presence of a one machine-usable reference (e.g.,
-          delimiting mailboxes), possibly including source-routing to
-          the machine.
-
-3. If it is best for references and inline external targets to be
-   immediately adjacent, then they might as well be integrated.
-   Here's an alternative syntax embedding the target URL in the
-   reference::
-
-       This is an anonymous `reference <http://www.example.org
-       /reference/>`__ of one word ("reference").  Here is a `phrase
-       reference <http://www.example.org/phrase_reference/>`__.
-
-   Advantages and disadvantages are similar to those in (2).
-   Readability is still an issue, but the syntax is a bit less
-   heavyweight (reduced line noise).  Backquotes are required, even
-   for one-word references; the target URL is included within the
-   reference text, forcing a phrase context.
-
-   We'll call this variant "embedded URIs".
-
-   Problem: how to refer to a title like "HTML Anchors: <a>" (which
-   ends with an HTML/SGML/XML tag)?  We could either require more
-   syntax on the target (like ``"`reference text
-   __<http://example.com/>`__"``), or require the odd conflicting
-   title to be escaped (like ``"`HTML Anchors: \<a>`__"``).  The
-   latter seems preferable, and not too onerous.
-
-   Similarly to (2) above, a single trailing underscore would convert
-   the reference & inline external target from anonymous to implicitly
-   named, allowing reuse of targets by name.
-
-   I think this is the least objectionable of the syntax alternatives.
-
-Other syntax variations have been proposed (by Brett Cannon and Benja
-Fallenstein)::
-
-    `phrase reference`->http://www.example.com
-
-    `phrase reference`@http://www.example.com
-
-    `phrase reference`__ ->http://www.example.com
-
-    `phrase reference` [-> http://www.example.com]
-
-    `phrase reference`__ [-> http://www.example.com]
-
-    `phrase reference` <http://www.example.com>_
-
-None of these variations are clearly superior to #3 above.  Some have
-problems that exclude their use.
-
-With any kind of inline external target syntax it comes down to the
-conflict between maintainability and plaintext readability.  I don't
-see a major problem with reStructuredText's maintainability, and I
-don't want to sacrifice plaintext readability to "improve" it.
-
-The proponents of inline external targets want them for easily
-maintainable web pages.  The arguments go something like this:
-
-- Named hyperlinks are difficult to maintain because the reference
-  text is duplicated as the target name.
-
-  To which I said, "So use anonymous hyperlinks."
-
-- Anonymous hyperlinks are difficult to maintain becuase the
-  references and targets have to be kept in sync.
-
-  "So keep the targets close to the references, grouped after each
-  paragraph.  Maintenance is trivial."
-
-- But targets grouped after paragraphs break the flow of text.
-
-  "Surely less than URLs embedded in the text!  And if the intent is
-  to produce web pages, not readable plaintext, then who cares about
-  the flow of text?"
-
-Many participants have voiced their objections to the proposed syntax:
-
-    Garth Kidd: "I strongly prefer the current way of doing it.
-    Inline is spectactularly messy, IMHO."
-
-    Tony Ibbs: "I vehemently agree... that the inline alternatives
-    being suggested look messy - there are/were good reasons they've
-    been taken out...  I don't believe I would gain from the new
-    syntaxes."
-
-    Paul Moore: "I agree as well.  The proposed syntax is far too
-    punctuation-heavy, and any of the alternatives discussed are
-    ambiguous or too subtle."
-
-Others have voiced their support:
-
-    fantasai: "I agree with Simon.  In many cases, though certainly
-    not in all, I find parenthesizing the url in plain text flows
-    better than relegating it to a footnote."
-
-    Ken Manheimer: "I'd like to weigh in requesting some kind of easy,
-    direct inline reference link."
-
-(Interesting that those *against* the proposal have been using
-reStructuredText for a while, and those *for* the proposal are either
-new to the list ["fantasai", background unknown] or longtime
-StructuredText users [Ken Manheimer].)
-
-I was initially ambivalent/against the proposed "inline external
-targets".  I value reStructuredText's readability very highly, and
-although the proposed syntax offers convenience, I don't know if the
-convenience is worth the cost in ugliness.  Does the proposed syntax
-compromise readability too much, or should the choice be left up to
-the author?  Perhaps if the syntax is *allowed* but its use strongly
-*discouraged*, for aesthetic/readability reasons?
-
-After a great deal of thought and much input from users, I've decided
-that there are reasonable use cases for this construct.  The
-documentation should strongly caution against its use in most
-situations, recommending independent block-level targets instead.
-Syntax #3 above ("embedded URIs") will be used.
-
-
-Doctree Representation of Transitions
-=====================================
-
-(Although not reStructuredText-specific, this section fits best in
-this document.)
-
-Having added the "horizontal rule" construct to the `reStructuredText
-Markup Specification`_, a decision had to be made as to how to reflect
-the construct in the implementation of the document tree.  Given this
-source::
-
-    Document
-    ========
-
-    Paragraph 1
-
-    --------
-
-    Paragraph 2
-
-The horizontal rule indicates a "transition" (in prose terms) or the
-start of a new "division".  Before implementation, the parsed document
-tree would be::
-
-    <document>
-        <section names="document">
-            <title>
-                Document
-            <paragraph>
-                Paragraph 1
-            --------               <--- error here
-            <paragraph>
-                Paragraph 2
-
-There are several possibilities for the implementation:
-
-1. Implement horizontal rules as "divisions" or segments.  A
-   "division" is a title-less, non-hierarchical section.  The first
-   try at an implementation looked like this::
-
-       <document>
-           <section names="document">
-               <title>
-                   Document
-               <paragraph>
-                   Paragraph 1
-               <division>
-                   <paragraph>
-                       Paragraph 2
-
-   But the two paragraphs are really at the same level; they shouldn't
-   appear to be at different levels.  There's really an invisible
-   "first division".  The horizontal rule splits the document body
-   into two segments, which should be treated uniformly.
-
-2. Treating "divisions" uniformly brings us to the second
-   possibility::
-
-       <document>
-           <section names="document">
-               <title>
-                   Document
-               <division>
-                   <paragraph>
-                       Paragraph 1
-               <division>
-                   <paragraph>
-                       Paragraph 2
-
-   With this change, documents and sections will directly contain
-   divisions and sections, but not body elements.  Only divisions will
-   directly contain body elements.  Even without a horizontal rule
-   anywhere, the body elements of a document or section would be
-   contained within a division element.  This makes the document tree
-   deeper.  This is similar to the way HTML_ treats document contents:
-   grouped within a ``<body>`` element.
-
-3. Implement them as "transitions", empty elements::
-
-       <document>
-           <section names="document">
-               <title>
-                   Document
-               <paragraph>
-                   Paragraph 1
-               <transition>
-               <paragraph>
-                   Paragraph 2
-
-   A transition would be a "point element", not containing anything,
-   only identifying a point within the document structure.  This keeps
-   the document tree flatter, but the idea of a "point element" like
-   "transition" smells bad.  A transition isn't a thing itself, it's
-   the space between two divisions.  However, transitions are a
-   practical solution.
-
-Solution 3 was chosen for incorporation into the document tree model.
-
-.. _HTML: http://www.w3.org/MarkUp/
-
-
-Syntax for Line Blocks
-======================
-
-* An early idea: How about a literal-block-like prefix, perhaps
-  "``;;``"?  (It is, after all, a *semi-literal* literal block, no?)
-  Example::
-
-      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...
-
-  Kinda lame.
-
-* Another idea: in an ordinary paragraph, if the first line ends with
-  a backslash (escaping the newline), interpret the entire paragraph
-  as a verse block?  For example::
-
-      Add just one backslash\
-      And this paragraph becomes
-      An awful haiku
-
-  (Awful, and arguably invalid, since in Japanese the word "haiku"
-  contains three syllables not two.)
-
-  This idea was superceded by the rules for escaped whitespace, useful
-  for `character-level inline markup`_.
-
-* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed
-  a "plain list" syntax (and also provided a patch)::
-
-       | John Doe
-       | President, SuperDuper Corp.
-       | jdoe@example.org
-
-  __ http://thread.gmane.org/gmane.text.docutils.devel/1187
-
-  This syntax is very natural.  However, these "plain lists" seem very
-  similar to line blocks, and I see so little intrinsic "list-ness"
-  that I'm loathe to add a new object.  I used the term "blurbs" to
-  remove the "list" connotation from the originally proposed name.
-  Perhaps line blocks could be refined to add the two properties they
-  currently lack:
-
-  A) long lines wrap nicely
-  B) HTML output doesn't look like program code in non-CSS web
-     browsers
-
-  (A) is an issue of all 3 aspects of Docutils: syntax (construct
-  behaviour), internal representation, and output.  (B) is partly an
-  issue of internal representation but mostly of output.
-
-ReStructuredText will redefine line blocks with the "|"-quoting
-syntax.  The following is my current thinking.
-
-
-Syntax
-------
-
-Perhaps line block syntax like this would do::
-
-     | M6: James Bond
-     | MIB: Mr. J.
-     | IMF: not decided yet, but probably one of the following:
-     |   Ethan Hunt
-     |   Jim Phelps
-     |   Claire Phelps
-     | CIA: Felix Leiter
-
-Note that the "nested" list does not have nested syntax (the "|" are
-not further indented); the leading whitespace would still be
-significant somehow (more below).  As for long lines in the input,
-this could suffice::
-
-     | John Doe
-     | Founder, President, Chief Executive Officer, Cook, Bottle
-       Washer, and All-Round Great Guy
-     | SuperDuper Corp.
-     | jdoe@example.org
-
-The lack of "|" on the third line indicates that it's a continuation
-of the second line, wrapped.
-
-I don't see much point in allowing arbitrary nested content.  Multiple
-paragraphs or bullet lists inside a "blurb" doesn't make sense to me.
-Simple nested line blocks should suffice.
-
-
-Internal Representation
------------------------
-
-Line blocks are currently represented as text blobs as follows::
-
-     <!ELEMENT line_block %text.model;>
-     <!ATTLIST line_block
-         %basic.atts;
-         %fixedspace.att;>
-
-Instead, we could represent each line by a separate element::
-
-     <!ELEMENT line_block (line+)>
-     <!ATTLIST line_block %basic.atts;>
-
-     <!ELEMENT line %text.model;>
-     <!ATTLIST line %basic.atts;>
-
-We'd keep the significance of the leading whitespace of each line
-either by converting it to non-breaking spaces at output, or with a
-per-line margin.  Non-breaking spaces are simpler (for HTML, anyway)
-but kludgey, and wouldn't support indented long lines that wrap.  But
-should inter-word whitespace (i.e., not leading whitespace) be
-preserved?  Currently it is preserved in line blocks.
-
-Representing a more complex line block may be tricky::
-
-     | 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?
-
-Perhaps the representation could allow for nested line blocks::
-
-     <!ELEMENT line_block (line | line_block)+>
-
-With this model, leading whitespace would no longer be significant.
-Instead, left margins are implied by the nesting.  The example above
-could be represented as follows::
-
-     <line_block>
-         <line>
-             But can a bee be said to be
-         <line_block>
-             <line>
-                  or not to be an entire bee,
-             <line_block>
-                 <line>
-                     when half the bee is not a bee,
-                 <line_block>
-                     <line>
-                         due to some ancient injury?
-
-I wasn't sure what to do about even more complex line blocks::
-
-     |     Indented
-     | Not indented
-     |   Indented a bit
-     |     A bit more
-     |  Only one space
-
-How should that be parsed and nested?  Should the first line have
-the same nesting level (== indentation in the output) as the fourth
-line, or the same as the last line?  Mark Nodine suggested that such
-line blocks be parsed similarly to complexly-nested block quotes,
-which seems reasonable.  In the example above, this would result in
-the nesting of first line matching the last line's nesting.  In
-other words, the nesting would be relative to neighboring lines
-only.
-
-
-Output
-------
-
-In HTML, line blocks are currently output as "<pre>" blocks, which
-gives us significant whitespace and line breaks, but doesn't allow
-long lines to wrap and causes monospaced output without stylesheets.
-Instead, we could output "<div>" elements parallelling the
-representation above, where each nested <div class="line_block"> would
-have an increased left margin (specified in the stylesheet).
-
-Jarno suggested the following HTML output::
-
-    <div class="line_block">
-       <span class="line">First, top level line</span><br class="hidden"/>
-       <div class="line_block"><span class="hidden">&nbsp;</span>
-          <span class="line">Second, once nested</span><br class="hidden"/>
-          <span class="line">Third, once nested</span><br class="hidden"/>
-          ...
-       </div>
-       ...
-    </div>
-
-The ``<br class="hidden" />`` and ``<span
-class="hidden">&nbsp;</span>`` are meant to support non-CSS and
-non-graphical browsers.  I understand the case for "br", but I'm not
-so sure about hidden "&nbsp;".  I question how much effort should be
-put toward supporting non-graphical and especially non-CSS browsers,
-at least for html4css1.py output.
-
-Should the lines themselves be ``<span>`` or ``<div>``?  I don't like
-mixing inline and block-level elements.
-
-
-Implementation Plan
--------------------
-
-We'll leave the old implementation in place (via the "line-block"
-directive only) until all Writers have been updated to support the new
-syntax & implementation.  The "line-block" directive can then be
-updated to use the new internal representation, and its documentation
-will be updated to recommend the new syntax.
-
-
-List-Driven Tables
-==================
-
-The original idea came from Dylan Jay:
-
-    ... to use a two level bulleted list with something to
-    indicate it should be rendered as a table ...
-
-It's an interesting idea.  It could be implemented in as a directive
-which transforms a uniform two-level list into a table.  Using a
-directive would allow the author to explicitly set the table's
-orientation (by column or by row), the presence of row headers, etc.
-
-Alternatives:
-
-1. (Implemented in Docutils 0.3.8).
-
-   Bullet-list-tables might look like this::
-
-       .. list-table::
-
-          * - Treat
-            - Quantity
-            - Description
-          * - Albatross!
-            - 299
-            - On a stick!
-          * - Crunchy Frog!
-            - 1499
-            - If we took the bones out, it wouldn't be crunchy,
-              now would it?
-          * - Gannet Ripple!
-            - 199
-            - On a stick!
-
-   This list must be written in two levels.  This wouldn't work::
-
-       .. list-table::
-
-          * Treat
-          * Albatross!
-          * Gannet!
-          * Crunchy Frog!
-
-          * Quantity
-          * 299
-          * 199
-          * 1499
-
-          * Description
-          * On a stick!
-          * On a stick!
-          * If we took the bones out...
-
-   The above is a single list of 12 items.  The blank lines are not
-   significant to the markup.  We'd have to explicitly specify how
-   many columns or rows to use, which isn't a good idea.
-
-2. Beni Cherniavsky suggested a field list alternative.  It could look
-   like this::
-
-       .. field-list-table::
-          :headrows: 1
-
-          - :treat: Treat
-            :quantity: Quantity
-            :descr: Description
-
-          - :treat: Albatross!
-            :quantity: 299
-            :descr: On a stick!
-
-          - :treat: Crunchy Frog!
-            :quantity: 1499
-            :descr: If we took the bones out, it wouldn't be
-                    crunchy, now would it?
-
-   Column order is determined from the order of fields in the first
-   row.  Field order in all other rows is ignored.  As a side-effect,
-   this allows trivial re-arrangement of columns.  By using named
-   fields, it becomes possible to omit fields in some rows without
-   losing track of things, which is important for spans.
-
-3. An alternative to two-level bullet lists would be to use enumerated
-   lists for the table cells::
-
-       .. list-table::
-
-           * 1. Treat
-             2. Quantity
-             3. Description
-           * 1. Albatross!
-             2. 299
-             3. On a stick!
-           * 1. Crunchy Frog!
-             2. 1499
-             3. If we took the bones out, it wouldn't be crunchy,
-                now would it?
-
-   That provides better correspondence between cells in the same
-   column than does bullet-list syntax, but not as good as field list
-   syntax.  I think that were only field-list-tables available, a lot
-   of users would use the equivalent degenerate case::
-
-       .. field-list-table::
-           - :1: Treat
-             :2: Quantity
-             :3: Description
-           ...
-
-4. Another natural variant is to allow a description list with field
-   lists as descriptions::
-
-       .. list-table::
-           :headrows: 1
-
-           Treat
-               :quantity: Quantity
-               :descr: Description
-           Albatross!
-               :quantity: 299
-               :descr: On a stick!
-           Crunchy Frog!
-               :quantity: 1499
-               :descr: If we took the bones out, it wouldn't be
-                       crunchy, now would it?
-
-   This would make the whole first column a header column ("stub").
-   It's limited to a single column and a single paragraph fitting on
-   one source line.  Also it wouldn't allow for empty cells or row
-   spans in the first column.  But these are limitations that we could
-   live with, like those of simple tables.
-
-The List-driven table feature could be done in many ways.  Each user
-will have their preferred usage.  Perhaps a single "list-table"
-directive could handle them all, depending on which options and
-content are present.
-
-Issues:
-
-* How to indicate that there's 1 header row?  Perhaps two lists?  ::
-
-      .. list-table::
-
-         + - Treat
-           - Quantity
-           - Description
-
-         * - Albatross!
-           - 299
-           - On a stick!
-
-  This is probably too subtle though.  Better would be a directive
-  option, like ``:headrows: 1``.  An early suggestion for the header
-  row(s) was to use a directive option::
-
-      .. field-list-table::
-         :header:
-             - :treat: Treat
-               :quantity: Quantity
-               :descr: Description
-         - :treat: Albatross!
-           :quantity: 299
-           :descr: On a stick!
-
-  But the table data is at two levels and looks inconsistent.
-
-  In general, we cannot extract the header row from field lists' field
-  names because field names cannot contain everything one might put in
-  a table cell.  A separate header row also allows shorter field names
-  and doesn't force one to rewrite the whole table when the header
-  text changes.  But for simpler cases, we can offer a ":header:
-  fields" option, which does extract header cells from field names::
-
-      .. field-list-table::
-          :header: fields
-
-          - :Treat: Albatross!
-            :Quantity: 299
-            :Description: On a stick!
-
-* How to indicate the column widths?  A directive option? ::
-
-      .. list-table::
-         :widths: 15 10 35
-
-  Automatic defaults from the text used?
-
-* How to handle row and/or column spans?
-
-  In a field list, column-spans can be indicated by specifying the
-  first and last fields, separated by space-dash-space or ellipsis::
-
-      - :foo - baz: quuux
-      - :foo ... baz: quuux
-
-  Commas were proposed for column spans::
-
-      - :foo, bar: quux
-
-  But non-adjacent columns become problematic.  Should we report an
-  error, or duplicate the value into each span of adjacent columns (as
-  was suggested)?  The latter suggestion is appealing but may be too
-  clever.  Best perhaps to simply specify the two ends.
-
-  It was suggested that comma syntax should be allowed, too, in order
-  to allow the user to avoid trouble when changing the column order.
-  But changing the column order of a table with spans is not trivial;
-  we shouldn't make it easier to mess up.
-
-  One possible syntax for row-spans is to simply treat any row where a
-  field is missing as a row-span from the last row where it appeared.
-  Leaving a field empty would still be possible by writing a field
-  with empty content.  But this is too implicit.
-
-  Another way would be to require an explicit continuation marker
-  (``...``/``-"-``/``"``?) in all but the first row of a spanned
-  field.  Empty comments could work ("..").  If implemented, the same
-  marker could also be supported in simple tables, which lack
-  row-spanning abilities.
-
-  Explicit markup like ":rowspan:" and ":colspan:" was also suggested.
-
-  Sometimes in a table, the first header row contains spans.  It may
-  be necessary to provide a way to specify the column field names
-  independently of data rows.  A directive option would do it.
-
-* We could specify "column-wise" or "row-wise" ordering, with the same
-  markup structure.  For example, with definition data::
-
-      .. list-table::
-         :column-wise:
-
-         Treat
-             - Albatross!
-             - Crunchy Frog!
-         Quantity
-             - 299
-             - 1499
-         Description
-             - On a stick!
-             - If we took the bones out, it wouldn't be
-               crunchy, now would it?
-
-* A syntax for _`stubs in grid tables` is easy to imagine::
-
-      +------------------------++------------+----------+
-      | Header row, column 1   || Header 2   | Header 3 |
-      +========================++============+==========+
-      | body row 1, column 1   || column 2   | column 3 |
-      +------------------------++------------+----------+
-
-  Or this idea from Nick Moffitt::
-
-      +-----+---+---+
-      | XOR # T | F |
-      +=====+===+===+
-      |   T # F | T |
-      +-----+---+---+
-      |   F # T | F |
-      +-----+---+---+
-
-
-Auto-Enumerated Lists
-=====================
-
-Implemented 2005-03-24: combination of variation 1 & 2.
-
-The advantage of auto-numbered enumerated lists would be similar to
-that of auto-numbered footnotes: lists could be written and rearranged
-without having to manually renumber them.  The disadvantages are also
-the same: input and output wouldn't match exactly; the markup may be
-ugly or confusing (depending on which alternative is chosen).
-
-1. Use the "#" symbol.  Example::
-
-       #. Item 1.
-       #. Item 2.
-       #. Item 3.
-
-   Advantages: simple, explicit.  Disadvantage: enumeration sequence
-   cannot be specified (limited to arabic numerals); ugly.
-
-2. As a variation on #1, first initialize the enumeration sequence?
-   For example::
-
-       a) Item a.
-       #) Item b.
-       #) Item c.
-
-   Advantages: simple, explicit, any enumeration sequence possible.
-   Disadvantages: ugly; perhaps confusing with mixed concrete/abstract
-   enumerators.
-
-3. Alternative suggested by Fred Bremmer, from experience with MoinMoin::
-
-       1. Item 1.
-       1. Item 2.
-       1. Item 3.
-
-   Advantages: enumeration sequence is explicit (could be multiple
-   "a." or "(I)" tokens).  Disadvantages: perhaps confusing; otherwise
-   erroneous input (e.g., a duplicate item "1.") would pass silently,
-   either causing a problem later in the list (if no blank lines
-   between items) or creating two lists (with blanks).
-
-   Take this input for example::
-
-       1. Item 1.
-
-       1. Unintentional duplicate of item 1.
-
-       2. Item 2.
-
-   Currently the parser will produce two list, "1" and "1,2" (no
-   warnings, because of the presence of blank lines).  Using Fred's
-   notation, the current behavior is "1,1,2 -> 1 1,2" (without blank
-   lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2").  What
-   should the behavior be with auto-numbering?
-
-   Fred has produced a patch__, whose initial behavior is as follows::
-
-       1,1,1   -> 1,2,3
-       1,2,2   -> 1,2,3
-       3,3,3   -> 3,4,5
-       1,2,2,3 -> 1,2,3 [WARNING] 3
-       1,1,2   -> 1,2 [WARNING] 2
-
-   (After the "[WARNING]", the "3" would begin a new list.)
-
-   I have mixed feelings about adding this functionality to the spec &
-   parser.  It would certainly be useful to some users (myself
-   included; I often have to renumber lists).  Perhaps it's too
-   clever, asking the parser to guess too much.  What if you *do* want
-   three one-item lists in a row, each beginning with "1."?  You'd
-   have to use empty comments to force breaks.  Also, I question
-   whether "1,2,2 -> 1,2,3" is optimal behavior.
-
-   In response, Fred came up with "a stricter and more explicit rule
-   [which] would be to only auto-number silently if *all* the
-   enumerators of a list were identical".  In that case::
-
-       1,1,1   -> 1,2,3
-       1,2,2   -> 1,2 [WARNING] 2
-       3,3,3   -> 3,4,5
-       1,2,2,3 -> 1,2 [WARNING] 2,3
-       1,1,2   -> 1,2 [WARNING] 2
-
-   Should any start-value be allowed ("3,3,3"), or should
-   auto-numbered lists be limited to begin with ordinal-1 ("1", "A",
-   "a", "I", or "i")?
-
-   __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802
-      &group_id=38414&atid=422032
-
-4. Alternative proposed by Tony Ibbs::
-
-       #1. First item.
-       #3. Aha - I edited this in later.
-       #2. Second item.
-
-   The initial proposal required unique enumerators within a list, but
-   this limits the convenience of a feature of already limited
-   applicability and convenience.  Not a useful requirement; dropped.
-
-   Instead, simply prepend a "#" to a standard list enumerator to
-   indicate auto-enumeration.  The numbers (or letters) of the
-   enumerators themselves are not significant, except:
-
-   - as a sequence indicator (arabic, roman, alphabetic; upper/lower),
-
-   - and perhaps as a start value (first list item).
-
-   Advantages: explicit, any enumeration sequence possible.
-   Disadvantages: a bit ugly.
-
-
------------------
- Not Implemented
------------------
-
-Reworking Footnotes
-===================
-
-As a further wrinkle (see `Reworking Explicit Markup (Round 1)`_
-above), in the wee hours of 2002-02-28 I posted several ideas for
-changes to footnote syntax:
-
-    - Change footnote syntax from ``.. [1]`` to ``_[1]``? ...
-    - Differentiate (with new DTD elements) author-date "citations"
-      (``[GVR2002]``) from numbered footnotes? ...
-    - Render footnote references as superscripts without "[]"? ...
-
-These ideas are all related, and suggest changes in the
-reStructuredText syntax as well as the docutils tree model.
-
-The footnote has been used for both true footnotes (asides expanding
-on points or defining terms) and for citations (references to external
-works).  Rather than dealing with one amalgam construct, we could
-separate the current footnote concept into strict footnotes and
-citations.  Citations could be interpreted and treated differently
-from footnotes.  Footnotes would be limited to numerical labels:
-manual ("1") and auto-numbered (anonymous "#", named "#label").
-
-The footnote is the only explicit markup construct (starts with ".. ")
-that directly translates to a visible body element.  I've always been
-a little bit uncomfortable with the ".. " marker for footnotes because
-of this; ".. " has a connotation of "special", but footnotes aren't
-especially "special".  Printed texts often put footnotes at the bottom
-of the page where the reference occurs (thus "foot note").  Some HTML
-designs would leave footnotes to be rendered the same positions where
-they're defined.  Other online and printed designs will gather
-footnotes into a section near the end of the document, converting them
-to "endnotes" (perhaps using a directive in our case); but this
-"special processing" is not an intrinsic property of the footnote
-itself, but a decision made by the document author or processing
-system.
-
-Citations are almost invariably collected in a section at the end of a
-document or section.  Citations "disappear" from where they are
-defined and are magically reinserted at some well-defined point.
-There's more of a connection to the "special" connotation of the ".. "
-syntax.  The point at which the list of citations is inserted could be
-defined manually by a directive (e.g., ".. citations::"), and/or have
-default behavior (e.g., a section automatically inserted at the end of
-the document) that might be influenced by options to the Writer.
-
-Syntax proposals:
-
-+ Footnotes:
-
-  - Current syntax::
-
-        .. [1] Footnote 1
-        .. [#] Auto-numbered footnote.
-        .. [#label] Auto-labeled footnote.
-
-  - The syntax proposed in the original 2002-02-28 Doc-SIG post:
-    remove the ".. ", prefix a "_"::
-
-        _[1] Footnote 1
-        _[#] Auto-numbered footnote.
-        _[#label] Auto-labeled footnote.
-
-    The leading underscore syntax (earlier dropped because
-    ``.. _[1]:`` was too verbose) is a useful reminder that footnotes
-    are hyperlink targets.
-
-  - Minimal syntax: remove the ".. [" and "]", prefix a "_", and
-    suffix a "."::
-
-        _1. Footnote 1.
-        _#. Auto-numbered footnote.
-        _#label. Auto-labeled footnote.
-
-                 ``_1.``, ``_#.``, and ``_#label.`` are markers,
-                 like list markers.
-
-    Footnotes could be rendered something like this in HTML
-
-        | 1. This is a footnote.  The brackets could be dropped
-        |    from the label, and a vertical bar could set them
-        |    off from the rest of the document in the HTML.
-
-    Two-way hyperlinks on the footnote marker ("1." above) would also
-    help to differentiate footnotes from enumerated lists.
-
-    If converted to endnotes (by a directive/transform), a horizontal
-    half-line might be used instead.  Page-oriented output formats
-    would typically use the horizontal line for true footnotes.
-
-+ Footnote references:
-
-  - Current syntax::
-
-        [1]_, [#]_, [#label]_
-
-  - Minimal syntax to match the minimal footnote syntax above::
-
-        1_, #_, #label_
-
-    As a consequence, pure-numeric hyperlink references would not be
-    possible; they'd be interpreted as footnote references.
-
-+ Citation references: no change is proposed from the current footnote
-  reference syntax::
-
-      [GVR2001]_
-
-+ Citations:
-
-  - Current syntax (footnote syntax)::
-
-        .. [GVR2001] Python Documentation; van Rossum, Drake, et al.;
-           http://www.python.org/doc/
-
-  - Possible new syntax::
-
-        _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
-                   http://www.python.org/doc/
-
-        _[DJG2002]
-            Docutils: Python Documentation Utilities project; Goodger
-            et al.; http://docutils.sourceforge.net/
-
-    Without the ".. " marker, subsequent lines would either have to
-    align as in one of the above, or we'd have to allow loose
-    alignment (I'd rather not)::
-
-        _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
-            http://www.python.org/doc/
-
-I proposed adopting the "minimal" syntax for footnotes and footnote
-references, and adding citations and citation references to
-reStructuredText's repertoire.  The current footnote syntax for
-citations is better than the alternatives given.
-
-From a reply by Tony Ibbs on 2002-03-01:
-
-    However, I think easier with examples, so let's create one::
-
-        Fans of Terry Pratchett are perhaps more likely to use
-        footnotes [1]_ in their own writings than other people
-        [2]_.  Of course, in *general*, one only sees footnotes
-        in academic or technical writing - it's use in fiction
-        and letter writing is not normally considered good
-        style [4]_, particularly in emails (not a medium that
-        lends itself to footnotes).
-
-        .. [1] That is, little bits of referenced text at the
-           bottom of the page.
-        .. [2] Because Terry himself does, of course [3]_.
-        .. [3] Although he has the distinction of being
-           *funny* when he does it, and his fans don't always
-           achieve that aim.
-        .. [4] Presumably because it detracts from linear
-           reading of the text - this is, of course, the point.
-
-    and look at it with the second syntax proposal::
-
-        Fans of Terry Pratchett are perhaps more likely to use
-        footnotes [1]_ in their own writings than other people
-        [2]_.  Of course, in *general*, one only sees footnotes
-        in academic or technical writing - it's use in fiction
-        and letter writing is not normally considered good
-        style [4]_, particularly in emails (not a medium that
-        lends itself to footnotes).
-
-        _[1] That is, little bits of referenced text at the
-             bottom of the page.
-        _[2] Because Terry himself does, of course [3]_.
-        _[3] Although he has the distinction of being
-             *funny* when he does it, and his fans don't always
-             achieve that aim.
-        _[4] Presumably because it detracts from linear
-             reading of the text - this is, of course, the point.
-
-    (I note here that if I have gotten the indentation of the
-    footnotes themselves correct, this is clearly not as nice.  And if
-    the indentation should be to the left margin instead, I like that
-    even less).
-
-    and the third (new) proposal::
-
-        Fans of Terry Pratchett are perhaps more likely to use
-        footnotes 1_ in their own writings than other people
-        2_.  Of course, in *general*, one only sees footnotes
-        in academic or technical writing - it's use in fiction
-        and letter writing is not normally considered good
-        style 4_, particularly in emails (not a medium that
-        lends itself to footnotes).
-
-        _1. That is, little bits of referenced text at the
-            bottom of the page.
-        _2. Because Terry himself does, of course 3_.
-        _3. Although he has the distinction of being
-            *funny* when he does it, and his fans don't always
-            achieve that aim.
-        _4. Presumably because it detracts from linear
-            reading of the text - this is, of course, the point.
-
-    I think I don't, in practice, mind the targets too much (the use
-    of a dot after the number helps a lot here), but I do have a
-    problem with the body text, in that I don't naturally separate out
-    the footnotes as different than the rest of the text - instead I
-    keep wondering why there are numbers interspered in the text.  The
-    use of brackets around the numbers ([ and ]) made me somehow parse
-    the footnote references as "odd" - i.e., not part of the body text
-    - and thus both easier to skip, and also (paradoxically) easier to
-    pick out so that I could follow them.
-
-    Thus, for the moment (and as always susceptable to argument), I'd
-    say -1 on the new form of footnote reference (i.e., I much prefer
-    the existing ``[1]_`` over the proposed ``1_``), and ambivalent
-    over the proposed target change.
-
-    That leaves David's problem of wanting to distinguish footnotes
-    and citations - and the only thing I can propose there is that
-    footnotes are numeric or # and citations are not (which, as a
-    human being, I can probably cope with!).
-
-From a reply by Paul Moore on 2002-03-01:
-
-    I think the current footnote syntax ``[1]_`` is *exactly* the
-    right balance of distinctness vs unobtrusiveness.  I very
-    definitely don't think this should change.
-
-    On the target change, it doesn't matter much to me.
-
-From a further reply by Tony Ibbs on 2002-03-01, referring to the
-"[1]" form and actual usage in email:
-
-    Clearly this is a form people are used to, and thus we should
-    consider it strongly (in the same way that the usage of ``*..*``
-    to mean emphasis was taken partly from email practise).
-
-    Equally clearly, there is something "magical" for people in the
-    use of a similar form (i.e., ``[1]``) for both footnote reference
-    and footnote target - it seems natural to keep them similar.
-
-    ...
-
-    I think that this established plaintext usage leads me to strongly
-    believe we should retain square brackets at both ends of a
-    footnote.  The markup of the reference end (a single trailing
-    underscore) seems about as minimal as we can get away with.  The
-    markup of the target end depends on how one envisages the thing -
-    if ".." means "I am a target" (as I tend to see it), then that's
-    good, but one can also argue that the "_[1]" syntax has a neat
-    symmetry with the footnote reference itself, if one wishes (in
-    which case ".." presumably means "hidden/special" as David seems
-    to think, which is why one needs a ".." *and* a leading underline
-    for hyperlink targets.
-
-Given the persuading arguments voiced, we'll leave footnote & footnote
-reference syntax alone.  Except that these discussions gave rise to
-the "auto-symbol footnote" concept, which has been added.  Citations
-and citation references have also been added.
-
-
-Syntax for Questions & Answers
-==============================
-
-Implement as a generic two-column marked list?  As a standalone
-(non-directive) construct?  (Is the markup ambiguous?)  Add support to
-parts.contents?
-
-New elements would be required.  Perhaps::
-
-    <!ELEMENT question_list (question_list_item+)>
-    <!ATTLIST question_list
-        numbering  (none | local | global)
-                            #IMPLIED
-        start     NUMBER    #IMPLIED>
-    <!ELEMENT question_list_item (question, answer*)>
-    <!ELEMENT question %text.model;>
-    <!ELEMENT answer (%body.elements;)+>
-
-Originally I thought of implementing a Q&A list with special syntax::
-
-    Q: What am I?
-
-    A: You are a question-and-answer
-       list.
-
-    Q: What are you?
-
-    A: I am the omniscient "we".
-
-Where each "Q" and "A" could also be numbered (e.g., "Q1").  However,
-a simple enumerated or bulleted list will do just fine for syntax.  A
-directive could treat the list specially; e.g. the first paragraph
-could be treated as a question, the remainder as the answer (multiple
-answers could be represented by nested lists).  Without special
-syntax, this directive becomes low priority.
-
-As described in the FAQ__, no special syntax or directive is needed
-for this application.
-
-__ http://docutils.sf.net/FAQ.html
-   #how-can-i-mark-up-a-faq-or-other-list-of-questions-answers
-
-
---------
- Tabled
---------
-
-Reworking Explicit Markup (Round 2)
-===================================
-
-See `Reworking Explicit Markup (Round 1)`_ for an earlier discussion.
-
-In April 2004, a new thread becan on docutils-develop: `Inconsistency
-in RST markup`__.  Several arguments were made; the first argument
-begat later arguments.  Below, the arguments are paraphrased "in
-quotes", with responses.
-
-__ http://thread.gmane.org/gmane.text.docutils.devel/1386
-
-1. References and targets take this form::
-
-       targetname_
-
-       .. _targetname: stuff
-
-   But footnotes, "which generate links just like targets do", are
-   written as::
-
-       [1]_
-
-       .. [1] stuff
-
-   "Footnotes should be written as"::
-
-       [1]_
-
-       .. _[1]: stuff
-
-   But they're not the same type of animal.  That's not a "footnote
-   target", it's a *footnote*.  Being a target is not a footnote's
-   primary purpose (an arguable point).  It just happens to grow a
-   target automatically, for convenience.  Just as a section title::
-
-       Title
-       =====
-
-   isn't a "title target", it's a *title*, which happens to grow a
-   target automatically.  The consistency is there, it's just deeper
-   than at first glance.
-
-   Also, ".. [1]" was chosen for footnote syntax because it closely
-   resembles one form of actual footnote rendering.  ".. _[1]:" is too
-   verbose; excessive punctuation is required to get the job done.
-
-   For more of the reasoning behind the syntax, see `Problems With
-   StructuredText (Hyperlinks) <problems.html#hyperlinks>`__ and
-   `Reworking Footnotes`_.
-
-2. "I expect directives to also look like ``.. this:`` [one colon]
-   because that also closely parallels the link and footnote target
-   markup."
-
-   There are good reasons for the two-colon syntax:
-
-       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.
-
-       -- `restructuredtext.html#directives
-       <../../ref/rst/restructuredtext.html#directives>`__
-
-   The last reason is not particularly compelling; it's more of a
-   convenient coincidence or mnemonic.
-
-3. "Comments always seemed too easy.  I almost never write comments.
-   I'd have no problem writing '.. comment:' in front of my comments.
-   In fact, it would probably be more readable, as comments *should*
-   be set off strongly, because they are very different from normal
-   text."
-
-   Many people do use comments though, and some applications of
-   reStructuredText require it.  For example, all reStructuredText
-   PEPs (and this document!) have an Emacs stanza at the bottom, in a
-   comment.  Having to write ".. comment::" would be very obtrusive.
-
-   Comments *should* be dirt-easy to do.  It should be easy to
-   "comment out" a block of text.  Comments in programming languages
-   and other markup languages are invariably easy.
-
-   Any author is welcome to preface their comments with "Comment:" or
-   "Do Not Print" or "Note to Editor" or anything they like.  A
-   "comment" directive could easily be implemented.  It might be
-   confused with admonition directives, like "note" and "caution"
-   though.  In unrelated (and unpublished and unfinished) work, adding
-   a "comment" directive as a true document element was considered::
-
-       If structure is necessary, we could use a "comment" directive
-       (to avoid nonsensical DTD changes, the "comment" directive
-       could produce an untitled topic element).
-
-4. "One of the goals of reStructuredText is to be *readable* by people
-   who don't know it.  This construction violates that: it is not at
-   all obvious to the uninitiated that text marked by '..' is a
-   comment.  On the other hand, '.. comment:' would be totally
-   transparent."
-
-   Totally transparent, perhaps, but also very obtrusive.  Another of
-   `reStructuredText's goals`_ is to be unobtrusive, and
-   ".. comment::" would violate that.  The goals of reStructuredText
-   are many, and they conflict.  Determining the right set of goals
-   and finding solutions that best fit is done on a case-by-case
-   basis.
-
-   Even readability is has two aspects.  Being readable without any
-   prior knowledge is one.  Being as easily read in raw form as in
-   processed form is the other.  ".." may not contribute to the former
-   aspect, but ".. comment::" would certainly detract from the latter.
-
-   .. _author's note:
-   .. _reStructuredText's goals: ../../ref/rst/introduction.html#goals
-
-5. "Recently I sent someone an rst document, and they got confused; I
-   had to explain to them that '..' marks comments, *unless* it's a
-   directive, etc..."
-
-   The explanation of directives *is* roundabout, defining comments in
-   terms of not being other things.  That's definitely a wart.
-
-6. "Under the current system, a mistyped directive (with ':' instead
-   of '::') will be silently ignored.  This is an error that could
-   easily go unnoticed."
-
-   A parser option/setting like "--comments-on-stderr" would help.
-
-7. "I'd prefer to see double-dot-space / command / double-colon as the
-   standard Docutils markup-marker.  It's unusual enough to avoid
-   being accidently used.  Everything that starts with a double-dot
-   should end with a double-colon."
-
-   That would increase the punctuation verbosity of some constructs
-   considerably.
-
-8. Edward Loper proposed the following plan for backwards
-   compatibility:
-
-       1. ".. foo" will generate a deprecation warning to stderr, and
-          nothing in the output (no system messages).
-       2. ".. foo: bar" will be treated as a directive foo.  If there
-          is no foo directive, then do the normal error output.
-       3. ".. foo:: bar" will generate a deprecation warning to
-          stderr, and be treated as a directive.  Or leave it valid?
-
-       So some existing documents might start printing deprecation
-       warnings, but the only existing documents that would *break*
-       would be ones that say something like::
-
-           .. warning: this should be a comment
-
-       instead of::
-
-           .. warning:: this should be a comment
-
-       Here, we're trading fairly common a silent error (directive
-       falsely treated as a comment) for a fairly uncommon explicitly
-       flagged error (comment falsely treated as directive).  To make
-       things even easier, we could add a sentence to the
-       unknown-directive error.  Something like "If you intended to
-       create a comment, please use '.. comment:' instead".
-
-On one hand, I understand and sympathize with the points raised.  On
-the other hand, I think the current syntax strikes the right balance
-(but I acknowledge a possible lack of objectivity).  On the gripping
-hand, the comment and directive syntax has become well established, so
-even if it's a wart, it may be a wart we have to live with.
-
-Making any of these changes would cause a lot of breakage or at least
-deprecation warnings.  I'm not sure the benefit is worth the cost.
-
-For now, we'll treat this as an unresolved legacy issue.
-
-
--------
- To Do
--------
-
-Nested Inline Markup
-====================
-
-These are collected notes on a long-discussed issue.  The original
-mailing list messages should be referred to for details.
-
-* In a 2001-10-31 discussion I wrote:
-
-      Try, for example, `Ed Loper's 2001-03-21 post`_, which details
-      some rules for nested inline markup. I think the complexity is
-      prohibitive for the marginal benefit. (And if you can understand
-      that tree without going mad, you're a better man than I. ;-)
-
-      Inline markup is already fragile. Allowing nested inline markup
-      would only be asking for trouble IMHO. If it proves absolutely
-      necessary, it can be added later. The rules for what can appear
-      inside what must be well thought out first though.
-
-      .. _Ed Loper's 2001-03-21 post:
-         http://mail.python.org/pipermail/doc-sig/2001-March/001487.html
-
-      -- http://mail.python.org/pipermail/doc-sig/2001-October/002354.html
-
-* In a 2001-11-09 Doc-SIG post, I wrote:
-
-      The problem is that in the
-      what-you-see-is-more-or-less-what-you-get markup language that
-      is reStructuredText, the symbols used for inline markup ("*",
-      "**", "`", "``", etc.) may preclude nesting.
-
-  I've rethought this position.  Nested markup is not precluded, just
-  tricky.  People and software parse "double and 'single' quotes" all
-  the time.  Continuing,
-
-      I've thought over how we might implement nested inline
-      markup. The first algorithm ("first identify the outer inline
-      markup as we do now, then recursively scan for nested inline
-      markup") won't work; counterexamples were given in my `last post
-      <http://mail.python.org/pipermail/doc-sig/2001-November/002363.html>`__.
-
-      The second algorithm makes my head hurt::
-
-          while 1:
-              scan for start-string
-              if found:
-                  push on stack
-                  scan for start or end string
-                  if new start string found:
-                      recurse
-                  elif matching end string found:
-                      pop stack
-                  elif non-matching end string found:
-                      if its a markup error:
-                          generate warning
-                      elif the initial start-string was misinterpreted:
-                          # e.g. in this case: ***strong** in emphasis*
-                          restart with the other interpretation
-                          # but it might be several layers back ...
-              ...
-
-      This is similar to how the parser does section title
-      recognition, but sections are much more regular and
-      deterministic.
-
-      Bottom line is, I don't think the benefits are worth the effort,
-      even if it is possible. I'm not going to try to write the code,
-      at least not now. If somebody codes up a consistent, working,
-      general solution, I'll be happy to consider it.
-
-      -- http://mail.python.org/pipermail/doc-sig/2001-November/002388.html
-
-* In a `2003-05-06 Docutils-Users post`__ Paul Tremblay proposed a new
-  syntax to allow for easier nesting.  It eventually evolved into
-  this::
-
-      :role:[inline text]
-
-  The duplication with the existing interpreted text syntax is
-  problematic though.
-
-  __ http://article.gmane.org/gmane.text.docutils.user/317
-
-* Could the parser be extended to parse nested interpreted text? ::
-
-      :emphasis:`Some emphasized text with :strong:`some more
-      emphasized text` in it and **perhaps** :reference:`a link``
-
-* In a `2003-06-18 Docutils-Develop post`__, Mark Nodine reported on
-  his implementation of a form of nested inline markup in his
-  Perl-based parser (unpublished).  He brought up some interesting
-  ideas.  The implementation was flawed, however, by the change in
-  semantics required for backslash escapes.
-
-  __ http://article.gmane.org/gmane.text.docutils.devel/795
-
-* Docutils-develop threads between David Abrahams, David Goodger, and
-  Mark Nodine (beginning 2004-01-16__ and 2004-01-19__) hashed out
-  many of the details of a potentially successful implementation, as
-  described below.  David Abrahams checked in code to the "nesting"
-  branch of CVS, awaiting thorough review.
-
-  __ http://thread.gmane.org/gmane.text.docutils.devel/1102
-  __ http://thread.gmane.org/gmane.text.docutils.devel/1125
-
-It may be possible to accomplish nested inline markup in general with
-a more powerful inline markup parser.  There may be some issues, but
-I'm not averse to the idea of nested inline markup in general.  I just
-don't have the time or inclination to write a new parser now.  Of
-course, a good patch would be welcome!
-
-I envisage something like this.  Explicit-role interpreted text must
-be nestable.  Prefix-based is probably preferred, since suffix-based
-will look like inline literals::
-
-    ``text`:role1:`:role2:
-
-But it can be disambiguated, so it ought to be left up to the author::
-
-    `\ `text`:role1:`:role2:
-
-In addition, other forms of inline markup may be nested if
-unambiguous::
-
-    *emphasized ``literal`` and |substitution ref| and link_*
-
-IOW, the parser ought to be as permissive as possible.
-
-
-Index Entries & Indexes
-=======================
-
-Were I writing a book with an index, I guess I'd need two
-different kinds of index targets: inline/implicit and
-out-of-line/explicit.  For example::
-
-    In this `paragraph`:index:, several words are being
-    `marked`:index: inline as implicit `index`:index:
-    entries.
-
-    .. index:: markup
-    .. index:: syntax
-
-    The explicit index directives above would refer to
-    this paragraph.  It might also make sense to allow multiple
-    entries in an ``index`` directive:
-
-    .. index::
-        markup
-        syntax
-
-The words "paragraph", "marked", and "index" would become index
-entries pointing at the words in the first paragraph.  The index
-entry words appear verbatim in the text.  (Don't worry about the
-ugly ":index:" part; if indexing is the only/main application of
-interpreted text in your documents, it can be implicit and
-omitted.)  The two directives provide manual indexing, where the
-index entry words ("markup" and "syntax") do not appear in the
-main text.  We could combine the two directives into one::
-
-    .. index:: markup; syntax
-
-Semicolons instead of commas because commas could *be* part of the
-index target, like::
-
-    .. index:: van Rossum, Guido
-
-Another reason for index directives is because other inline markup
-wouldn't be possible within inline index targets.
-
-Sometimes index entries have multiple levels.  Given::
-
-    .. index:: statement syntax: expression statements
-
-In a hypothetical index, combined with other entries, it might
-look like this::
-
-    statement syntax
-        expression statements ..... 56
-        assignment ................ 57
-        simple statements ......... 58
-        compound statements ....... 60
-
-Inline multi-level index targets could be done too.  Perhaps
-something like::
-
-    When dealing with `expression statements <statement syntax:>`,
-    we must remember ...
-
-The opposite sense could also be possible::
-
-    When dealing with `index entries <:multi-level>`, there are
-    many permutations to consider.
-
-Also "see / see also" index entries.
-
-Given::
-
-    Here's a paragraph.
-
-    .. index:: paragraph
-
-(The "index" directive above actually targets the *preceding*
-object.)  The directive should produce something like this XML::
-
-    <paragraph>
-    <index_entry text="paragraph"/>
-    Here's a paragraph.
-    </paragraph>
-
-This kind of content model would also allow true inline
-index-entries::
-
-    Here's a `paragraph`:index:.
-
-If the "index" role were the default for the application, it could be
-dropped::
-
-    Here's a `paragraph`.
-
-Both of these would result in this XML::
-
-    <paragraph>
-    Here's a <index_entry>paragraph</index_entry>.
-    </paragraph>
-
-
-from 2002-06-24 docutils-develop posts
---------------------------------------
-
-    If all of your index entries will appear verbatim in the text,
-    this should be sufficient.  If not (e.g., if you want "Van Rossum,
-    Guido" in the index but "Guido van Rossum" in the text), we'll
-    have to figure out a supplemental mechanism, perhaps using
-    substitutions.
-
-I've thought a bit more on this, and I came up with two possibilities:
-
-1. Using interpreted text, embed the index entry text within the
-   interpreted text::
-
-       ... by `Guido van Rossum [Van Rossum, Guido]` ...
-
-   The problem with this is obvious: the text becomes cluttered and
-   hard to read.  The processed output would drop the text in
-   brackets, which goes against the spirit of interpreted text.
-
-2. Use substitutions::
-
-       ... by |Guido van Rossum| ...
-
-       .. |Guido van Rossum| index:: Van Rossum, Guido
-
-   A problem with this is that each substitution definition must have
-   a unique name.  A subsequent ``.. |Guido van Rossum| index:: BDFL``
-   would be illegal.  Some kind of anonymous substitution definition
-   mechanism would be required, but I think that's going too far.
-
-Both of these alternatives are flawed.  Any other ideas?
-
-
--------------------
- ... Or Not To Do?
--------------------
-
-This is the realm of the possible but questionably probable.  These
-ideas are kept here as a record of what has been proposed, for
-posterity and in case any of them prove to be useful.
-
-
-Compound Enumerated Lists
-=========================
-
-Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to
-allow for nested enumerated lists without indentation?
-
-
-Indented Lists
-==============
-
-Allow for variant styles by interpreting indented lists as if they
-weren't indented?  For example, currently the list below will be
-parsed as a list within a block quote::
-
-    paragraph
-
-      * list item 1
-      * list item 2
-
-But a lot of people seem to write that way, and HTML browsers make it
-look as if that's the way it should be.  The parser could check the
-contents of block quotes, and if they contain only a single list,
-remove the block quote wrapper.  There would be two problems:
-
-1. What if we actually *do* want a list inside a block quote?
-
-2. What if such a list comes immediately after an indented construct,
-   such as a literal block?
-
-Both could be solved using empty comments (problem 2 already exists
-for a block quote after a literal block).  But that's a hack.
-
-Perhaps a runtime setting, allowing or disabling this convenience,
-would be appropriate.  But that raises issues too:
-
-    User A, who writes lists indented (and their config file is set up
-    to allow it), sends a file to user B, who doesn't (and their
-    config file disables indented lists).  The result of processing by
-    the two users will be different.
-
-It may seem minor, but it adds ambiguity to the parser, which is bad.
-
-See the `Doc-SIG discussion starting 2001-04-18`__ with Ed Loper's
-"Structuring: a summary; and an attempt at EBNF", item 4 (and
-follow-ups, here__ and here__).  Also `docutils-users, 2003-02-17`__
-and `beginning 2003-08-04`__.
-
-__ http://mail.python.org/pipermail/doc-sig/2001-April/001776.html
-__ http://mail.python.org/pipermail/doc-sig/2001-April/001789.html
-__ http://mail.python.org/pipermail/doc-sig/2001-April/001793.html
-__ http://sourceforge.net/mailarchive/message.php?msg_id=3838913
-__ http://sf.net/mailarchive/forum.php?thread_id=2957175&forum_id=11444
-
-
-Sloppy Indentation of List Items
-================================
-
-Perhaps the indentation shouldn't be so strict.  Currently, this is
-required::
-
-    1. First line,
-       second line.
-
-Anything wrong with this? ::
-
-    1. First line,
-     second line.
-
-Problem? ::
-
-    1. First para.
-
-       Block quote.  (no good: requires some indent relative to first
-       para)
-
-     Second Para.
-
-    2. Have to carefully define where the literal block ends::
-
-         Literal block
-
-       Literal block?
-
-Hmm...  Non-strict indentation isn't such a good idea.
-
-
-Lazy Indentation of List Items
-==============================
-
-Another approach: Going back to the first draft of reStructuredText
-(2000-11-27 post to Doc-SIG)::
-
-    - This is the fourth item of the main list (no blank line above).
-    The second line of this item is not indented relative to the
-    bullet, which precludes it from having a second paragraph.
-
-Change that to *require* a blank line above and below, to reduce
-ambiguity.  This "loosening" may be added later, once the parser's
-been nailed down.  However, a serious drawback of this approach is to
-limit the content of each list item to a single paragraph.
-
-
-David's Idea for Lazy Indentation
----------------------------------
-
-Consider a paragraph in a word processor.  It is a single logical line
-of text which ends with a newline, soft-wrapped arbitrarily at the
-right edge of the page or screen.  We can think of a plaintext
-paragraph in the same way, as a single logical line of text, ending
-with two newlines (a blank line) instead of one, and which may contain
-arbitrary line breaks (newlines) where it was accidentally
-hard-wrapped by an application.  We can compensate for the accidental
-hard-wrapping by "unwrapping" every unindented second and subsequent
-line.  The indentation of the first line of a paragraph or list item
-would determine the indentation for the entire element.  Blank lines
-would be required between list items when using lazy indentation.
-
-The following example shows the lazy indentation of multiple body
-elements::
-
-    - This is the first paragraph
-    of the first list item.
-
-      Here is the second paragraph
-    of the first list item.
-
-    - This is the first paragraph
-    of the second list item.
-
-      Here is the second paragraph
-    of the second list item.
-
-A more complex example shows the limitations of lazy indentation::
-
-    - This is the first paragraph
-    of the first list item.
-
-      Next is a definition list item:
-
-      Term
-          Definition.  The indentation of the term is
-    required, as is the indentation of the definition's
-    first line.
-
-          When the definition extends to more than
-    one line, lazy indentation may occur.  (This is the second
-    paragraph of the definition.)
-
-    - This is the first paragraph
-    of the second list item.
-
-      - Here is the first paragraph of
-    the first item of a nested list.
-
-      So this paragraph would be outside of the nested list,
-    but inside the second list item of the outer list.
-
-    But this paragraph is not part of the list at all.
-
-And the ambiguity remains::
-
-    - Look at the hyphen at the beginning of the next line
-    - is it a second list item marker, or a dash in the text?
-
-    Similarly, we may want to refer to numbers inside enumerated
-    lists:
-
-    1. How many socks in a pair? There are
-    2. How many pants in a pair? Exactly
-    1. Go figure.
-
-Literal blocks and block quotes would still require consistent
-indentation for all their lines.  For block quotes, we might be able
-to get away with only requiring that the first line of each contained
-element be indented.  For example::
-
-    Here's a paragraph.
-
-        This is a paragraph inside a block quote.
-    Second and subsequent lines need not be indented at all.
-
-        - A bullet list inside
-    the block quote.
-
-          Second paragraph of the
-    bullet list inside the block quote.
-
-Although feasible, this form of lazy indentation has problems.  The
-document structure and hierarchy is not obvious from the indentation,
-making the source plaintext difficult to read.  This will also make
-keeping track of the indentation while writing difficult and
-error-prone.  However, these problems may be acceptable for Wikis and
-email mode, where we may be able to rely on less complex structure
-(few nested lists, for example).
-
-
-Multiple Roles in Interpreted Text
-==================================
-
-In reStructuredText, inline markup cannot be nested (yet; `see
-above`__).  This also applies to interpreted text.  In order to
-simultaneously combine multiple roles for a single piece of text, a
-syntax extension would be necessary.  Ideas:
-
-1. Initial idea::
-
-       `interpreted text`:role1,role2:
-
-2. Suggested by Jason Diamond::
-
-       `interpreted text`:role1:role2:
-
-If a document is so complex as to require nested inline markup,
-perhaps another markup system should be considered.  By design,
-reStructuredText does not have the flexibility of XML.
-
-__ `Nested Inline Markup`_
-
-
-Parameterized Interpreted Text
-==============================
-
-In some cases it may be expedient to pass parameters to interpreted
-text, analogous to function calls.  Ideas:
-
-1. Parameterize the interpreted text role itself (suggested by Jason
-   Diamond)::
-
-       `interpreted text`:role1(foo=bar):
-
-   Positional parameters could also be supported::
-
-       `CSS`:acronym(Cascading Style Sheets): is used for HTML, and
-       `CSS`:acronym(Content Scrambling System): is used for DVDs.
-
-   Technical problem: current interpreted text syntax does not
-   recognize roles containing whitespace.  Design problem: this smells
-   like programming language syntax, but reStructuredText is not a
-   programming language.
-
-2. Put the parameters inside the interpreted text::
-
-       `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and
-       `CSS (Content Scrambling System)`:acronym: is used for DVDs.
-
-   Although this could be defined on an individual basis (per role),
-   we ought to have a standard.  Hyperlinks with embedded URIs already
-   use angle brackets; perhaps they could be used here too::
-
-       `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and
-       `CSS <Content Scrambling System>`:acronym: is used for DVDs.
-
-   Do angle brackets connote URLs too much for this to be acceptable?
-   How about the "tag" connotation -- does it save them or doom them?
-
-3. `Nested inline markup`_ could prove useful here::
-
-       `CSS :def:`Cascading Style Sheets``:acronym: is used for HTML,
-       and `CSS :def:`Content Scrambling System``:acronym: is used for
-       DVDs.
-
-   Inline markup roles could even define the default roles of nested
-   inline markup, allowing this cleaner syntax::
-
-       `CSS `Cascading Style Sheets``:acronym: is used for HTML, and
-       `CSS `Content Scrambling System``:acronym: is used for DVDs.
-
-Does this push inline markup too far?  Readability becomes a serious
-issue.  Substitutions may provide a better alternative (at the expense
-of verbosity and duplication) by pulling the details out of the text
-flow::
-
-    |CSS| is used for HTML, and |CSS-DVD| is used for DVDs.
-
-    .. |CSS| acronym:: Cascading Style Sheets
-    .. |CSS-DVD| acronym:: Content Scrambling System
-       :text: CSS
-
-----------------------------------------------------------------------
-
-This whole idea may be going beyond the scope of reStructuredText.
-Documents requiring this functionality may be better off using XML or
-another markup system.
-
-This argument comes up regularly when pushing the envelope of
-reStructuredText syntax.  I think it's a useful argument in that it
-provides a check on creeping featurism.  In many cases, the resulting
-verbosity produces such unreadable plaintext that there's a natural
-desire *not* to use it unless absolutely necessary.  It's a matter of
-finding the right balance.
-
-
-Syntax for Interpreted Text Role Bindings
-=========================================
-
-The following syntax (idea from Jeffrey C. Jacobs) could be used to
-associate directives with roles::
-
-    .. :rewrite: class:: rewrite
-
-    `She wore ribbons in her hair and it lay with streaks of
-    grey`:rewrite:
-
-The syntax is similar to that of substitution declarations, and the
-directive/role association may resolve implementation issues.  The
-semantics, ramifications, and implementation details would need to be
-worked out.
-
-The example above would implement the "rewrite" role as adding a
-``class="rewrite"`` attribute to the interpreted text ("inline"
-element).  The stylesheet would then pick up on the "class" attribute
-to do the actual formatting.
-
-The advantage of the new syntax would be flexibility.  Uses other than
-"class" may present themselves.  The disadvantage is complexity:
-having to implement new syntax for a relatively specialized operation,
-and having new semantics in existing directives ("class::" would do
-something different).
-
-The `"role" directive`__ has been implemented.
-
-__ ../../ref/rst/directives.html#role
-
-
-Character Processing
-====================
-
-Several people have suggested adding some form of character processing
-to reStructuredText:
-
-* Some sort of automated replacement of ASCII sequences:
-
-  - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash).
-  - Convert quotes to curly quote entities.  (Essentially impossible
-    for HTML?  Unnecessary for TeX.)
-  - Various forms of ``:-)`` to smiley icons.
-  - ``"\ "`` to &nbsp;.  Problem with line-wrapping though: it could
-    end up escaping the newline.
-  - Escaped newlines to <BR>.
-  - Escaped period or quote or dash as a disappearing catalyst to
-    allow character-level inline markup?
-
-* XML-style character entities, such as "&copy;" for the copyright
-  symbol.
-
-Docutils has no need of a character entity subsystem.  Supporting
-Unicode and text encodings, character entities should be directly
-represented in the text: a copyright symbol should be represented by
-the copyright symbol character.  If this is not possible in an
-authoring environment, a pre-processing stage can be added, or a table
-of substitution definitions can be devised.
-
-A "unicode" directive has been implemented to allow direct
-specification of esoteric characters.  In combination with the
-substitution construct, "include" files defining common sets of
-character entities can be defined and used.  `A set of character
-entity set definition files have been defined`__ (`tarball`__).
-There's also `a description and instructions for use`__.
-
-__ http://docutils.sf.net/tmp/charents/
-__ http://docutils.sf.net/tmp/charents.tgz
-__ http://docutils.sf.net/tmp/charents/README.html
-
-To allow for `character-level inline markup`_, a limited form of
-character processing has been added to the spec and parser: escaped
-whitespace characters are removed from the processed document.  Any
-further character processing will be of this functional type, rather
-than of the character-encoding type.
-
-.. _character-level inline markup:
-   ../../ref/rst/restructuredtext.html#character-level-inline-markup
-
-* Directive idea::
-
-      .. text-replace:: "pattern" "replacement"
-
-  - Support Unicode "U+XXXX" codes.
-  - Support regexps, perhaps with alternative "regexp-replace"
-    directive.
-  - Flags for regexps; ":flags:" option, or individuals.
-  - Specifically, should the default be case-sensistive or
-    -insensitive?
-
-
-Page Or Line Breaks
-===================
-
-* Should ^L (or something else in reST) be defined to mean
-  force/suggest page breaks in whatever output we have?
-
-  A "break" or "page-break" directive would be easy to add.  A new
-  doctree element would be required though (perhaps "break").  The
-  final behavior would be up to the Writer.  The directive argument
-  could be one of page/column/recto/verso for added flexibility.
-
-  Currently ^L (Python's ``\f``) characters are treated as whitespace.
-  They're converted to single spaces, actually, as are vertical tabs
-  (^K, Python's ``\v``).  It would be possible to recognize form feeds
-  as markup, but it requires some thought and discussion first.  Are
-  there any downsides?  Many editing environments do not allow the
-  insertion of control characters.  Will it cause any harm?  It would
-  be useful as a shorthand for the directive.
-
-  It's common practice to use ^L before Emacs "Local Variables"
-  lists::
-
-      ^L
-      ..
-         Local Variables:
-         mode: indented-text
-         indent-tabs-mode: nil
-         sentence-end-double-space: t
-         fill-column: 70
-         End:
-
-  These are already present in many PEPs and Docutils project
-  documents.  From the Emacs manual (info):
-
-      A "local variables list" goes near the end of the file, in the
-      last page.  (It is often best to put it on a page by itself.)
-
-  It would be unfortunate if this construct caused a final blank page
-  to be generated (for those Writers that recognize the page breaks).
-  We'll have to add a transform that looks for a "break" plus zero or
-  more comments at the end of a document, and removes them.
-
-  Probably a bad idea because there is no such thing as a page in a
-  generic document format.
-
-* Could the "break" concept above be extended to inline forms?
-  E.g. "^L" in the middle of a sentence could cause a line break.
-  Only recognize it at the end of a line (i.e., ``\f\n``)?
-
-  Or is formfeed inappropriate?  Perhaps vertical tab (``\v``), but
-  even that's a stretch.  Can't use carriage returns, since they're
-  commonly used for line endings.
-
-  Probably a bad idea as well because we do not want to use control
-  characters for well-readable and well-writable markup, and after all
-  we have the line block syntax for line breaks.
-
-
-Superscript Markup
-==================
-
-Add ``^superscript^`` inline markup?  The only common non-markup uses
-of "^" I can think of are as short hand for "superscript" itself and
-for describing control characters ("^C to cancel").  The former
-supports the proposed syntax, and it could be argued that the latter
-ought to be literal text anyhow (e.g. "``^C`` to cancel").
-
-However, superscripts are seldom needed, and new syntax would break
-existing documents.  When it's needed, the ``:superscript:``
-(``:sup:``) role can we used as well.
-
-
-Code Execution
-==============
-
-Add the following directives?
-
-- "exec": Execute Python code & insert the results.  Call it
-  "python" to allow for other languages?
-
-- "system": Execute an ``os.system()`` call, and insert the results
-  (possibly as a literal block).  Definitely dangerous!  How to make
-  it safe?  Perhaps such processing should be left outside of the
-  document, in the user's production system (a makefile or a script or
-  whatever).  Or, the directive could be disabled by default and only
-  enabled with an explicit command-line option or config file setting.
-  Even then, an interactive prompt may be useful, such as:
-
-      The file.txt document you are processing contains a "system"
-      directive requesting that the ``sudo rm -rf /`` command be
-      executed.  Allow it to execute?  (y/N)
-
-- "eval": Evaluate an expression & insert the text.  At parse
-  time or at substitution time?  Dangerous?  Perhaps limit to canned
-  macros; see text.date_.
-
-  .. _text.date: ../todo.html#text-date
-
-It's too dangerous (or too complicated in the case of "eval").  We do
-not want to have such things in the core.
-
-
-``encoding`` Directive
-======================
-
-Add an "encoding" directive to specify the character encoding of the
-input data?  Not a good idea for the following reasons:
-
-- When it sees the directive, the parser will already have read the
-  input data, and encoding determination will already have been done.
-
-- If a file with an "encoding" directive is edited and saved with
-  a different encoding, the directive may cause data corruption.
-
-
-Support for Annotations
-=======================
-
-Add an "annotation" role, as the equivalent of the HTML "title"
-attribute?  This is secondary information that may "pop up" when the
-pointer hovers over the main text.  A corresponding directive would be
-required to associate annotations with the original text (by name, or
-positionally as in anonymous targets?).
-
-There have not been many requests for such feature, though.  Also,
-cluttering WYSIWYG plaintext with annotations may not seem like a good
-idea, and there is no "tool tip" in formats other than HTML.
-
-
-``term`` Role
-=============
-
-Add a "term" role for unfamiliar or specialized terminology?  Probably
-not; there is no real use case, and emphasis is enough for most cases.
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   End:
diff --git a/docutils/docs/dev/rst/problems.txt b/docutils/docs/dev/rst/problems.txt
deleted file mode 100644
index bc0101cbf..000000000
--- a/docutils/docs/dev/rst/problems.txt
+++ /dev/null
@@ -1,872 +0,0 @@
-==============================
- Problems With StructuredText
-==============================
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: This document has been placed in the public domain.
-
-There are several problems, unresolved issues, and areas of
-controversy within StructuredText_ (Classic and Next Generation).  In
-order to resolve all these issues, this analysis brings all of the
-issues out into the open, enumerates all the alternatives, and
-proposes solutions to be incorporated into the reStructuredText_
-specification.
-
-
-.. contents::
-
-
-Formal Specification
-====================
-
-The description in the original StructuredText.py has been criticized
-for being vague.  For practical purposes, "the code *is* the spec."
-Tony Ibbs has been working on deducing a `detailed description`_ from
-the documentation and code of StructuredTextNG_.  Edward Loper's
-STMinus_ is another attempt to formalize a spec.
-
-For this kind of a project, the specification should always precede
-the code.  Otherwise, the markup is a moving target which can never be
-adopted as a standard.  Of course, a specification may be revised
-during lifetime of the code, but without a spec there is no visible
-control and thus no confidence.
-
-
-Understanding and Extending the Code
-====================================
-
-The original StructuredText_ is a dense mass of sparsely commented
-code and inscrutable regular expressions.  It was not designed to be
-extended and is very difficult to understand.  StructuredTextNG_ has
-been designed to allow input (syntax) and output extensions, but its
-documentation (both internal [comments & docstrings], and external) is
-inadequate for the complexity of the code itself.
-
-For reStructuredText to become truly useful, perhaps even part of
-Python's standard library, it must have clear, understandable
-documentation and implementation code.  For the implementation of
-reStructuredText to be taken seriously, it must be a sterling example
-of the potential of docstrings; the implementation must practice what
-the specification preaches.
-
-
-Section Structure via Indentation
-=================================
-
-Setext_ required that body text be indented by 2 spaces.  The original
-StructuredText_ and StructuredTextNG_ require that section structure
-be indicated through indentation, as "inspired by Python".  For
-certain structures with a very limited, local extent (such as lists,
-block quotes, and literal blocks), indentation naturally indicates
-structure or hierarchy.  For sections (which may have a very large
-extent), structure via indentation is unnecessary, unnatural and
-ambiguous.  Rather, the syntax of the section title *itself* should
-indicate that it is a section title.
-
-The original StructuredText states that "A single-line paragraph whose
-immediately succeeding paragraphs are lower level is treated as a
-header." Requiring indentation in this way is:
-
-- Unnecessary.  The vast majority of docstrings and standalone
-  documents will have no more than one level of section structure.
-  Requiring indentation for such docstrings is unnecessary and
-  irritating.
-
-- Unnatural.  Most published works use title style (type size, face,
-  weight, and position) and/or section/subsection numbering rather
-  than indentation to indicate hierarchy.  This is a tradition with a
-  very long history.
-
-- Ambiguous.  A StructuredText header is indistinguishable from a
-  one-line paragraph followed by a block quote (precluding the use of
-  block quotes).  Enumerated section titles are ambiguous (is it a
-  header? is it a list item?).  Some additional adornment must be
-  required to confirm the line's role as a title, both to a parser and
-  to the human reader of the source text.
-
-Python's use of significant whitespace is a wonderful (if not
-original) innovation, however requiring indentation in ordinary
-written text is hypergeneralization.
-
-reStructuredText_ indicates section structure through title adornment
-style (as exemplified by this document).  This is far more natural.
-In fact, it is already in widespread use in plain text documents,
-including in Python's standard distribution (such as the toplevel
-README_ file).
-
-
-Character Escaping Mechanism
-============================
-
-No matter what characters are chosen for markup, some day someone will
-want to write documentation *about* that markup or using markup
-characters in a non-markup context.  Therefore, any complete markup
-language must have an escaping or encoding mechanism.  For a
-lightweight markup system, encoding mechanisms like SGML/XML's '&ast;'
-are out.  So an escaping mechanism is in.  However, with carefully
-chosen markup, it should be necessary to use the escaping mechanism
-only infrequently.
-
-reStructuredText_ needs an escaping mechanism: a way to treat
-markup-significant characters as the characters themselves.  Currently
-there is no such mechanism (although ZWiki uses '!').  What are the
-candidates?
-
-1. ``!``
-   (http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping)
-2. ``\``
-3. ``~``
-4. doubling of characters
-
-The best choice for this is the backslash (``\``).  It's "the single
-most popular escaping character in the world!", therefore familiar and
-unsurprising.  Since characters only need to be escaped under special
-circumstances, which are typically those explaining technical
-programming issues, the use of the backslash is natural and
-understandable.  Python docstrings can be raw (prefixed with an 'r',
-as in 'r""'), which would obviate the need for gratuitous doubling-up
-of backslashes.
-
-(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash
-escapes, saying, "'nuff said.  Backslash it is." Although neither
-legally binding nor irrevocable nor any kind of guarantee of anything,
-it is a good sign.)
-
-The rule would be: An unescaped backslash followed by any markup
-character escapes the 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 an "escaped backslash," two backslashes in
-a row.
-
-A carefully constructed set of recognition rules for inline markup
-will obviate the need for backslash-escapes in almost all cases; see
-`Delimitation of Inline Markup`_ below.
-
-When an expression (requiring backslashes and other characters used
-for markup) becomes too complicated and therefore unreadable, a
-literal block may be used instead.  Inside literal blocks, no markup
-is recognized, therefore backslashes (for the purpose of escaping
-markup) become unnecessary.
-
-We could allow backslashes preceding non-markup characters to remain
-in the output.  This would make describing regular expressions and
-other uses of backslashes easier.  However, this would complicate the
-markup rules and would be confusing.
-
-
-Blank Lines in Lists
-====================
-
-Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13)
-is the ability to write lists without requiring blank lines between
-items.  In docstrings, space is at a premium.  Authors want to convey
-their API or usage information in as compact a form as possible.
-StructuredText_ requires blank lines between all body elements,
-including list items, even when boundaries are obvious from the markup
-itself.
-
-In reStructuredText, blank lines are optional between list items.
-However, in order to eliminate ambiguity, a blank line is required
-before the first list item and after the last.  Nested lists also
-require blank lines before the list start and after the list end.
-
-
-Bullet List Markup
-==================
-
-StructuredText_ includes 'o' as a bullet character.  This is dangerous
-and counter to the language-independent nature of the markup.  There
-are many languages in which 'o' is a word.  For example, in Spanish::
-
-    Llamame a la casa
-    o al trabajo.
-
-    (Call me at home or at work.)
-
-And in Japanese (when romanized)::
-
-    Senshuu no doyoubi ni tegami
-    o kakimashita.
-
-    ([I] wrote a letter on Saturday last week.)
-
-If a paragraph containing an 'o' word wraps such that the 'o' is the
-first text on a line, or if a paragraph begins with such a word, it
-could be misinterpreted as a bullet list.
-
-In reStructuredText_, 'o' is not used as a bullet character.  '-',
-'*', and '+' are the possible bullet characters.
-
-
-Enumerated List Markup
-======================
-
-StructuredText enumerated lists are allowed to begin with numbers and
-letters followed by a period or right-parenthesis, then whitespace.
-This has surprising consequences for writing styles.  For example,
-this is recognized as an enumerated list item by StructuredText::
-
-    Mr. Creosote.
-
-People will write enumerated lists in all different ways.  It is folly
-to try to come up with the "perfect" format for an enumerated list,
-and limit the docstring parser's recognition to that one format only.
-
-Rather, the parser should recognize a variety of enumerator styles.
-It is also recommended that the enumerator of the first list item be
-ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be
-able to begin a list at an arbitrary enumeration.
-
-An initial idea was to require two or more consistent enumerated list
-items in a row.  This idea proved impractical and was dropped.  In
-practice, the presence of a proper enumerator is enough to reliably
-recognize an enumerated list item; any ambiguities are reported by the
-parser.  Here's the original idea for posterity:
-
-    The parser should recognize a variety of enumerator styles, mark
-    each block as a potential enumerated list item (PELI), and
-    interpret the enumerators of adjacent PELIs to decide whether they
-    make up a consistent enumerated list.
-
-    If a PELI is labeled with a "1.", and is immediately followed by a
-    PELI labeled with a "2.", we've got an enumerated list.  Or "(A)"
-    followed by "(B)".  Or "i)" followed by "ii)", etc.  The chances
-    of accidentally recognizing two adjacent and consistently labeled
-    PELIs, are acceptably small.
-
-    For an enumerated list to be recognized, the following must be
-    true:
-
-    - the list must consist of multiple adjacent list items (2 or
-      more)
-    - the enumerators must all have the same format
-    - the enumerators must be sequential
-
-
-Definition List Markup
-======================
-
-StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on
-the first line of a paragraph to indicate a definition list item.  The
-' -- ' serves to separate the term (on the left) from the definition
-(on the right).
-
-Many people use ' -- ' as an em-dash in their text, conflicting with
-the StructuredText usage.  Although the Chicago Manual of Style says
-that spaces should not be used around an em-dash, Peter Funk pointed
-out that this is standard usage in German (according to the Duden, the
-official German reference), and possibly in other languages as well.
-The widespread use of ' -- ' precludes its use for definition lists;
-it would violate the "unsurprising" criterion.
-
-A simpler, and at least equally visually distinctive construct
-(proposed by Guido van Rossum, who incidentally is a frequent user of
-' -- ') would do just as well::
-
-    term 1
-        Definition.
-
-    term 2
-        Definition 2, paragraph 1.
-
-        Definition 2, paragraph 2.
-
-A reStructuredText definition list item consists of a term and a
-definition.  A term is a simple one-line paragraph.  A definition is a
-block indented relative to the term, and may contain multiple
-paragraphs and other body elements.  No blank line precedes a
-definition (this distinguishes definition lists from block quotes).
-
-
-Literal Blocks
-==============
-
-The StructuredText_ specification has literal blocks indicated by
-'example', 'examples', or '::' ending the preceding paragraph.  STNG
-only recognizes '::'; 'example'/'examples' are not implemented.  This
-is good; it fixes an unnecessary language dependency.  The problem is
-what to do with the sometimes- unwanted '::'.
-
-In reStructuredText_ '::' at the end of a paragraph indicates that
-subsequent *indented* blocks are treated as literal text.  No further
-markup interpretation is done within literal blocks (not even
-backslash-escapes).  If the '::' is preceded by whitespace, '::' is
-omitted from the output; if '::' was the sole content of a paragraph,
-the entire paragraph is removed (no 'empty' paragraph remains).  If
-'::' is preceded by a non-whitespace character, '::' is replaced by
-':' (i.e., the extra colon is removed).
-
-Thus, a section could begin with a literal block as follows::
-
-    Section Title
-    -------------
-
-    ::
-
-        print "this is example literal"
-
-
-Tables
-======
-
-The table markup scheme in classic StructuredText was horrible.  Its
-omission from StructuredTextNG is welcome, and its markup will not be
-repeated here.  However, tables themselves are useful in
-documentation.  Alternatives:
-
-1. This format is the most natural and obvious.  It was independently
-   invented (no great feat of creation!), and later found to be the
-   format supported by the `Emacs table mode`_::
-
-       +------------+------------+------------+--------------+
-       |  Header 1  |  Header 2  |  Header 3  |  Header 4    |
-       +============+============+============+==============+
-       |  Column 1  |  Column 2  | Column 3 & 4 span (Row 1) |
-       +------------+------------+------------+--------------+
-       |    Column 1 & 2 span    |  Column 3  | - Column 4   |
-       +------------+------------+------------+ - Row 2 & 3  |
-       |      1     |      2     |      3     | - span       |
-       +------------+------------+------------+--------------+
-
-   Tables are described with a visual outline made up of the
-   characters '-', '=', '|', and '+':
-
-   - The hyphen ('-') is used for horizontal lines (row separators).
-   - The equals sign ('=') is optionally used as a header separator
-     (as of version 1.5.24, this is not supported by the Emacs table
-     mode).
-   - The vertical bar ('|') is used for for vertical lines (column
-     separators).
-   - The plus sign ('+') is used for intersections of horizontal and
-     vertical lines.
-
-   Row and column spans are possible simply by omitting the column or
-   row separators, respectively.  The header row separator must be
-   complete; in other words, a header cell may not span into the table
-   body.  Each cell contains body elements, and may have multiple
-   paragraphs, lists, etc.  Initial spaces for a left margin are
-   allowed; the first line of text in a cell determines its left
-   margin.
-
-2. Below is a simpler table structure.  It may be better suited to
-   manual input than alternative #1, but there is no Emacs editing
-   mode available.  One disadvantage is that it resembles section
-   titles; a one-column table would look exactly like section &
-   subsection titles. ::
-
-       ============ ============ ============ ==============
-         Header 1     Header 2     Header 3     Header 4
-       ============ ============ ============ ==============
-         Column 1     Column 2    Column 3 & 4 span (Row 1)
-       ------------ ------------ ---------------------------
-           Column 1 & 2 span       Column 3    - Column 4
-       ------------------------- ------------  - Row 2 & 3
-             1            2            3       - span
-       ============ ============ ============ ==============
-
-   The table begins with a top border of equals signs with a space at
-   each column boundary (regardless of spans).  Each row is
-   underlined.  Internal row separators are underlines of '-', with
-   spaces at column boundaries.  The last of the optional head rows is
-   underlined with '=', again with spaces at column boundaries.
-   Column spans have no spaces in their underline.  Row spans simply
-   lack an underline at the row boundary.  The bottom boundary of the
-   table consists of '=' underlines.  A blank line is required
-   following a table.
-
-3. A minimalist alternative is as follows::
-
-       ====  =====  ========  ========  =======  ====  =====  =====
-       Old State    Input     Action             New State    Notes
-       -----------  --------  -----------------  -----------
-       ids   types  new type  sys.msg.  dupname  ids   types
-       ====  =====  ========  ========  =======  ====  =====  =====
-       --    --     explicit  --        --       new   True
-       --    --     implicit  --        --       new   False
-       None  False  explicit  --        --       new   True
-       old   False  explicit  implicit  old      new   True
-       None  True   explicit  explicit  new      None  True
-       old   True   explicit  explicit  new,old  None  True   [1]
-       None  False  implicit  implicit  new      None  False
-       old   False  implicit  implicit  new,old  None  False
-       None  True   implicit  implicit  new      None  True
-       old   True   implicit  implicit  new      old   True
-       ====  =====  ========  ========  =======  ====  =====  =====
-
-   The table begins with a top border of equals signs with one or more
-   spaces at each column boundary (regardless of spans).  There must
-   be at least two columns in the table (to differentiate it from
-   section headers).  Each line starts a new row.  The rightmost
-   column is unbounded; text may continue past the edge of the table.
-   Each row/line must contain spaces at column boundaries, except for
-   explicit column spans.  Underlines of '-' can be used to indicate
-   column spans, but should be used sparingly if at all.  Lines
-   containing column span underlines may not contain any other text.
-   The last of the optional head rows is underlined with '=', again
-   with spaces at column boundaries.  The bottom boundary of the table
-   consists of '=' underlines.  A blank line is required following a
-   table.
-
-   This table sums up the features.  Using all the features in such a
-   small space is not pretty though::
-
-       ========  ========  ========
-                 Header 2 & 3 Span
-                 ------------------
-       Header 1  Header 2  Header 3
-       ========  ========  ========
-       Each      line is   a new row.
-       Each row  consists  of one line only.
-       Row       spans     are not possible.
-       The last  column    may spill over to the right.
-       Column spans are possible with an underline joining columns.
-       ----------------------------
-       The span  is        limited to the row above the underline.
-       ========  ========  ========
-
-4. As a variation of alternative 3, bullet list syntax in the first
-   column could be used to indicate row starts.  Multi-line rows are
-   possible, but row spans are not.  For example::
-
-       ===== =====
-       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 paragraph of row 3,
-             column 2
-       ===== =====
-
-   Column spans would be indicated on the line after the last line of
-   the row.  To indicate a real bullet list within a first-column
-   cell, simply nest the bullets.
-
-5. In a further variation, we could simply assume that whitespace in
-   the first column implies a multi-line row; the text in other
-   columns is continuation text.  For example::
-
-       ===== =====
-       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 paragraph of row 3,
-             column 2
-       ===== =====
-
-   Limitations of this approach:
-
-   - Cells in the first column are limited to one line of text.
-
-   - Cells in the first column *must* contain some text; blank cells
-     would lead to a misinterpretation.  An empty comment ("..") is
-     sufficient.
-
-6. Combining alternative 3 and 4, a bullet list in the first column
-   could mean multi-line rows, and no bullet list means single-line
-   rows only.
-
-Alternatives 1 and 5 has been adopted by reStructuredText.
-
-
-Delimitation of Inline Markup
-=============================
-
-StructuredText specifies that inline markup must begin with
-whitespace, precluding such constructs as parenthesized or quoted
-emphatic text::
-
-    "**What?**" she cried.  (*exit stage left*)
-
-The `reStructuredText markup specification`_ allows for such
-constructs and disambiguates inline markup through a set of
-recognition rules.  These recognition rules define the context of
-markup start-strings and end-strings, allowing markup characters to be
-used in most non-markup contexts without a problem (or a backslash).
-So we can say, "Use asterisks (*) around words or phrases to
-*emphasisze* them." The '(*)' will not be recognized as markup.  This
-reduces the need for markup escaping to the point where an escape
-character is *almost* (but not quite!) unnecessary.
-
-
-Underlining
-===========
-
-StructuredText uses '_text_' to indicate underlining.  To quote David
-Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring
-grammar: a very revised proposal":
-
-    The tagging of underlined text with _'s is suboptimal.  Underlines
-    shouldn't be used from a typographic perspective (underlines were
-    designed to be used in manuscripts to communicate to the
-    typesetter that the text should be italicized -- no well-typeset
-    book ever uses underlines), and conflict with double-underscored
-    Python variable names (__init__ and the like), which would get
-    truncated and underlined when that effect is not desired.  Note
-    that while *complete* markup would prevent that truncation
-    ('__init__'), I think of docstring markups much like I think of
-    type annotations -- they should be optional and above all do no
-    harm.  In this case the underline markup does harm.
-
-Underlining is not part of the reStructuredText specification.
-
-
-Inline Literals
-===============
-
-StructuredText's markup for inline literals (text left as-is,
-verbatim, usually in a monospaced font; as in HTML <TT>) is single
-quotes ('literals').  The problem with single quotes is that they are
-too often used for other purposes:
-
-- Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'.";
-
-- Quoting text:
-
-      First Bruce: "Well Bruce, I heard the prime minister use it.
-      'S'hot enough to boil a monkey's bum in 'ere your Majesty,' he
-      said, and she smiled quietly to herself."
-
-  In the UK, single quotes are used for dialogue in published works.
-
-- String literals: s = ''
-
-Alternatives::
-
-    'text'    \'text\'    ''text''    "text"    \"text\"    ""text""
-    #text#     @text@      `text`     ^text^    ``text''    ``text``
-
-The examples below contain inline literals, quoted text, and
-apostrophes.  Each example should evaluate to the following HTML::
-
-    Some <TT>code</TT>, with a 'quote', "double", ain't it grand?
-    Does <TT>a[b] = 'c' + "d" + `2^3`</TT> work?
-
-    0. Some code, with a quote, double, ain't it grand?
-       Does a[b] = 'c' + "d" + `2^3` work?
-    1. Some 'code', with a \'quote\', "double", ain\'t it grand?
-       Does 'a[b] = \'c\' + "d" + `2^3`' work?
-    2. Some \'code\', with a 'quote', "double", ain't it grand?
-       Does \'a[b] = 'c' + "d" + `2^3`\' work?
-    3. Some ''code'', with a 'quote', "double", ain't it grand?
-       Does ''a[b] = 'c' + "d" + `2^3`'' work?
-    4. Some "code", with a 'quote', \"double\", ain't it grand?
-       Does "a[b] = 'c' + "d" + `2^3`" work?
-    5. Some \"code\", with a 'quote', "double", ain't it grand?
-       Does \"a[b] = 'c' + "d" + `2^3`\" work?
-    6. Some ""code"", with a 'quote', "double", ain't it grand?
-       Does ""a[b] = 'c' + "d" + `2^3`"" work?
-    7. Some #code#, with a 'quote', "double", ain't it grand?
-       Does #a[b] = 'c' + "d" + `2^3`# work?
-    8. Some @code@, with a 'quote', "double", ain't it grand?
-       Does @a[b] = 'c' + "d" + `2^3`@ work?
-    9. Some `code`, with a 'quote', "double", ain't it grand?
-       Does `a[b] = 'c' + "d" + \`2^3\`` work?
-    10. Some ^code^, with a 'quote', "double", ain't it grand?
-        Does ^a[b] = 'c' + "d" + `2\^3`^ work?
-    11. Some ``code'', with a 'quote', "double", ain't it grand?
-        Does ``a[b] = 'c' + "d" + `2^3`'' work?
-    12. Some ``code``, with a 'quote', "double", ain't it grand?
-        Does ``a[b] = 'c' + "d" + `2^3\``` work?
-
-Backquotes (#9 & #12) are the best choice.  They are unobtrusive and
-relatviely rarely used (more rarely than ' or ", anyhow).  Backquotes
-have the connotation of 'quotes', which other options (like carets,
-#10) don't.
-
-Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12)
-could be used for inline literals.  If single-backquotes are used for
-'interpreted text' (context-sensitive domain-specific descriptive
-markup) such as function name hyperlinks in Python docstrings, then
-double-backquotes could be used for absolute-literals, wherein no
-processing whatsoever takes place.  An advantage of double-backquotes
-would be that backslash-escaping would no longer be necessary for
-embedded single-backquotes; however, embedded double-backquotes (in an
-end-string context) would be illegal.  See `Backquotes in
-Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__.
-
-__ alternatives.html#backquotes-in-phrase-links
-__ alternatives.html
-
-Alternative choices are carets (#10) and TeX-style quotes (#11).  For
-examples of TeX-style quoting, see
-http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor.
-
-Some existing uses of backquotes:
-
-1. As a synonym for repr() in Python.
-2. For command-interpolation in shell scripts.
-3. Used as open-quotes in TeX code (and carried over into plaintext
-   by TeXies).
-
-The inline markup start-string and end-string recognition rules
-defined by the `reStructuredText markup specification`_ would allow
-all of these cases inside inline literals, with very few exceptions.
-As a fallback, literal blocks could handle all cases.
-
-Outside of inline literals, the above uses of backquotes would require
-backslash-escaping.  However, these are all prime examples of text
-that should be marked up with inline literals.
-
-If either backquotes or straight single-quotes are used as markup,
-TeX-quotes are too troublesome to support, so no special-casing of
-TeX-quotes should be done (at least at first).  If TeX-quotes have to
-be used outside of literals, a single backslash-escaped would suffice:
-\``TeX quote''.  Ugly, true, but very infrequently used.
-
-Using literal blocks is a fallback option which removes the need for
-backslash-escaping::
-
-    like this::
-
-        Here, we can do ``absolutely'' anything `'`'\|/|\ we like!
-
-No mechanism for inline literals is perfect, just as no escaping
-mechanism is perfect.  No matter what we use, complicated inline
-expressions involving the inline literal quote and/or the backslash
-will end up looking ugly.  We can only choose the least often ugly
-option.
-
-reStructuredText will use double backquotes for inline literals, and
-single backqoutes for interpreted text.
-
-
-Hyperlinks
-==========
-
-There are three forms of hyperlink currently in StructuredText_:
-
-1. (Absolute & relative URIs.)  Text enclosed by double quotes
-   followed by a colon, a URI, and concluded by punctuation plus white
-   space, or just white space, is treated as a hyperlink::
-
-       "Python":http://www.python.org/
-
-2. (Absolute URIs only.)  Text enclosed by double quotes followed by a
-   comma, one or more spaces, an absolute URI and concluded by
-   punctuation plus white space, or just white space, is treated as a
-   hyperlink::
-
-       "mail me", mailto:me@mail.com
-
-3. (Endnotes.)  Text enclosed by brackets link to an endnote at the
-   end of the document: at the beginning of the line, two dots, a
-   space, and the same text in brackets, followed by the end note
-   itself::
-
-       Please refer to the fine manual [GVR2001].
-
-       .. [GVR2001] Python Documentation, Release 2.1, van Rossum,
-          Drake, et al., http://www.python.org/doc/
-
-The problem with forms 1 and 2 is that they are neither intuitive nor
-unobtrusive (they break design goals 5 & 2).  They overload
-double-quotes, which are too often used in ordinary text (potentially
-breaking design goal 4).  The brackets in form 3 are also too common
-in ordinary text (such as [nested] asides and Python lists like [12]).
-
-Alternatives:
-
-1. Have no special markup for hyperlinks.
-
-2. A. Interpret and mark up hyperlinks as any contiguous text
-      containing '://' or ':...@' (absolute URI) or '@' (email
-      address) after an alphanumeric word.  To de-emphasize the URI,
-      simply enclose it in parentheses:
-
-          Python (http://www.python.org/)
-
-   B. Leave special hyperlink markup as a domain-specific extension.
-      Hyperlinks in ordinary reStructuredText documents would be
-      required to be standalone (i.e. the URI text inline in the
-      document text).  Processed hyperlinks (where the URI text is
-      hidden behind the link) are important enough to warrant syntax.
-
-3. The original Setext_ introduced a mechanism of indirect hyperlinks.
-   A source link word ('hot word') in the text was given a trailing
-   underscore::
-
-       Here is some text with a hyperlink_ built in.
-
-   The hyperlink itself appeared at the end of the document on a line
-   by itself, beginning with two dots, a space, the link word with a
-   leading underscore, whitespace, and the URI itself::
-
-       .. _hyperlink http://www.123.xyz
-
-   Setext used ``underscores_instead_of_spaces_`` for phrase links.
-
-With some modification, alternative 3 best satisfies the design goals.
-It has the advantage of being readable and relatively unobtrusive.
-Since each source link must match up to a target, the odd variable
-ending in an underscore can be spared being marked up (although it
-should generate a "no such link target" warning).  The only
-disadvantage is that phrase-links aren't possible without some
-obtrusive syntax.
-
-We could achieve phrase-links if we enclose the link text:
-
-1. in double quotes::
-
-       "like this"_
-
-2. in brackets::
-
-       [like this]_
-
-3. or in backquotes::
-
-       `like this`_
-
-Each gives us somewhat obtrusive markup, but that is unavoidable.  The
-bracketed syntax (#2) is reminiscent of links on many web pages
-(intuitive), although it is somewhat obtrusive.  Alternative #3 is
-much less obtrusive, and is consistent with interpreted text: the
-trailing underscore indicates the interpretation of the phrase, as a
-hyperlink.  #3 also disambiguates hyperlinks from footnote references.
-Alternative #3 wins.
-
-The same trailing underscore markup can also be used for footnote and
-citation references, removing the problem with ordinary bracketed text
-and Python lists::
-
-    Please refer to the fine manual [GVR2000]_.
-
-    .. [GVR2000] Python Documentation, van Rossum, Drake, et al.,
-       http://www.python.org/doc/
-
-The two-dots-and-a-space syntax was generalized by Setext for
-comments, which are removed from the (visible) processed output.
-reStructuredText uses this syntax for comments, footnotes, and link
-target, collectively termed "explicit markup".  For link targets, in
-order to eliminate ambiguity with comments and footnotes,
-reStructuredText specifies that a colon always follow the link target
-word/phrase.  The colon denotes 'maps to'.  There is no reason to
-restrict target links to the end of the document; they could just as
-easily be interspersed.
-
-Internal hyperlinks (links from one point to another within a single
-document) can be expressed by a source link as before, and a target
-link with a colon but no URI.  In effect, these targets 'map to' the
-element immediately following.
-
-As an added bonus, we now have a perfect candidate for
-reStructuredText directives, a simple extension mechanism: explicit
-markup containing a single word followed by two colons and whitespace.
-The interpretation of subsequent data on the directive line or
-following is directive-dependent.
-
-To summarize::
-
-    .. This is a comment.
-
-    .. The line below is an example of a directive.
-    .. version:: 1
-
-    This is a footnote [1]_.
-
-    This internal hyperlink will take us to the footnotes_ area below.
-
-    Here is a one-word_ external hyperlink.
-
-    Here is `a hyperlink phrase`_.
-
-    .. _footnotes:
-    .. [1] Footnote text goes here.
-
-    .. external hyperlink target mappings:
-    .. _one-word: http://www.123.xyz
-    .. _a hyperlink phrase: http://www.123.xyz
-
-The presence or absence of a colon after the target link
-differentiates an indirect hyperlink from a footnote, respectively.  A
-footnote requires brackets.  Backquotes around a target link word or
-phrase are required if the phrase contains a colon, optional
-otherwise.
-
-Below are examples using no markup, the two StructuredText hypertext
-styles, and the reStructuredText hypertext style.  Each example
-contains an indirect link, a direct link, a footnote/endnote, and
-bracketed text.  In HTML, each example should evaluate to::
-
-    <P>A <A HREF="http://spam.org">URI</A>, see <A HREF="#eggs2000">
-    [eggs2000]</A> (in Bacon [Publisher]).  Also see
-    <A HREF="http://eggs.org">http://eggs.org</A>.</P>
-
-    <P><A NAME="eggs2000">[eggs2000]</A> "Spam, Spam, Spam, Eggs,
-    Bacon, and Spam"</P>
-
-1. No markup::
-
-       A URI http://spam.org, see eggs2000 (in Bacon [Publisher]).
-       Also see http://eggs.org.
-
-       eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam"
-
-2. StructuredText absolute/relative URI syntax
-   ("text":http://www.url.org)::
-
-       A "URI":http://spam.org, see [eggs2000] (in Bacon [Publisher]).
-       Also see "http://eggs.org":http://eggs.org.
-
-       .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
-
-   Note that StructuredText does not recognize standalone URIs,
-   forcing doubling up as shown in the second line of the example
-   above.
-
-3. StructuredText absolute-only URI syntax
-   ("text", mailto:you@your.com)::
-
-       A "URI", http://spam.org, see [eggs2000] (in Bacon
-       [Publisher]).  Also see "http://eggs.org", http://eggs.org.
-
-       .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
-
-4. reStructuredText syntax::
-
-    4. A URI_, see [eggs2000]_ (in Bacon [Publisher]).
-       Also see http://eggs.org.
-
-       .. _URI: http:/spam.org
-       .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
-
-The bracketed text '[Publisher]' may be problematic with
-StructuredText (syntax 2 & 3).
-
-reStructuredText's syntax (#4) is definitely the most readable.  The
-text is separated from the link URI and the footnote, resulting in
-cleanly readable text.
-
-.. _StructuredText:
-   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
-.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _detailed description:
-   http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html
-.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html
-.. _StructuredTextNG:
-   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
-.. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/
-   python/python/dist/src/README
-.. _Emacs table mode: http://table.sourceforge.net/
-.. _reStructuredText Markup Specification:
-   ../../ref/rst/restructuredtext.html
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   End: