initial import from docstring.sf.net and structuredtext.sf.netgoodger

git-svn-id: http://svn.code.sf.net/p/docutils/code/branches/goodger@21 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 439 insertions, 305 deletions

diff --git a/docutils/docs/dev/semantics.txt b/docutils/docs/dev/semantics.txt
index 96d2d5644..f6ec09ebd 100644
--- a/docutils/docs/dev/semantics.txt
+++ b/docutils/docs/dev/semantics.txt
@@ -36,3 +36,12 @@ conventions which are understood by the Docutils.
 - Frederic Giacometti's "iPhrase Python documentation conventions" is
   an attachment to his Doc-SIG post of 2001-05-30
   (http://mail.python.org/pipermail/doc-sig/2001-May/001840.html).
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
diff --git a/docutils/docs/peps/pep-0287.txt b/docutils/docs/peps/pep-0287.txt
index f19354587..a3d4216d1 100644
--- a/docutils/docs/peps/pep-0287.txt
+++ b/docutils/docs/peps/pep-0287.txt
@@ -1,4 +1,4 @@
-PEP: 
+PEP: 287
 Title: reStructuredText Standard Docstring Format
 Version: $Revision$
 Last-Modified: $Date$
@@ -6,33 +6,87 @@ Author: goodger@users.sourceforge.net (David Goodger)
 Discussions-To: doc-sig@python.org
 Status: Draft
 Type: Informational
-Created: 2002-03-25
-Post-History: 
+Created: 25-Mar-2002
+Post-History: 02-Apr-2002
+Replaces: 216
 
 
 Abstract
 
-    This PEP proposes that the reStructuredText [1]_ markup be adopted
-    as the standard markup format for plaintext documentation in
-    Python docstrings, and (optionally) for PEPs and ancillary
-    documents as well.  reStructuredText is a rich and extensible yet
-    easy-to-read, what-you-see-is-what-you-get plaintext markup
-    syntax.
+    When plaintext hasn't been expressive enough for inline
+    documentation, Python programmers have sought out a format for
+    docstrings.  This PEP proposes that the reStructuredText markup
+    [1]_ be adopted as a standard markup format for structured
+    plaintext documentation in Python docstrings, and for PEPs and
+    ancillary documents as well.  reStructuredText is a rich and
+    extensible yet easy-to-read, what-you-see-is-what-you-get
+    plaintext markup syntax.
 
     Only the low-level syntax of docstrings is addressed here.  This
     PEP is not concerned with docstring semantics or processing at
-    all.
+    all.  Nor is it an attempt to deprecate pure plaintext docstrings,
+    which are always going to be legitimate.  The reStructuredText
+    markup is an alternative for those who want more expressive
+    docstrings.
+
+
+Benefits
+
+    Programmers are by nature a lazy breed.  We reuse code with
+    functions, classes, modules, and subsystems.  Through its
+    docstring syntax, Python allows us to document our code from
+    within.  The "holy grail" of the Python Documentation Special
+    Interest Group (Doc-SIG) [2]_ has been a markup syntax and toolset
+    to allow auto-documentation, where the docstrings of Python
+    systems can be extracted in context and processed into useful,
+    high-quality documentation for multiple purposes.
+
+    Document markup languages have three groups of customers: the
+    authors who write the documents, the software systems that process
+    the data, and the readers, who are the final consumers and the
+    most important group.  Most markups are designed for the authors
+    and software systems; readers are only meant to see the processed
+    form, either on paper or via browser software.  ReStructuredText
+    is different: it is intended to be easily readable in source form,
+    without prior knowledge of the markup.   ReStructuredText) is
+    entirely readable in plaintext format, and many of the markup
+    forms match common usage (e.g., ``*emphasis*``), so it reads quite
+    naturally.  Yet it is rich enough to produce complex documents,
+    and extensible so that there are few limits.  Of course, to write
+    reStructuredText documents prior knowledge is required.
+
+    The reStructuredText parser is available now.  The Docutils
+    project is at the point where standalone reStructuredText
+    documents can be converted to HTML; other output format writers
+    will become available over time.  Work is progressing on a Python
+    source "Reader" which will implement auto-documentation.  Authors
+    of existing auto-documentation tools are encouraged to integrate
+    the reStructuredText parser into their projects, or better yet, to
+    join forces to produce a world-class toolset for the Python
+    standard library.
+
+    Tools will become available in the near future, which will allow
+    programmers to generate HTML for online help, XML for multiple
+    purposes, and perhaps eventually PDF/DocBook/LaTeX for printed
+    documentation, essentially "for free" from the existing
+    docstrings.  The adoption of a standard will, at the very least,
+    benefit docstring processing tools by preventing further
+    "reinventing the wheel".
+
+    Eventually PyDoc, the one existing standard auto-documentation
+    tool, could have reStructuredText support added.  In the interim
+    it will have no problem with reStructuredText markup, since it
+    treats all docstrings as plaintext.
 
 
 Goals
 
     These are the generally accepted goals for a docstring format, as
-    discussed in the Python Documentation Special Interest Group
-    (Doc-SIG) [2]_:
+    discussed in the Doc-SIG:
 
-    1. It must be easy to type with any standard text editor.
+    1. It must be readable in source form by the casual observer.
 
-    2. It must be readable to the casual observer.
+    2. It must be easy to type with any standard text editor.
 
     3. It must not need to contain information which can be deduced
        from parsing the module.
@@ -43,21 +97,23 @@ Goals
     5. It must be possible to write a module's entire documentation in
        docstrings, without feeling hampered by the markup language.
 
-    [[Are these in fact the goals of the Doc-SIG members?  Anything to
-    add?]]
-
     reStructuredText meets and exceeds all of these goals, and sets
     its own goals as well, even more stringent.  See "Features" below.
 
     The goals of this PEP are as follows:
 
-    1. To establish a standard docstring format by attaining
-       "accepted" status (Python community consensus; BDFL
-       pronouncement). Once reStructuredText is a Python standard, all
-       effort can be focused on tools instead of arguing for a
-       standard.  Python needs a standard set of documentation tools.
+    1. To establish reStructuredText as a standard structured
+       plaintext format for docstrings (inline documentation of Python
+       modules and packages), PEPs, README-type files and other
+       standalone documents.  "Accepted" status will be sought through
+       Python community consensus and eventual BDFL pronouncement.
+
+       Please note that reStructuredText is being proposed as *a*
+       standard, not *the only* standard.  Its use will be entirely
+       optional.  Those who don't want to use it need not.
 
-    2. To address any related concerns raised by the Python community.
+    2. To solicit and address any related concerns raised by the
+       Python community.
 
     3. To encourage community support.  As long as multiple competing
        markups are out there, the development community remains
@@ -68,47 +124,40 @@ Goals
        projects.  It is hoped that interested developers will join
        forces and work on a joint/merged/common implementation.
 
-    5. (Optional.)  To adopt reStructuredText as the standard markup
-       for PEPs.  One or both of the following strategies may be
-       applied:
+    Once reStructuredText is a Python standard, effort can be focused
+    on tools instead of arguing for a standard.  Python needs a
+    standard set of documentation tools.
 
-       a) Keep the existing PEP section structure constructs (one-line
-          section headers, indented body text).  Subsections can either
-          be forbidden or supported with underlined headers in the
-          indented body text.
+    With regard to PEPs, one or both of the following strategies may
+    be applied:
 
-       b) Replace the PEP section structure constructs with the
-          reStructuredText syntax.  Section headers will require
-          underlines, subsections will be supported out of the box, and
-          body text need not be indented (except for block quotes).
+    a) Keep the existing PEP section structure constructs (one-line
+       section headers, indented body text).  Subsections can
+       either be forbidden or supported with underlined headers in
+       the indented body text.
 
-       Support for RFC822 headers will be added to the
-       reStructuredText parser (unambiguous given a specific context:
-       the first contiguous block of a PEP document).  It may be
-       desired to concretely specify what over/underline styles are
-       allowed for PEP section headers, for uniformity.
+    b) Replace the PEP section structure constructs with the
+       reStructuredText syntax.  Section headers will require
+       underlines, subsections will be supported out of the box,
+       and body text need not be indented (except for block
+       quotes).
 
-    6. (Optional.)  To adopt reStructuredText as the standard markup
-       for README-type files and other standalone documents in the
-       Python distribution.
+    Support for RFC 2822 headers will be added to the reStructuredText
+    parser for PEPs (unambiguous given a specific context: the first
+    contiguous block of the document).  It may be desired to
+    concretely specify what over/underline styles are allowed for PEP
+    section headers, for uniformity.
 
 
 Rationale
 
-    The __doc__ attribute is called a documentation string, or
-    docstring.  It is often used to summarize the interface of the
-    module, class or function.  The lack of a standard syntax for
-    docstrings has hampered the development of standard tools for
-    extracting docstrings and transforming them into documentation in
-    standard formats (e.g., HTML, DocBook, TeX).  There have been a
-    number of proposed markup formats and variations, and many tools
-    tied to these proposals, but without a standard docstring format
-    they have failed to gain a strong following and/or floundered
-    half-finished.
-
-    The adoption of a standard will, at the very least, benefit
-    docstring processing tools by preventing further "reinventing the
-    wheel".
+    The lack of a standard syntax for docstrings has hampered the
+    development of standard tools for extracting and converting
+    docstrings into documentation in standard formats (e.g., HTML,
+    DocBook, TeX).  There have been a number of proposed markup
+    formats and variations, and many tools tied to these proposals,
+    but without a standard docstring format they have failed to gain a
+    strong following and/or floundered half-finished.
 
     Throughout the existence of the Doc-SIG, consensus on a single
     standard docstring format has never been reached.  A lightweight,
@@ -130,22 +179,27 @@ Rationale
     4. Implicit markup is aesthetically compatible with the clean and
        minimalist Python syntax.
 
-    Proposed alternatives have included:
+    Many alternative markups for docstrings have been proposed on the
+    Doc-SIG over the years; a representative sample is listed below.
+    Each is briefly analyzed in terms of the goals stated above.
+    Please note that this is *not* intended to be an exclusive list of
+    all existing markup systems; there are many other markups
+    (Texinfo, Doxygen, TIM, YODL, AFT, ...) which are not mentioned.
 
     - XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_
 
       XML and SGML are explicit, well-formed meta-languages suitable
       for all kinds of documentation.  XML is a variant of SGML.  They
-      are best used behind the scenes, because they are verbose,
-      difficult to type, and too cluttered to read comfortably as
-      source.  DocBook, HTML, and XHTML are all applications of SGML
-      and/or XML, and all share the same basic syntax and the same
-      shortcomings.
+      are best used behind the scenes, because to untrained eyes they
+      are verbose, difficult to type, and too cluttered to read
+      comfortably as source.  DocBook, HTML, and XHTML are all
+      applications of SGML and/or XML, and all share the same basic
+      syntax and the same shortcomings.
 
     - TeX [8]_
 
-      TeX is similar to XML/SGML in that it's explicit, not very easy
-      to write, and not easy for the uninitiated to read.
+      TeX is similar to XML/SGML in that it's explicit, but not very
+      easy to write, and not easy for the uninitiated to read.
 
     - Perl POD [9]_
 
@@ -161,10 +215,9 @@ Rationale
       Special comments before Java classes and functions serve to
       document the code.  A program to extract these, and turn them
       into HTML documentation is called javadoc, and is part of the
-      standard Java distribution.  However, the only output format
-      that is supported is HTML, and JavaDoc has a very intimate
-      relationship with HTML, using HTML tags for most markup.  Thus
-      it shares the readability problems of HTML.
+      standard Java distribution.  However, JavaDoc has a very
+      intimate relationship with HTML, using HTML tags for most
+      markup.  Thus it shares the readability problems of HTML.
 
     - Setext [11]_, StructuredText [12]_
 
@@ -186,7 +239,8 @@ Rationale
         requirements.
 
       - STexts have been sometimes surprising.  Bits of text are
-        marked up unexpectedly, leading to user frustration.
+        unexpectedly interpreted as being marked up, leading to user
+        frustration.
 
       - SText implementations have been buggy.
 
@@ -205,29 +259,31 @@ Rationale
     the SText idea, addressing all of the problems listed above.
 
 
-Features
-
-    Rather than repeating or summarizing the extensive
-    reStructuredText spec, please read the originals available from
-    http://structuredtext.sourceforge.net/spec/ (.txt & .html files).
-    Reading the documents in following order is recommended:
+Specification
 
-    - An Introduction to reStructuredText [13]_
+    The specification and user documentaton for reStructuredText is
+    quite extensive.  Rather than repeating or summarizing it all
+    here, links to the originals are provided.
 
-    - Problems With StructuredText [14]_ (optional, if you've used
-      StructuredText; it explains many markup decisions made)
+    Please first take a look at "A ReStructuredText Primer" [13]_, a
+    short and gentle introduction.  The "Quick reStructuredText" user
+    reference [14]_ quickly summarizes all of the markup constructs.
+    For complete and extensive details, the following documents
+    contain the full specification itself:
 
-    - reStructuredText Markup Specification [15]_
+    - An Introduction to reStructuredText [15]_
 
-    - A Record of reStructuredText Syntax Alternatives [16]_ (explains
-      markup decisions made independently of StructuredText)
+    - reStructuredText Markup Specification [16]_
 
     - reStructuredText Directives [17]_
 
-    There is also a "Quick reStructuredText" user reference [18]_.
+    In addition, "Problems With StructuredText" [18]_ explains many
+    markup decisions made with regards to StructuredText, and "A
+    Record of reStructuredText Syntax Alternatives" [19]_ records
+    markup decisions made independently.
 
-    A summary of features addressing often-raised docstring markup
-    concerns follows:
+
+Docstring-Significant Features
 
     - A markup escaping mechanism.
 
@@ -286,6 +342,8 @@ Features
           class Keeper(Storer):
 
               """
+              Keep data fresher longer.
+
               Extend `Storer`.  Class attribute `instances` keeps track
               of the number of `Keeper` objects instantiated.
               """
@@ -338,14 +396,15 @@ Features
       These are mostly used for extension syntax, such as
       "bibliographic field lists" (representing document metadata such
       as author, date, and version) and extension attributes for
-      directives (see below).  They may be used to implement docstring
-      semantics, such as identifying parameters, exceptions raised,
-      etc.; such usage is beyond the scope of this PEP.
+      directives (see below).  They may be used to implement
+      methodologies (docstring semantics), such as identifying
+      parameters, exceptions raised, etc.; such usage is beyond the
+      scope of this PEP.
 
-      A modified RFC822 syntax is used, with a colon *before* as well
-      as *after* the field name.  Field bodies are more versatile as
-      well; they may contain multiple field bodies (even nested field
-      lists).  For example::
+      A modified RFC 2822 syntax is used, with a colon *before* as
+      well as *after* the field name.  Field bodies are more versatile
+      as well; they may contain multiple field bodies (even nested
+      field lists).  For example::
 
           :Date: 2002-03-22
           :Version: 1
@@ -354,13 +413,9 @@ Features
               - Myself
               - I
 
-      Standard RFC822 header syntax cannot be used for this construct
-      because it is ambiguous.  A word followed by a colon at the
-      beginning of a line is common in written text.  However, with
-      the addition of a well-defined context, such as when a field
-      list invariably occurs at the beginning of a document (e.g.,
-      PEPs and email messages), standard RFC822 header syntax can be
-      used.
+      Standard RFC 2822 header syntax cannot be used for this
+      construct because it is ambiguous.  A word followed by a colon
+      at the beginning of a line is common in written text.
 
     - Markup extensibility: directives and substitutions.
 
@@ -379,7 +434,7 @@ Features
 
           The |biohazard| symbol must be used on containers used to
           dispose of medical waste.
-      
+
           .. |biohazard| image:: biohazard.png
 
     - Section structure markup.
@@ -403,205 +458,268 @@ Features
 
 Questions & Answers
 
