Preliminary post-initial-posting edit; incomplete.

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

1 files changed, 89 insertions, 61 deletions

diff --git a/docutils/docs/peps/pep-0287.txt b/docutils/docs/peps/pep-0287.txt
index f886d94c2..74496d412 100644
--- a/docutils/docs/peps/pep-0287.txt
+++ b/docutils/docs/peps/pep-0287.txt
@@ -16,7 +16,7 @@ Abstract
     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 the standard markup format for structured
+    [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
@@ -41,11 +41,19 @@ Benefits
     systems can be extracted in context and processed into useful,
     high-quality documentation for multiple purposes.
 
-    The proposed format (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.
+    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
@@ -94,13 +102,18 @@ Goals
 
     The goals of this PEP are as follows:
 
-    1. To establish reStructuredText as a standard docstring format by
-       attaining "accepted" status (Python community consensus; BDFL
-       pronouncement).  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.
+    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.
 
-    2. To address any related concerns raised by the Python community.
+       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 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
@@ -111,29 +124,29 @@ Goals
        projects.  It is hoped that interested developers will join
        forces and work on a joint/merged/common implementation.
 
-    5. 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 RFC 2822 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. 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
@@ -166,8 +179,12 @@ Rationale
     4. Implicit markup is aesthetically compatible with the clean and
        minimalist Python syntax.
 
-    Many alternative markups have been proposed on the Doc-SIG,
-    including:
+    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]_
 
@@ -234,10 +251,6 @@ Rationale
       - There has been no mechanism to get around the SText markup
         rules when a markup character is used in a non-markup context.
 
-    (Please note that this is not an exclusive list of all existing
-    markup systems, just a sample of those seriously proposed for
-    docstring use, on the Doc-SIG.)
-
     Proponents of implicit STexts have vigorously opposed proposals
     for explicit markup (XML, HTML, TeX, POD, etc.), and the debates
     have continued off and on since 1996 or earlier.
@@ -248,24 +261,26 @@ Rationale
 
 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:
+    The specification and user documentaton for reStructuredText is
+    quite extensive.  Rather than repeating or summarizing it all
+    here, links to the originals are provided.
 
-    - An Introduction to reStructuredText [13]_
+    Please first take a look at "A ReStructuredText Primer" []_, a
+    short and gentle introduction.  The "Quick reStructuredText" user
+    reference [18]_ quickly summarizes all of the markup constructs.
+    For complete and extensive details, the following documents
+    contain the full specification itself:
 
-    - Problems With StructuredText [14]_ (optional for those who have
-      used StructuredText; it explains many markup decisions made)
+    - An Introduction to reStructuredText [13]_
 
     - reStructuredText Markup Specification [15]_
 
-    - A Record of reStructuredText Syntax Alternatives [16]_ (explains
-      markup decisions made independently of StructuredText)
-
     - reStructuredText Directives [17]_
 
-    There is also a "Quick reStructuredText" user reference [18]_.
+    In addition, "Problems With StructuredText" [14]_ explains many
+    markup decisions made with regards to StructuredText, and "A
+    Record of reStructuredText Syntax Alternatives" [16]_ records
+    markup decisions made independently.
 
     A summary of features addressing often-raised docstring markup
     concerns follows:
@@ -622,12 +637,11 @@ Questions & Answers
 
     Q7: Who's going to convert the existing PEPs to reStructuredText?
 
-    A7: 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).
+    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.
 
     Q8: Why use reStructuredText for README and other ancillary files?
 
@@ -678,10 +692,12 @@ Questions & Answers
     Q10: Will the docstrings in the Python standard library modules be
          converted to reStructuredText?
 
-    A10: Over time, with the help of the developer community, many
-         modules will be converted.  Some modules may never be
-         converted.  A future toolset will have to allow for
-         incompleteness.
+    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.
 
     Q11: I want to write all my strings in Unicode.  Will anything
          break?
@@ -690,6 +706,15 @@ Questions & Answers
          only because nobody's gotten around to implementing or
          testing Unicode support.  Contributions are always welcome!
 
+    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
 
@@ -717,6 +742,12 @@ References & Footnotes
 
     [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
 
+    [] A ReStructuredText Primer
+         http://structuredtext.sourceforge.net/docs/quickstart.html
+
+    [18] Quick reStructuredText
+         http://structuredtext.sourceforge.net/docs/quickref.html
+
     [13] An Introduction to reStructuredText
          http://structuredtext.sourceforge.net/spec/introduction.txt
 
@@ -732,9 +763,6 @@ References & Footnotes
     [17] reStructuredText Directives
          http://structuredtext.sourceforge.net/spec/directives.txt
 
-    [18] Quick reStructuredText
-         http://structuredtext.sourceforge.net/docs/quickref.html
-
     [19] PEP 1, PEP Guidelines, Warsaw, Hylton
          http://www.python.org/peps/pep-0001.html