1===================================== 2 An Introduction to reStructuredText 3===================================== 4:Author: David Goodger 5:Contact: docutils-develop@lists.sourceforge.net 6:Revision: $Revision: 7302 $ 7:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03. Jän 2012) $ 8:Copyright: This document has been placed in the public domain. 9 10reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get 11plaintext markup syntax and parser system. It is useful for inline 12program documentation (such as Python docstrings), for quickly 13creating simple web pages, and for standalone documents. 14reStructuredText_ is a proposed revision and reinterpretation of the 15StructuredText_ and Setext_ lightweight markup systems. 16 17reStructuredText is designed for extensibility for specific 18application domains. Its parser is a component of Docutils_. 19 20This document defines the goals_ of reStructuredText and provides a 21history_ of the project. It is written using the reStructuredText 22markup, and therefore serves as an example of its use. For a gentle 23introduction to using reStructuredText, please read `A 24ReStructuredText Primer`_. The `Quick reStructuredText`_ user 25reference is also useful. The `reStructuredText Markup 26Specification`_ is the definitive reference. There is also an 27analysis of the `Problems With StructuredText`_. 28 29ReStructuredText's web page is 30http://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 43Goals 44===== 45 46The primary goal of reStructuredText_ is to define a markup syntax for 47use in Python docstrings and other documentation domains, that is 48readable and simple, yet powerful enough for non-trivial use. The 49intended 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 57The secondary goal of reStructuredText is to be accepted by the Python 58community (by way of being blessed by PythonLabs and the BDFL [#]_) as 59a standard for Python inline documentation (possibly one of several 60standards, to account for taste). 61 62.. [#] Python's creator and "Benevolent Dictator For Life", 63 Guido van Rossum. 64 65To clarify the primary goal, here are specific design goals, in order, 66beginning with the most important: 67 681. 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 722. 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 793. 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 834. 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 895. 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 956. Easy. It should be easy to mark up text using any ordinary text 96 editor. 97 987. Scalable. The markup should be applicable regardless of the length 99 of the text. 100 1018. Powerful. The markup should provide enough constructs to produce a 102 reasonably rich structured document. 103 1049. Language-neutral. The markup should apply to multiple natural (as 105 well as artificial) languages, not only English. 106 10710. Extensible. The markup should provide a simple syntax and 108 interface for adding more complex general markup, and custom 109 markup. 110 11111. 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 115The design goals above were used as criteria for accepting or 116rejecting syntax, or selecting between alternatives. 117 118It is emphatically *not* the goal of reStructuredText to define 119docstring semantics, such as docstring contents or docstring length. 120These issues are orthogonal to the markup syntax and beyond the scope 121of this specification. 122 123Also, it is not the goal of reStructuredText to maintain compatibility 124with StructuredText_ or Setext_. reStructuredText shamelessly steals 125their great ideas and ignores the not-so-great. 126 127Author'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 150History 151======= 152 153reStructuredText_, the specification, is based on StructuredText_ and 154Setext_. StructuredText was developed by Jim Fulton of `Zope 155Corporation`_ (formerly Digital Creations) and first released in 1996. 156It is now released as a part of the open-source "Z Object Publishing 157Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ 158specification was either an influence on StructuredText or, by their 159similarities, at least evidence of the correctness of this approach. 160 161I discovered StructuredText_ in late 1999 while searching for a way to 162document the Python modules in one of my projects. Version 1.1 of 163StructuredText was included in Daniel Larsson's pythondoc_. Although 164I was not able to get pythondoc to work for me, I found StructuredText 165to be almost ideal for my needs. I joined the Python Doc-SIG_ 166(Documentation Special Interest Group) mailing list and found an 167ongoing discussion of the shortcomings of the StructuredText 168"standard". This discussion has been going on since the inception of 169the mailing list in 1996, and possibly predates it. 170 171I decided to modify the original module with my own extensions and 172some suggested by the Doc-SIG members. I soon realized that the 173module was not written with extension in mind, so I embarked upon a 174general reworking, including adapting it to the "re" regular 175expression module (the original inspiration for the name of this 176project). Soon after I completed the modifications, I discovered that 177StructuredText.py was up to version 1.23 in the ZOPE distribution. 178Implementing the new syntax extensions from version 1.23 proved to be 179an exercise in frustration, as the complexity of the module had become 180overwhelming. 181 182In 2000, development on StructuredTextNG_ ("Next Generation") began at 183`Zope Corporation`_ (then Digital Creations). It seems to have many 184improvements, but still suffers from many of the problems of classic 185StructuredText. 186 187I decided that a complete rewrite was in order, and even started a 188`reStructuredText SourceForge project`_ (now inactive). My 189motivations (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 211Unfortunately I was sidetracked and stopped working on this project. 212In November 2000 I made the time to enumerate the problems of 213StructuredText and possible solutions, and complete the first draft of 214a specification. This first draft was posted to the Doc-SIG in three 215parts: 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 225In March 2001 a flurry of activity on the Doc-SIG spurred me to 226further revise and refine my specification, the result of which you 227are now reading. An offshoot of the reStructuredText project has been 228the realization that a single markup scheme, no matter how well 229thought out, may not be enough. In order to tame the endless debates 230on Doc-SIG, a flexible `Docstring Processing System framework`_ needed 231to be constructed. This framework has become the more important of 232the two projects; reStructuredText_ has found its place as one 233possible choice for a single component of the larger framework. 234 235The project web site and the first project release were rolled out in 236June 2001, including posting the second draft of the spec [#spec-2]_ 237and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the 238Doc-SIG. These documents and the project implementation proceeded to 239evolve at a rapid pace. Implementation history details can be found 240in the `project history file`_. 241 242In November 2001, the reStructuredText parser was nearing completion. 243Development of the parser continued with the addition of small 244convenience features, improvements to the syntax, the filling in of 245gaps, and bug fixes. After a long holiday break, in early 2002 most 246development 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, 249and a basic HTML writer (producing HTML 4.01, using CSS-1) was 250completed in early March. 251 252`PEP 287`_, "reStructuredText Standard Docstring Format", was created 253to formally propose reStructuredText as a standard format for Python 254docstrings, PEPs, and other files. It was first posted to 255comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02. 256 257Version 0.4 of the reStructuredText__ and `Docstring Processing 258System`_ projects were released in April 2002. The two projects were 259immediately merged, renamed to "Docutils_", and a 0.1 release soon 260followed. 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: 315