rest25/documenting/rest.rst => rest262/documenting/rest.rst
f1.. highlightlang:: rest
2
3reStructuredText Primer
4=======================
5
6This section is a brief introduction to reStructuredText (reST) concepts and
n7-syntax, intended to provide authors with enough information to author
n7+syntax, intended to provide authors with enough information to author documents
8-documents productively.
9-Since reST was designed to be a simple, unobtrusive markup language, this will
8+productively.  Since reST was designed to be a simple, unobtrusive markup
10-not take too long.
9+language, this will not take too long.
11
12.. seealso::
13
14    The authoritative `reStructuredText User
15    Documentation <http://docutils.sourceforge.net/rst.html>`_.
16
17
18Paragraphs
19----------
20
n21-The paragraph is the most basic block in a reST document.
n20+The paragraph is the most basic block in a reST document.  Paragraphs are simply
22-Paragraphs are simply chunks of text
23-separated by one or more blank lines.  As in Python, indentation is significant
21+chunks of text separated by one or more blank lines.  As in Python, indentation
24-in reST, so all lines of the same paragraph must be left-aligned
22+is significant in reST, so all lines of the same paragraph must be left-aligned
25to the same level of indentation.
26
27
28Inline markup
29-------------
30
31The standard reST inline markup is quite simple: use
32
58List markup is natural: just place an asterisk at the start of a paragraph and
59indent properly.  The same goes for numbered lists; they can also be
60autonumbered using a ``#`` sign::
61
62   * This is a bulleted list.
63   * It has two items, the second
64     item uses two lines.
65
n64+   1. This is a numbered list.
65+   2. It has two items too.
66+ 
66   #. This is a numbered list.
67   #. It has two items too.
68
n70+ 
69Nested lists are possible, but be aware that they must be separated from the
70parent list items by blank lines::
71
72   * this is
73   * a list
74
75     * with a nested list
76     * and some subitems
91Paragraphs are quoted by just indenting them more than the surrounding
92paragraphs.
93
94
95Source Code
96-----------
97
98Literal code blocks are introduced by ending a paragraph with the special marker
n99-``::``.  The literal block must be indented, to be able to include blank lines::
n101+``::``.  The literal block must be indented::
100
101   This is a normal text paragraph. The next paragraph is a code sample::
102
103      It is not processed in any way, except
104      that the indentation is removed.
105
106      It can span multiple lines.
107
205
206   Lorem ipsum [#]_ dolor sit amet ... [#]_
207
208   .. rubric:: Footnotes
209
210   .. [#] Text of the first footnote.
211   .. [#] Text of the second footnote.
212
n215+You can also explicitly number the footnotes for better context.
216+ 
213
214Comments
215--------
216
217Every explicit markup block which isn't a valid markup construct (like the
n218-footnotes above) is regared as a comment.
n222+footnotes above) is regarded as a comment.
219
220
221Source encoding
222---------------
223
224Since the easiest way to include special characters like em dashes or copyright
225signs in reST is to directly write them as Unicode characters, one has to
226specify an encoding:
227
228All Python documentation source files must be in UTF-8 encoding, and the HTML
229documents written from them will be in that encoding as well.
230
231
t232-XXX: Gotchas
t236+Gotchas
237+-------
238+ 
239+There are some problems one commonly runs into while authoring reST documents:
240+ 
241+* **Separation of inline markup:** As said above, inline markup spans must be
242+  separated from the surrounding text by non-word characters, you have to use
243+  an escaped space to get around that.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op