--- rest25/documenting/rest.rst	2008-12-19 16:58:09.000000000 +0900
+++ rest262/documenting/rest.rst	2009-04-05 05:02:10.000000000 +0900
@@ -1,36 +1,34 @@
 .. highlightlang:: rest
 
 reStructuredText Primer
 =======================
 
 This section is a brief introduction to reStructuredText (reST) concepts and
-syntax, intended to provide authors with enough information to author
-documents productively.
-Since reST was designed to be a simple, unobtrusive markup language, this will
-not take too long.
+syntax, intended to provide authors with enough information to author documents
+productively.  Since reST was designed to be a simple, unobtrusive markup
+language, this will not take too long.
 
 .. seealso::
 
     The authoritative `reStructuredText User
     Documentation <http://docutils.sourceforge.net/rst.html>`_.
 
 
 Paragraphs
 ----------
 
-The paragraph is the most basic block in a reST document.
-Paragraphs are simply chunks of text
-separated by one or more blank lines.  As in Python, indentation is significant
-in reST, so all lines of the same paragraph must be left-aligned
+The paragraph is the most basic block in a reST document.  Paragraphs are simply
+chunks of text separated by one or more blank lines.  As in Python, indentation
+is significant in reST, so all lines of the same paragraph must be left-aligned
 to the same level of indentation.
 
 
 Inline markup
 -------------
 
 The standard reST inline markup is quite simple: use
 
 * one asterisk: ``*text*`` for emphasis (italics),
 * two asterisks: ``**text**`` for strong emphasis (boldface), and
 * backquotes: ````text```` for code samples.
 
@@ -54,27 +52,31 @@
 
 Lists and Quotes
 ----------------
 
 List markup is natural: just place an asterisk at the start of a paragraph and
 indent properly.  The same goes for numbered lists; they can also be
 autonumbered using a ``#`` sign::
 
    * This is a bulleted list.
    * It has two items, the second
      item uses two lines.
 
+   1. This is a numbered list.
+   2. It has two items too.
+
    #. This is a numbered list.
    #. It has two items too.
 
+
 Nested lists are possible, but be aware that they must be separated from the
 parent list items by blank lines::
 
    * this is
    * a list
 
      * with a nested list
      * and some subitems
 
    * and here the parent list continues
 
 Definition lists are created as follows::
@@ -87,25 +89,25 @@
    next term
       Description.
 
 
 Paragraphs are quoted by just indenting them more than the surrounding
 paragraphs.
 
 
 Source Code
 -----------
 
 Literal code blocks are introduced by ending a paragraph with the special marker
-``::``.  The literal block must be indented, to be able to include blank lines::
+``::``.  The literal block must be indented::
 
    This is a normal text paragraph. The next paragraph is a code sample::
 
       It is not processed in any way, except
       that the indentation is removed.
 
       It can span multiple lines.
 
    This is a normal text paragraph again.
 
 The handling of the ``::`` marker is smart:
 
@@ -201,32 +203,41 @@
 ---------
 
 For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote
 body at the bottom of the document after a "Footnotes" rubric heading, like so::
 
    Lorem ipsum [#]_ dolor sit amet ... [#]_
 
    .. rubric:: Footnotes
 
    .. [#] Text of the first footnote.
    .. [#] Text of the second footnote.
 
+You can also explicitly number the footnotes for better context.
+
 
 Comments
 --------
 
 Every explicit markup block which isn't a valid markup construct (like the
-footnotes above) is regared as a comment.
+footnotes above) is regarded as a comment.
 
 
 Source encoding
 ---------------
 
 Since the easiest way to include special characters like em dashes or copyright
 signs in reST is to directly write them as Unicode characters, one has to
 specify an encoding:
 
 All Python documentation source files must be in UTF-8 encoding, and the HTML
 documents written from them will be in that encoding as well.
 
 
-XXX: Gotchas
+Gotchas
+-------
+
+There are some problems one commonly runs into while authoring reST documents:
+
+* **Separation of inline markup:** As said above, inline markup spans must be
+  separated from the surrounding text by non-word characters, you have to use
+  an escaped space to get around that.