-    Q: Is reStructuredText rich enough?
-
-    A: Yes, it is for most people.  If it lacks some construct that is
-       require for a specific application, it can be added via the
-       directive mechansism.  If a common construct has been
-       overlooked and a suitably readable syntax can be found, it can
-       be added to the specification and parser.
-
-    Q: Is reStructuredText *too* rich?
-
-    A: No.
-
-       Since the very beginning, whenever a markup syntax has been
-       proposed on the Doc-SIG, someone has complained about the lack
-       of support for some construct or other.  The reply was often
-       something like, "These are docstrings we're talking about, and
-       docstrings shouldn't have complex markup."  The problem is that
-       a construct that seems superfluous to one person may be
-       absolutely essential to another.
-
-       reStructuredText takes the opposite approach: it provides a
-       rich set of implicit markup constructs (plus a generic
-       extension mechanism for explicit markup), allowing for all
-       kinds of documents.  If the set of constructs is too rich for a
-       particular application, the unused constructs can either be
-       removed from the parser (via application-specific overrides) or
-       simply omitted by convention.
-
-    Q: Why not use indentation for section structure, like
-       StructuredText does?  Isn't it more "Pythonic"?
-
-    A: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG
-       post:
-
-           I still think that using indentation to indicate sectioning
-           is wrong.  If you look at how real books and other print
-           publications are laid out, you'll notice that indentation
-           is used frequently, but mostly at the intra-section level.
-           Indentation can be used to offset lists, tables,
-           quotations, examples, and the like.  (The argument that
-           docstrings are different because they are input for a text
-           formatter is wrong: the whole point is that they are also
-           readable without processing.)
-
-           I reject the argument that using indentation is Pythonic:
-           text is not code, and different traditions and conventions
-           hold.  People have been presenting text for readability for
-           over 30 centuries.  Let's not innovate needlessly.
-
-       See "Section Structure via Indentation" in "Problems With
-       StructuredText" [14 ]_ for further elaboration.
-
-    Q: Why use reStructuredText for PEPs?  What's wrong with the
-       existing standard?
-
-    A: The existing standard for PEPs is very limited in terms of
-       general expressibility, and referencing is especially lacking
-       for such a reference-rich document type.  PEPs are currently
-       converted into HTML, but the results (mostly monospaced text)
-       are less than attractive, and most of the value-added potential
-       of HTML is untapped.
-
-       Making reStructuredText the standard markup for PEPs will
-       enable much richer expression, including support for section
-       structure, inline markup, graphics, and tables.  In several
-       PEPs there are ASCII graphics diagrams, which are all that
-       plaintext documents can support.  Since PEPs are made available
-       in HTML form, the ability to include proper diagrams would be
-       immediately useful.
-
-       Current PEP practices allow for reference markers in the form
-       "[1]" in the text, and the footnotes/references themselves are
-       listed in a section toward the end of the document.  There is
-       currently no hyperlinking between the reference marker and the
-       footnote/reference itself (it would be possible to add this to
-       pep2html.py, but the "markup" as it stands is ambiguous and
-       mistakes would be inevitable).  A PEP with many references
-       (such as this one ;-) requires a lot of flipping back and
-       forth.  When revising a PEP, often new references are added or
-       unused references deleted.  It is painful to renumber the
-       references, since it has to be done in two places and can have
-       a cascading effect (insert a single new reference 1, and every
-       other reference has to be renumbered; always adding new
-       references to the end is suboptimal).  It is easy for
-       references to go out of sync.
-
-       PEPs use references for two purposes: simple URL references and
-       footnotes.  reStructuredText differentiates between the two.  A
-       PEP might contain references like this::
-
-           Abstract
-
-               This PEP proposes a adding frungible doodads [1] to the
-               core.  It extends PEP 9876 [2] via the BCA [3]
-               mechanism.
-
-           References and Footnotes
-
-               [1] http://www.doodads.org/frungible.html
-
-               [2] PEP 9876, Let's Hope We Never Get Here
-                   http://www.python.org/peps/pep-9876.html
-
-               [3] "Bogus Complexity Addition"
-
-       Reference 1 is a simple URL reference.  Reference 2 is a
-       footnote containing text and a URL.  Reference 3 is a footnote
-       containing text only.  Rewritten using reStructuredText, this
-       PEP could look like this::
-
-           Abstract
-           ========
-
-           This PEP proposes a adding `frungible doodads`_ to the
-           core.  It extends PEP 9876 [#pep9876] via the BCA [#]
-           mechanism.
-
-           .. _frungible doodads:
-              http://www.doodads.org/frungible.html
-
-           .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here
-
-           __ http://www.python.org/peps/pep-9876.html
-
-           .. [#] "Bogus Complexity Addition"
-
-       URLs and footnotes can be defined close to their references if
-       desired, making them easier to read in the source text, and
-       making the PEPs easier to revise.  The "References and
-       Footnotes" section can be auto-generated with a document tree
-       transform.  Footnotes from throughout the PEP would be gathered
-       and displayed under a standard header.  If URL references
-       should likewise be written out explicitly (in citation form),
-       another tree transform could be used.
-
-       URL references can be named ("frungible doodads"), and can be
-       referenced from multiple places in the document without
-       additional definitions.  When converted to HTML, references
-       will be replaced with inline hyperlinks (HTML <A> tags).  The
-       two footnotes are automatically numbered, so they will always
-       stay in sync.  The first footnote also contains an internal
-       reference name, "pep9876", so it's easier to see the connection
-       between reference and footnote in the source text.  Named
-       footnotes can be referenced multiple times, maintaining
-       consistent numbering.
+    Q1: Is reStructuredText rich enough?
+
+    A1: Yes, it is for most people.  If it lacks some construct that
+        is required for a specific application, it can be added via
+        the directive mechanism.  If a common construct has been
+        overlooked and a suitably readable syntax can be found, it can
+        be added to the specification and parser.
+
+    Q2: Is reStructuredText *too* rich?
+
+    A2: For specific applications or individuals, perhaps.  In
+        general, no.
+
+        Since the very beginning, whenever a markup syntax has been
+        proposed on the Doc-SIG, someone has complained about the lack
+        of support for some construct or other.  The reply was often
+        something like, "These are docstrings we're talking about, and
+        docstrings shouldn't have complex markup."  The problem is
+        that a construct that seems superfluous to one person may be
+        absolutely essential to another.
+
+        reStructuredText takes the opposite approach: it provides a
+        rich set of implicit markup constructs (plus a generic
+        extension mechanism for explicit markup), allowing for all
+        kinds of documents.  If the set of constructs is too rich for
+        a particular application, the unused constructs can either be
+        removed from the parser (via application-specific overrides)
+        or simply omitted by convention.
+
+    Q3: Why not use indentation for section structure, like
+        StructuredText does?  Isn't it more "Pythonic"?
+
+    A3: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG
+        post:
+
+            I still think that using indentation to indicate
+            sectioning is wrong.  If you look at how real books and
+            other print publications are laid out, you'll notice that
+            indentation is used frequently, but mostly at the
+            intra-section level.  Indentation can be used to offset
+            lists, tables, quotations, examples, and the like.  (The
+            argument that docstrings are different because they are
+            input for a text formatter is wrong: the whole point is
+            that they are also readable without processing.)
+
+            I reject the argument that using indentation is Pythonic:
+            text is not code, and different traditions and conventions
+            hold.  People have been presenting text for readability
+            for over 30 centuries.  Let's not innovate needlessly.
+
+        See "Section Structure via Indentation" in "Problems With
+        StructuredText" [18 ]_ for further elaboration.
+
+    Q4: Why use reStructuredText for PEPs?  What's wrong with the
+        existing standard?
+
+    A4: The existing standard for PEPs is very limited in terms of
+        general expressibility, and referencing is especially lacking
+        for such a reference-rich document type.  PEPs are currently
+        converted into HTML, but the results (mostly monospaced text)
+        are less than attractive, and most of the value-added
+        potential of HTML is untapped.
+
+        Making reStructuredText a standard markup for PEPs will enable
+        much richer expression, including support for section
+        structure, inline markup, graphics, and tables.  In several
+        PEPs there are ASCII graphics diagrams, which are all that
+        plaintext documents can support.  Since PEPs are made
+        available in HTML form, the ability to include proper diagrams
+        would be immediately useful.
+
+        Current PEP practices allow for reference markers in the form
+        "[1]" in the text, and the footnotes/references themselves are
+        listed in a section toward the end of the document.  There is
+        currently no hyperlinking between the reference marker and the
+        footnote/reference itself (it would be possible to add this to
+        pep2html.py, but the "markup" as it stands is ambiguous and
+        mistakes would be inevitable).  A PEP with many references
+        (such as this one ;-) requires a lot of flipping back and
+        forth.  When revising a PEP, often new references are added or
+        unused references deleted.  It is painful to renumber the
+        references, since it has to be done in two places and can have
+        a cascading effect (insert a single new reference 1, and every
+        other reference has to be renumbered; always adding new
+        references to the end is suboptimal).  It is easy for
+        references to go out of sync.
+
+        PEPs use references for two purposes: simple URL references
+        and footnotes.  reStructuredText differentiates between the
+        two.  A PEP might contain references like this::
+
+            Abstract
+
+                This PEP proposes adding frungible doodads [1] to the
+                core.  It extends PEP 9876 [2] via the BCA [3]
+                mechanism.
+
+            References and Footnotes
+
+                [1] http://www.example.org/
+
+                [2] PEP 9876, Let's Hope We Never Get Here
+                    http://www.python.org/peps/pep-9876.html
+
+                [3] "Bogus Complexity Addition"
+
+        Reference 1 is a simple URL reference.  Reference 2 is a
+        footnote containing text and a URL.  Reference 3 is a footnote
+        containing text only.  Rewritten using reStructuredText, this
+        PEP could look like this::
+
+            Abstract
+            ========
+
+            This PEP proposes adding `frungible doodads`_ to the
+            core.  It extends PEP 9876 [#pep9876]_ via the BCA [#]_
+            mechanism.
+
+            .. _frungible doodads: http://www.example.org/
+
+            .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here
+
+            __ http://www.python.org/peps/pep-9876.html
+
+            .. [#] "Bogus Complexity Addition"
+
+        URLs and footnotes can be defined close to their references if
+        desired, making them easier to read in the source text, and
+        making the PEPs easier to revise.  The "References and
+        Footnotes" section can be auto-generated with a document tree
+        transform.  Footnotes from throughout the PEP would be
+        gathered and displayed under a standard header.  If URL
+        references should likewise be written out explicitly (in
+        citation form), another tree transform could be used.
+
+        URL references can be named ("frungible doodads"), and can be
+        referenced from multiple places in the document without
+        additional definitions.  When converted to HTML, references
+        will be replaced with inline hyperlinks (HTML <A> tags).  The
+        two footnotes are automatically numbered, so they will always
+        stay in sync.  The first footnote also contains an internal
+        reference name, "pep9876", so it's easier to see the
+        connection between reference and footnote in the source text.
+        Named footnotes can be referenced multiple times, maintaining
+        consistent numbering.
+
+        The "#pep9876" footnote could also be written in the form of a
+        citation::
+
+            It extends PEP 9876 [PEP9876]_ ...
+
+            .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here
+
+        Footnotes are numbered, whereas citations use text for their
+        references.
+
+    Q5: Wouldn't it be better to keep the docstring and PEP proposals
+        separate?
+
+    A5: The PEP markup proposal may be removed if it is deemed that
+        there is no need for PEP markup, or it could be made into a
+        separate PEP.  If accepted, PEP 1, PEP Purpose and Guidelines
+        [20]_, and PEP 9, Sample PEP Template [21]_ will be updated.
+
+        It seems natural to adopt a single consistent markup standard
+        for all uses of structured plaintext in Python, and to propose
+        it all in one place.
+
+    Q6: The existing pep2html.py script converts the existing PEP
+        format to HTML.  How will the new-format PEPs be converted to
+        HTML?
+
+    A6: One of the deliverables of the Docutils project [22]_ will be
+        a new version of pep2html.py with integrated reStructuredText
+        parsing.  The Docutils project will support PEPs with a "PEP
+        Reader" component, including all functionality currently in
+        pep2html.py (auto-recognition of PEP & RFC references).
 
-       The "#pep9876" footnote could also be written in the form of a
-       citation::
+    Q7: Who's going to convert the existing PEPs to reStructuredText?
 
-           It extends PEP 9876 [PEP9876]_ ...
+    A7: PEP authors or volunteers may convert existing PEPs if they
+        like, but there is no requirement to do so.  The
+        reStructuredText-based PEPs will coexist with the old PEP
+        standard.  The pep2html.py mentioned in A6 will process both
+        old and new standards.
 
-           .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here
-
-       Footnotes are numbered, whereas citations use text for their
-       references.
-
-    Q: Wouldn't it be better to keep the docstring and PEP proposals
-       separate?
+    Q8: Why use reStructuredText for README and other ancillary files?
 
-    A: The PEP markup proposal is an option to this PEP.  It may be
-       removed if it is deemed that there is no need for PEP markup.
-       The PEP markup proposal could be made into a separate PEP if
-       necessary.  If accepted, PEP 1, PEP Purpose and Guidelines [19]_,
-       and PEP 9, Sample PEP Template [20]_ will be updated.
+    A8: The reasoning given for PEPs in A4 above also applies to
+        README and other ancillary files.  By adopting a standard
+        markup, these files can be converted to attractive
+        cross-referenced HTML and put up on python.org.  Developers of
+        Python projects can also take advantage of this facility for
+        their own documentation.
 
-       It seems natural to adopt a single consistent markup standard
-       for all uses of plaintext in Python.
+    Q9: Won't the superficial similarity to existing markup
+        conventions cause problems, and result in people writing
+        invalid markup (and not noticing, because the plaintext looks
+        natural)?  How forgiving is reStructuredText of "not quite
+        right" markup?
 
-    Q: The existing pep2html.py script converts the existing PEP
-       format to HTML.  How will the new-format PEPs be converted to
-       HTML?
+    A9: There will be some mis-steps, as there would be when moving
+        from one programming language to another.  As with any
+        language, proficiency grows with experience.  Luckily,
+        reStructuredText is a very little language indeed.
 
-    A: One of the deliverables of the Docutils project [21]_ will be a
-       new version of pep2html.py with integrated reStructuredText
-       parsing.  The Docutils project will support PEPs with a "PEP
-       Reader" component, including all functionality currently in
-       pep2html.py (auto-recognition of PEP & RFC references).
+        As with any syntax, there is the possibility of syntax errors.
+        It is expected that a user will run the processing system over
+        their input and check the output for correctness.
 
-    Q: Who's going to convert the existing PEPs to reStructuredText?
+        In a strict sense, the reStructuredText parser is very
+        unforgiving (as it should be; "In the face of ambiguity,
+        refuse the temptation to guess" [23]_ applies to parsing
+        markup as well as computer languages).  Here's a design goal
+        from "An Introduction to reStructuredText" [15 ]_:
+
+            3. Unambiguous.  The rules for markup must not be open for
+               interpretation.  For any given input, there should be
+               one and only one possible output (including error
+               output).
+
+        While unforgiving, at the same time the parser does try to be
+        helpful by producing useful diagnostic output ("system
+        messages").  The parser reports problems, indicating their
+        level of severity (from least to most: debug, info, warning,
+        error, severe).  The user or the client software can decide on
+        reporting thresholds; they can ignore low-level problems or
+        cause high-level problems to bring processing to an immediate
+        halt.  Problems are reported during the parse as well as
+        included in the output, often with two-way links between the
+        source of the problem and the system message explaining it.
+
+    Q10: Will the docstrings in the Python standard library modules be
+         converted to reStructuredText?
+
+    A10: No.  Python's library reference documentation is maintained
+         separately from the source.  Docstrings in the Python
+         standard library should not try to duplicate the library
+         reference documentation.  The current policy for docstrings
+         in the Python standard library is that they should be no more
+         than concise hints.
 
-    A: A call for volunteers will be put out to the Doc-SIG and
-       greater Python communities.  If insufficient volunteers are
-       forthcoming, I (David Goodger) will convert the documents
-       myself, perhaps with some level of automation.  A transitional
-       system whereby both old and new standards can coexist will be
-       easy to implement (and I pledge to implement it if necessary).
+    Q11: I want to write all my strings in Unicode.  Will anything
+         break?
 
-    Q: Why use reStructuredText for README and other ancillary files?
+    A11: The parser will fully support Unicode.  It may not yet, but
+         only because nobody's gotten around to implementing or
+         testing Unicode support.  Contributions are always welcome!
 
-    A: The same reasoning used for PEPs above applies to README and
-       other ancillary files.  By adopting a standard markup, these
-       files can be converted to attractive cross-referenced HTML and
-       put up on python.org.  Developers of Python projects can also
-       take advantage of this facility for their own documentation.
-
-
-References and Footnotes
-
-    [1] http://structuredtext.sourceforge.net/
+    Q12: Why does the community need a new structured text design?
+         What is wrong with existing markup methodologies?
+
+    A12: The existing structured text designs are deficient.
+         @@@
+
+         For Python docstrings, there is no official standard.
+         @@@
+
+
+References & Footnotes
+
+    [1] http://docutils.sourceforge.net/spec/rst.html
 
     [2] http://www.python.org/sigs/doc-sig/
 
@@ -625,33 +743,39 @@ References and Footnotes
 
     [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
 
-    [13] An Introduction to reStructuredText
-         http://structuredtext.sourceforge.net/spec/introduction.txt
+    [13] A ReStructuredText Primer
+         http://docutils.sourceforge.net/docs/rst/quickstart.html
 
-    [14] Problems with StructuredText
-         http://structuredtext.sourceforge.net/spec/problems.txt
+    [14] Quick reStructuredText
+         http://docutils.sourceforge.net/docs/rst/quickref.html
 
-    [15] reStructuredText Markup Specification
-         http://structuredtext.sourceforge.net/spec/reStructuredText.txt
+    [15] An Introduction to reStructuredText
+         http://docutils.sourceforge.net/spec/rst/introduction.html
 
-    [16] A Record of reStructuredText Syntax Alternatives
-         http://structuredtext.sourceforge.net/spec/alternatives.txt
+    [16] reStructuredText Markup Specification
+         http://docutils.sourceforge.net/spec/rst/reStructuredText.html
 
     [17] reStructuredText Directives
-         http://structuredtext.sourceforge.net/spec/directives.txt
+         http://docutils.sourceforge.net/spec/rst/directives.html
 
-    [18] Quick reStructuredText
-         http://structuredtext.sourceforge.net/docs/quickref.html
+    [18] Problems with StructuredText
+         http://docutils.sourceforge.net/spec/rst/problems.html
 
-    [19] PEP 1, PEP Guidelines, Warsaw, Hylton
+    [19] A Record of reStructuredText Syntax Alternatives
+         http://docutils.sourceforge.net/spec/rst/alternatives.html
+
+    [20] PEP 1, PEP Guidelines, Warsaw, Hylton
          http://www.python.org/peps/pep-0001.html
 
-    [20] PEP 9, Sample PEP Template, Warsaw
+    [21] PEP 9, Sample PEP Template, Warsaw
          http://www.python.org/peps/pep-0009.html
 
-    [21] http://docutils.sourceforge.net/
+    [22] http://docutils.sourceforge.net/
+
+    [23] From "The Zen of Python (by Tim Peters)",
+         http://www.python.org/doc/Humor.html#zen (or ``import this``)
 
-    [22] PEP 216, Docstring Format, Zadka
+    [24] PEP 216, Docstring Format, Zadka
          http://www.python.org/peps/pep-0216.html
 
 
@@ -662,10 +786,11 @@ Copyright
 
 Acknowledgements
 
-    Some text is borrowed from PEP 216, Docstring Format, by Moshe
-    Zadka [22]_.
+    Some text is borrowed from PEP 216, Docstring Format [24]_, by
+    Moshe Zadka.
 
-    Special thanks to all members past & present of the Python Doc-SIG.
+    Special thanks to all members past & present of the Python
+    Doc-SIG.