web/rst.txt

   1 ====================
   2  |reStructuredText|
   3 ====================
   4 -------------------------------------------------
   5  Markup Syntax and Parser Component of Docutils_
   6 -------------------------------------------------
   7
   8 :Date: $Date$
   9
  10 .. contents::
  11
  12 reStructuredText is an easy-to-read, what-you-see-is-what-you-get
  13 plaintext markup syntax and parser system.  It is useful for in-line
  14 program documentation (such as Python docstrings), for quickly
  15 creating simple web pages, and for standalone documents.
  16 reStructuredText is designed for extensibility for specific
  17 application domains.  The reStructuredText parser is a component of
  18 Docutils_.  reStructuredText is a revision and reinterpretation of the
  19 StructuredText_ and Setext_ lightweight markup systems.
  20
  21 The primary goal of reStructuredText is to define and implement a
  22 markup syntax for use in Python docstrings and other documentation
  23 domains, that is readable and simple, yet powerful enough for
  24 non-trivial use.  The intended purpose of the markup is the conversion
  25 of reStructuredText documents into useful structured data formats.
  26
  27 See statemachine.py_ for an example of a Python module fully
  28 documented using reStructuredText.
  29
  30
  31 User Documentation
  32 ==================
  33
  34 - `A ReStructuredText Primer`__ (HTML file, or `text source`__).
  35 - `Quick reStructuredText`__ (user reference)
  36 - `reStructuredText Cheat Sheet`__ (text only; 1 page for syntax, 1
  37   page directive & role reference)
  38
  39 Users who have questions or need assistance with Docutils or
  40 reStructuredText should post a message to the Docutils-users_ mailing
  41 list.
  42
  43 __ docs/user/rst/quickstart.html
  44 __ docs/user/rst/quickstart.txt
  45 __ docs/user/rst/quickref.html
  46 __ docs/user/rst/cheatsheet.txt
  47 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
  48
  49
  50 Reference Documentation
  51 =======================
  52
  53 - `An Introduction to reStructuredText`__ (includes the Goals__ and
  54   History__ of reStructuredText)
  55 - `reStructuredText Markup Specification`__
  56 - `reStructuredText Directives`__
  57 - `reStructuredText Interpreted Text Roles`__
  58
  59 __ docs/ref/rst/introduction.html
  60 __ docs/ref/rst/introduction.html#goals
  61 __ docs/ref/rst/introduction.html#history
  62 __ docs/ref/rst/restructuredtext.html
  63 __ docs/ref/rst/directives.html
  64 __ docs/ref/rst/roles.html
  65
  66
  67 Developer Documentation
  68 =======================
  69
  70 - `A Record of reStructuredText Syntax Alternatives`__
  71 - `Problems With StructuredText`__
  72
  73 __ docs/dev/rst/alternatives.html
  74 __ docs/dev/rst/problems.html
  75
  76
  77 How-To's
  78 --------
  79
  80 - `Creating reStructuredText Directives`__
  81 - `Creating reStructuredText Interpreted Text Roles`__
  82
  83 __ docs/howto/rst-directives.html
  84 __ docs/howto/rst-roles.html
  85
  86
  87 Testimonials
  88 ============
  89
  90 The following testimonials are excerpts from unsolicited posts to
  91 mailing lists and the comp.lang.python newsgroup.  Being excerpts,
  92 there's often context missing, which sometimes tones down the message.
  93
  94 `Ueli Schlaepfer on Doc-SIG, 2002-03-28`__:
  95
  96 __ http://mail.python.org/pipermail/doc-sig/2002-March/002526.html
  97
  98     I have adopted reST as my tool of choice for producing notes while
  99     doing lab work (mostly in a matlab environment).  Since then, the
 100     quality of such documentation has increased noticeably, mostly for
 101     two reasons:
 102
 103     - I no longer need to switch to another tool, so the threshold has
 104       fallen to very low.  Note that "another tool" means Winword...
 105     - Still, I have a powerful set of markup constructs at my
 106       fingertips that let me create the kind of documents I need with
 107       more ease than any other tool I can think of.
 108
 109     Thanks to reST/DPS [now Docutils --ed], I'll soon be able to go
 110     ahead and apply the same tools for extracting documentation out of
 111     my Python code.  Hey, that's a printable and a browsable version
 112     *for free*!  Personally, I consider this a large benefit.
 113
 114     ... All essential constructs for everyday use are there, and much
 115     more if needed. ...
 116
 117 `Guido van Rossum, enthusiastic about PEP 287 but a bit hasty (see the
 118 follow-ups) on Python-Dev, 2002-04-02`__:
 119
 120 __ http://mail.python.org/pipermail/python-dev/2002-April/022131.html
 121
 122     Good PEP, David!  What's the next step?  Should the processing
 123     code be incorporated in the standard library?  Should we start
 124     converting the standard library docs to reStructuredText?
 125
 126 `Timothy Delaney on comp.lang.python, 2002-04-03`__:
 127
 128 __ http://mail.python.org/pipermail/python-list/2002-April/096013.html
 129
 130     I read through all the reStructuredText docs, comparing the text
 131     versions to the html versions.  I found the text versions to be
 132     *very* easy to read, whilst making it obvious in most cases when
 133     something was "special".
 134
 135     I particularly like the system of doing hyperlinks...
 136
 137     Definitely +1 from me ... I would really like a standard, clean
 138     docstring format.  Might make it easier to get my next project
 139     done in Python...
 140
 141 `Guido van Rossum on Python-Dev, 2002-04-03`__:
 142
 143 __ http://mail.python.org/pipermail/python-dev/2002-April/022212.html
 144
 145     I think that reStructuredText is a good format for marking up
 146     docstrings; it's probably as good as it gets given the
 147     requirements (a fairly elaborate feature set, yet more readable
 148     "in the raw" than HTML).
 149
 150 `Richard Jones on comp.lang.python, 2002-04-03`__:
 151
 152 __ http://mail.python.org/pipermail/python-list/2002-April/096117.html
 153
 154     How I see it is that ReST is a middle ground between markup and
 155     non-.  It has markup, and you can use it to the extreme.  Or you
 156     can follow some simple conventions (the most basic form of markup)
 157     and not worry about all the finer detail stuff. The difference
 158     between::
 159
 160         @section{The Section Title}
 161
 162     and::
 163
 164         The Section Title
 165         -----------------
 166
 167     Is pretty clearly to me that the second doesn't *look* like
 168     markup, even though it is.
 169
 170 `Guido van Rossum on Python-Dev, 2002-04-04`__:
 171
 172 __ http://mail.python.org/pipermail/python-dev/2002-April/022247.html
 173
 174     Structured text is really a great idea for certain situations;
 175     reST is a much better implementation of the idea than any versions
 176     I've seen before.
 177
 178 `Max M on comp.lang.python, 2002-04-05`__:
 179
 180 __ http://mail.python.org/pipermail/python-list/2002-April/096656.html
 181
 182     Any programmer can learn the basics in 15 minutes or less.
 183
 184     And it really is very very easy to write documents in it.  I do
 185     belive that if I were ever to write a book (again) I would write
 186     it in ReST.
 187
 188     And as far as I can tell from the specs, ReST solves most of the
 189     problems I have had with structured text.  A few things gets a
 190     little more complicated and some get simpler.  All in all a good
 191     bargain.
 192
 193     I would certainly use it.  I also hope that it gets integrated
 194     into Zope.
 195
 196 `David Abrahams on Python-Dev, 2002-04-06`__:
 197
 198 __ http://mail.python.org/pipermail/python-dev/2002-April/022443.html
 199
 200     Incidentally, I'm really excited about reST.  I've been looking
 201     for a tolerable markup for C++ comments, and reST looks like it
 202     might fit the bill.
 203
 204 `Eric Jones on Python-Dev, 2002-08-01`__:
 205
 206 __ http://mail.python.org/pipermail/python-dev/2002-August/027198.html
 207
 208     I would very much like to see reStructuredText, or some minor
 209     variation on it, move forward as a "standard" for doc-strings very
 210     soon.  I have long lamented not having a prescribed format *and*
 211     an associated processing tool suite included in the standard
 212     library.  Even if the format isn't perfect (I think it looks very
 213     good), it is time to pick a reasonable candidate and go.
 214
 215 This being the Internet, there were plenty of people opposed to the
 216 idea of reStructuredText, some vehemently.  Discovering *those* gems
 217 is left as an exercise for the reader.
 218
 219 .. _Docutils: index.html
 220 .. _StructuredText:
 221    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
 222 .. _Setext: mirror/setext.html
 223 .. _statemachine.py: docutils/statemachine.py
 224
 225 .. |reStructuredText| image:: rst.png
 226
 227 \f
 228 ..
 229    Local Variables:
 230    mode: indented-text
 231    indent-tabs-mode: nil
 232    sentence-end-double-space: t
 233    fill-column: 70
 234    End: