"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "docutils-0.5/docs/ref/rst/introduction.txt" of archive docutils-0.5.tar.gz:

    1 =====================================
    2  An Introduction to reStructuredText
    3 =====================================
    4 :Author: David Goodger
    5 :Contact: goodger@python.org
    6 :Revision: $Revision: 4564 $
    7 :Date: $Date: 2006-05-21 22:44:42 +0200 (Son, 21 Mai 2006) $
    8 :Copyright: This document has been placed in the public domain.
    9 
   10 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
   11 plaintext markup syntax and parser system.  It is useful for inline
   12 program documentation (such as Python docstrings), for quickly
   13 creating simple web pages, and for standalone documents.
   14 reStructuredText_ is a proposed revision and reinterpretation of the
   15 StructuredText_ and Setext_ lightweight markup systems.
   16 
   17 reStructuredText is designed for extensibility for specific
   18 application domains.  Its parser is a component of Docutils_.
   19 
   20 This document defines the goals_ of reStructuredText and provides a
   21 history_ of the project.  It is written using the reStructuredText
   22 markup, and therefore serves as an example of its use.  For a gentle
   23 introduction to using reStructuredText, please read `A
   24 ReStructuredText Primer`_.  The `Quick reStructuredText`_ user
   25 reference is also useful.  The `reStructuredText Markup
   26 Specification`_ is the definitive reference.  There is also an
   27 analysis of the `Problems With StructuredText`_.
   28 
   29 ReStructuredText's web page is
   30 http://docutils.sourceforge.net/rst.html.
   31 
   32 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
   33 .. _StructuredText:
   34     http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
   35 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
   36 .. _Docutils: http://docutils.sourceforge.net/
   37 .. _A ReStructuredText Primer: ../../user/rst/quickstart.html
   38 .. _Quick reStructuredText: ../../user/rst/quickref.html
   39 .. _reStructuredText Markup Specification: restructuredtext.html
   40 .. _Problems with StructuredText: ../../dev/rst/problems.html
   41 
   42 
   43 Goals
   44 =====
   45 
   46 The primary goal of reStructuredText_ is to define a markup syntax for
   47 use in Python docstrings and other documentation domains, that is
   48 readable and simple, yet powerful enough for non-trivial use.  The
   49 intended purpose of the reStructuredText markup is twofold:
   50 
   51 - the establishment of a set of standard conventions allowing the
   52   expression of structure within plaintext, and
   53 
   54 - the conversion of such documents into useful structured data
   55   formats.
   56 
   57 The secondary goal of reStructuredText is to be accepted by the Python
   58 community (by way of being blessed by PythonLabs and the BDFL [#]_) as
   59 a standard for Python inline documentation (possibly one of several
   60 standards, to account for taste).
   61 
   62 .. [#] Python's creator and "Benevolent Dictator For Life",
   63    Guido van Rossum.
   64 
   65 To clarify the primary goal, here are specific design goals, in order,
   66 beginning with the most important:
   67 
   68 1. Readable.  The marked-up text must be easy to read without any
   69    prior knowledge of the markup language.  It should be as easily
   70    read in raw form as in processed form.
   71 
   72 2. Unobtrusive.  The markup that is used should be as simple and
   73    unobtrusive as possible.  The simplicity of markup constructs
   74    should be roughly proportional to their frequency of use.  The most
   75    common constructs, with natural and obvious markup, should be the
   76    simplest and most unobtrusive.  Less common constructs, for which
   77    there is no natural or obvious markup, should be distinctive.
   78 
   79 3. Unambiguous.  The rules for markup must not be open for
   80    interpretation.  For any given input, there should be one and only
   81    one possible output (including error output).
   82 
   83 4. Unsurprising.  Markup constructs should not cause unexpected output
   84    upon processing.  As a fallback, there must be a way to prevent
   85    unwanted markup processing when a markup construct is used in a
   86    non-markup context (for example, when documenting the markup syntax
   87    itself).
   88 
   89 5. Intuitive.  Markup should be as obvious and easily remembered as
   90    possible, for the author as well as for the reader.  Constructs
   91    should take their cues from such naturally occurring sources as
   92    plaintext email messages, newsgroup postings, and text
   93    documentation such as README.txt files.
   94 
   95 6. Easy.  It should be easy to mark up text using any ordinary text
   96    editor.
   97 
   98 7. Scalable.  The markup should be applicable regardless of the length
   99    of the text.
  100 
  101 8. Powerful.  The markup should provide enough constructs to produce a
  102    reasonably rich structured document.
  103 
  104 9. Language-neutral.  The markup should apply to multiple natural (as
  105    well as artificial) languages, not only English.
  106 
  107 10. Extensible.  The markup should provide a simple syntax and
  108     interface for adding more complex general markup, and custom
  109     markup.
  110 
  111 11. Output-format-neutral.  The markup will be appropriate for
  112     processing to multiple output formats, and will not be biased
  113     toward any particular format.
  114 
  115 The design goals above were used as criteria for accepting or
  116 rejecting syntax, or selecting between alternatives.
  117 
  118 It is emphatically *not* the goal of reStructuredText to define
  119 docstring semantics, such as docstring contents or docstring length.
  120 These issues are orthogonal to the markup syntax and beyond the scope
  121 of this specification.
  122 
  123 Also, it is not the goal of reStructuredText to maintain compatibility
  124 with StructuredText_ or Setext_.  reStructuredText shamelessly steals
  125 their great ideas and ignores the not-so-great.
  126 
  127 Author's note:
  128 
  129     Due to the nature of the problem we're trying to solve (or,
  130     perhaps, due to the nature of the proposed solution), the above
  131     goals unavoidably conflict.  I have tried to extract and distill
  132     the wisdom accumulated over the years in the Python Doc-SIG_
  133     mailing list and elsewhere, to come up with a coherent and
  134     consistent set of syntax rules, and the above goals by which to
  135     measure them.
  136 
  137     There will inevitably be people who disagree with my particular
  138     choices.  Some desire finer control over their markup, others
  139     prefer less.  Some are concerned with very short docstrings,
  140     others with full-length documents.  This specification is an
  141     effort to provide a reasonably rich set of markup constructs in a
  142     reasonably simple form, that should satisfy a reasonably large
  143     group of reasonable people.
  144 
  145     David Goodger (goodger@python.org), 2001-04-20
  146 
  147 .. _Doc-SIG: http://www.python.org/sigs/doc-sig/
  148 
  149 
  150 History
  151 =======
  152 
  153 reStructuredText_, the specification, is based on StructuredText_ and
  154 Setext_.  StructuredText was developed by Jim Fulton of `Zope
  155 Corporation`_ (formerly Digital Creations) and first released in 1996.
  156 It is now released as a part of the open-source "Z Object Publishing
  157 Environment" (ZOPE_).  Ian Feldman's and Tony Sanders' earlier Setext_
  158 specification was either an influence on StructuredText or, by their
  159 similarities, at least evidence of the correctness of this approach.
  160 
  161 I discovered StructuredText_ in late 1999 while searching for a way to
  162 document the Python modules in one of my projects.  Version 1.1 of
  163 StructuredText was included in Daniel Larsson's pythondoc_.  Although
  164 I was not able to get pythondoc to work for me, I found StructuredText
  165 to be almost ideal for my needs.  I joined the Python Doc-SIG_
  166 (Documentation Special Interest Group) mailing list and found an
  167 ongoing discussion of the shortcomings of the StructuredText
  168 "standard".  This discussion has been going on since the inception of
  169 the mailing list in 1996, and possibly predates it.
  170 
  171 I decided to modify the original module with my own extensions and
  172 some suggested by the Doc-SIG members.  I soon realized that the
  173 module was not written with extension in mind, so I embarked upon a
  174 general reworking, including adapting it to the "re" regular
  175 expression module (the original inspiration for the name of this
  176 project).  Soon after I completed the modifications, I discovered that
  177 StructuredText.py was up to version 1.23 in the ZOPE distribution.
  178 Implementing the new syntax extensions from version 1.23 proved to be
  179 an exercise in frustration, as the complexity of the module had become
  180 overwhelming.
  181 
  182 In 2000, development on StructuredTextNG_ ("Next Generation") began at
  183 `Zope Corporation`_ (then Digital Creations).  It seems to have many
  184 improvements, but still suffers from many of the problems of classic
  185 StructuredText.
  186 
  187 I decided that a complete rewrite was in order, and even started a
  188 `reStructuredText SourceForge project`_ (now inactive).  My
  189 motivations (the "itches" I aim to "scratch") are as follows:
  190 
  191 - I need a standard format for inline documentation of the programs I
  192   write.  This inline documentation has to be convertible to other
  193   useful formats, such as HTML.  I believe many others have the same
  194   need.
  195 
  196 - I believe in the Setext/StructuredText idea and want to help
  197   formalize the standard.  However, I feel the current specifications
  198   and implementations have flaws that desperately need fixing.
  199 
  200 - reStructuredText could form part of the foundation for a
  201   documentation extraction and processing system, greatly benefitting
  202   Python.  But it is only a part, not the whole.  reStructuredText is
  203   a markup language specification and a reference parser
  204   implementation, but it does not aspire to be the entire system.  I
  205   don't want reStructuredText or a hypothetical Python documentation
  206   processor to die stillborn because of over-ambition.
  207 
  208 - Most of all, I want to help ease the documentation chore, the bane
  209   of many a programmer.
  210 
  211 Unfortunately I was sidetracked and stopped working on this project.
  212 In November 2000 I made the time to enumerate the problems of
  213 StructuredText and possible solutions, and complete the first draft of
  214 a specification.  This first draft was posted to the Doc-SIG in three
  215 parts:
  216 
  217 - `A Plan for Structured Text`__
  218 - `Problems With StructuredText`__
  219 - `reStructuredText: Revised Structured Text Specification`__
  220 
  221 __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
  222 __ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html
  223 __ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html
  224 
  225 In March 2001 a flurry of activity on the Doc-SIG spurred me to
  226 further revise and refine my specification, the result of which you
  227 are now reading.  An offshoot of the reStructuredText project has been
  228 the realization that a single markup scheme, no matter how well
  229 thought out, may not be enough.  In order to tame the endless debates
  230 on Doc-SIG, a flexible `Docstring Processing System framework`_ needed
  231 to be constructed.  This framework has become the more important of
  232 the two projects; reStructuredText_ has found its place as one
  233 possible choice for a single component of the larger framework.
  234 
  235 The project web site and the first project release were rolled out in
  236 June 2001, including posting the second draft of the spec [#spec-2]_
  237 and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the
  238 Doc-SIG.  These documents and the project implementation proceeded to
  239 evolve at a rapid pace.  Implementation history details can be found
  240 in the `project history file`_.
  241 
  242 In November 2001, the reStructuredText parser was nearing completion.
  243 Development of the parser continued with the addition of small
  244 convenience features, improvements to the syntax, the filling in of
  245 gaps, and bug fixes.  After a long holiday break, in early 2002 most
  246 development moved over to the other Docutils components, the
  247 "Readers", "Writers", and "Transforms".  A "standalone" reader
  248 (processes standalone text file documents) was completed in February,
  249 and a basic HTML writer (producing HTML 4.01, using CSS-1) was
  250 completed in early March.
  251 
  252 `PEP 287`_, "reStructuredText Standard Docstring Format", was created
  253 to formally propose reStructuredText as a standard format for Python
  254 docstrings, PEPs, and other files.  It was first posted to
  255 comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02.
  256 
  257 Version 0.4 of the reStructuredText__ and `Docstring Processing
  258 System`_ projects were released in April 2002.  The two projects were
  259 immediately merged, renamed to "Docutils_", and a 0.1 release soon
  260 followed.
  261 
  262 .. __: `reStructuredText SourceForge project`_
  263 
  264 .. [#spec-2] The second draft of the spec:
  265 
  266    - `An Introduction to reStructuredText`__
  267    - `Problems With StructuredText`__
  268    - `reStructuredText Markup Specification`__
  269    - `Python Extensions to the reStructuredText Markup
  270      Specification`__
  271 
  272    __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html
  273    __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html
  274    __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html
  275    __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html
  276 
  277 .. [#peps-1] First drafts of the PEPs:
  278 
  279    - `PEP 256: Docstring Processing System Framework`__
  280    - `PEP 258: DPS Generic Implementation Details`__
  281    - `PEP 257: Docstring Conventions`__
  282 
  283    Current working versions of the PEPs can be found in
  284    http://docutils.sourceforge.net/docs/peps/, and official versions
  285    can be found in the `master PEP repository`_.
  286 
  287    __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html
  288    __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html
  289    __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html
  290 
  291 
  292 .. _Zope Corporation: http://www.zope.com
  293 .. _ZOPE: http://www.zope.org
  294 .. _reStructuredText SourceForge project:
  295    http://structuredtext.sourceforge.net/
  296 .. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
  297 .. _StructuredTextNG:
  298    http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
  299 .. _project history file: ../../../HISTORY.html
  300 .. _PEP 287: ../../peps/pep-0287.html
  301 .. _Docstring Processing System framework: ../../peps/pep-0256.html
  302 .. _comp.lang.python: news:comp.lang.python
  303 .. _Python-dev: http://mail.python.org/pipermail/python-dev/
  304 .. _Docstring Processing System: http://docstring.sourceforge.net/
  305 .. _master PEP repository: http://www.python.org/peps/
  306 
  307 
  308 ..
  309    Local Variables:
  310    mode: indented-text
  311    indent-tabs-mode: nil
  312    sentence-end-double-space: t
  313    fill-column: 70
  314    End: