doc: Rework "markup" documents

These are going to form the basis of a future 'directive' document, so
we do some cleanup before this happens. There are a number of cleanup
items.

- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/markup/code.rst

@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 .. _code-examples:
 
@@ -8,14 +8,16 @@ Showing code examples
 .. index:: pair: code; examples
            single: sourcecode
 
+.. todo:: Rework this to remove the bullet points
+
 Examples of Python source code or interactive sessions are represented using
 standard reST literal blocks.  They are started by a ``::`` at the end of the
 preceding paragraph and delimited by indentation.
 
 Representing an interactive session requires including the prompts and output
 along with the Python code.  No special markup is required for interactive
-sessions.  After the last line of input or output presented, there should not be
+sessions.  After the last line of input or output presented, there should not
-an "unused" primary prompt; this is an example of what *not* to do::
+be an "unused" primary prompt; this is an example of what *not* to do::
 
    >>> 1 + 1
    2
@@ -24,10 +26,10 @@ an "unused" primary prompt; this is an example of what *not* to do::
 Syntax highlighting is done with `Pygments <http://pygments.org>`_ and handled
 in a smart way:
 
-* There is a "highlighting language" for each source file.  Per default, this is
+* There is a "highlighting language" for each source file.  Per default, this
-  ``'python'`` as the majority of files will have to highlight Python snippets,
+  is ``'python'`` as the majority of files will have to highlight Python
-  but the doc-wide default can be set with the :confval:`highlight_language`
+  snippets, but the doc-wide default can be set with the
-  config value.
+  :confval:`highlight_language` config value.
 
 * Within Python highlighting mode, interactive sessions are recognized
   automatically and highlighted appropriately.  Normal Python code is only
@@ -44,7 +46,8 @@ in a smart way:
 
         .. highlight:: c
 
-     This language is used until the next ``highlight`` directive is encountered.
+     This language is used until the next ``highlight`` directive is
+     encountered.
 
 * For documents that have to show snippets in different languages, there's also
   a :rst:dir:`code-block` directive that is given the highlighting language
@@ -78,9 +81,9 @@ Line numbers
 ^^^^^^^^^^^^
 
 Pygments can generate line numbers for code blocks.  For
-automatically-highlighted blocks (those started by ``::``), line numbers must be
+automatically-highlighted blocks (those started by ``::``), line numbers must
-switched on in a :rst:dir:`highlight` directive, with the ``linenothreshold``
+be switched on in a :rst:dir:`highlight` directive, with the
-option::
+``linenothreshold`` option::
 
    .. highlight:: python
       :linenothreshold: 5
@@ -131,13 +134,13 @@ Includes
 
    Longer displays of verbatim text may be included by storing the example text
    in an external file containing only plain text.  The file may be included
-   using the ``literalinclude`` directive. [1]_ For example, to include the
+   using the ``literalinclude`` directive. [#]_ For example, to include the
    Python source file :file:`example.py`, use::
 
       .. literalinclude:: example.py
 
-   The file name is usually relative to the current file's path.  However, if it
+   The file name is usually relative to the current file's path.  However, if
-   is absolute (starting with ``/``), it is relative to the top source
+   it is absolute (starting with ``/``), it is relative to the top source
    directory.
 
    Tabs in the input are expanded if you give a ``tab-width`` option with the
@@ -168,8 +171,8 @@ Includes
       .. literalinclude:: example.py
          :pyobject: Timer.start
 
-   This would only include the code lines belonging to the ``start()`` method in
+   This would only include the code lines belonging to the ``start()`` method
-   the ``Timer`` class within the file.
+   in the ``Timer`` class within the file.
 
    Alternately, you can specify exactly which lines to include by giving a
    ``lines`` option::
@@ -181,16 +184,17 @@ Includes
 
    Another way to control which part of the file is included is to use the
    ``start-after`` and ``end-before`` options (or only one of them).  If
-   ``start-after`` is given as a string option, only lines that follow the first
+   ``start-after`` is given as a string option, only lines that follow the
-   line containing that string are included.  If ``end-before`` is given as a
+   first line containing that string are included.  If ``end-before`` is given
-   string option, only lines that precede the first lines containing that string
+   as a string option, only lines that precede the first lines containing that
-   are included.
+   string are included.
 
    With lines selected using ``start-after`` it is still possible to use
-   ``lines``, the first allowed line having by convention the line number ``1``.
+   ``lines``, the first allowed line having by convention the line number
+   ``1``.
 
-   When lines have been selected in any of the ways described above, the
+   When lines have been selected in any of the ways described above, the line
-   line numbers in ``emphasize-lines`` refer to those selected lines, counted
+   numbers in ``emphasize-lines`` refer to those selected lines, counted
    consecutively starting at ``1``.
 
    When specifying particular parts of a file to display, it can be useful to
@@ -202,15 +206,14 @@ Includes
    ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
    highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
 
-
+   If you want to show the diff of the code, you can specify the old file by
-   If you want to show the diff of the code, you can specify the old
+   giving a ``diff`` option::
-   file by giving a ``diff`` option::
 
       .. literalinclude:: example.py
          :diff: example.py.orig
 
-   This shows the diff between example.py and example.py.orig with unified diff
+   This shows the diff between ``example.py`` and ``example.py.orig`` with
-   format.
+   unified diff format.
 
    .. versionadded:: 0.4.3
       The ``encoding`` option.
@@ -242,11 +245,9 @@ For example::
 
       print 'Explicit is better than implicit.'
 
-
 :rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option.
-``caption`` has an additional feature that if you leave the value empty, the shown
+``caption`` has an additional feature that if you leave the value empty, the
-filename will be exactly the one given as an argument.
+shown filename will be exactly the one given as an argument.
-
 
 Dedent
 ^^^^^^
@@ -263,8 +264,7 @@ block. For example::
 
 :rst:dir:`code-block` also supports the ``dedent`` option.
 
-
 .. rubric:: Footnotes
 
-.. [1] There is a standard ``.. include`` directive, but it raises errors if the
+.. [#] There is a standard ``.. include`` directive, but it raises errors if the
        file is not found.  This one only emits a warning.

doc/markup/index.rst

@@ -3,8 +3,9 @@
 Sphinx Markup Constructs
 ========================
 
-Sphinx adds a lot of new directives and interpreted text roles to `standard reST
+Sphinx adds a lot of new directives and interpreted text roles to `standard
-markup`_.  This section contains the reference material for these facilities.
+reST markup`_.  This section contains the reference material for these
+facilities.
 
 .. toctree::
 

doc/markup/misc.rst

@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 Miscellaneous markup
 ====================
@@ -186,10 +186,9 @@ Use :ref:`reStructuredText tables <rst-tables>`, i.e. either
 The :dudir:`table` directive serves as optional wrapper of the *grid* and
 *simple* syntaxes.
 
-They work fine in
+They work fine in HTML output, however there are some gotchas when using tables
-HTML output, however there are some gotchas when using tables in LaTeX: the
+in LaTeX: the column width is hard to determine correctly automatically.  For
-column width is hard to determine correctly automatically.  For this reason, the
+this reason, the following directive exists:
-following directive exists:
 
 .. rst:directive:: .. tabularcolumns:: column spec
 
@@ -297,6 +296,8 @@ following directive exists:
 Math
 ----
 
+.. todo:: Move this in here.
+
 See :ref:`math-support`.
 
 .. rubric:: Footnotes
@@ -307,4 +308,3 @@ See :ref:`math-support`.
 
        Note that the current builder tag is not available in ``conf.py``, it is
        only available after the builder is initialized.
-

doc/markup/para.rst

@@ -1,4 +1,4 @@
-.. highlight:: rest
+.. highlight:: rst
 
 Paragraph-level markup
 ----------------------
@@ -7,7 +7,7 @@ Paragraph-level markup
            pair: changes; in version
 
 These directives create short paragraphs and can be used inside information
-units as well as normal text:
+units as well as normal text.
 
 .. rst:directive:: .. note::
 
@@ -61,9 +61,6 @@ units as well as normal text:
       .. deprecated:: 3.1
          Use :func:`spam` instead.
 
-
---------------
-
 .. rst:directive:: seealso
 
    Many sections include a list of references to module documentation or
@@ -104,7 +101,6 @@ units as well as normal text:
       assumed to only contain footnote definitions and therefore would create an
       empty heading.
 
-
 .. rst:directive:: centered
 
    This directive creates a centered boldfaced line of text.  Use it as
@@ -116,7 +112,6 @@ units as well as normal text:
       This presentation-only directive is a legacy from older versions.  Use a
       :rst:dir:`rst-class` directive instead and add an appropriate style.
 
-
 .. rst:directive:: hlist
 
    This directive must contain a bullet list.  It will transform it into a more
@@ -138,16 +133,6 @@ units as well as normal text:
    .. versionadded:: 0.6
 
 
-Table-of-contents markup
-------------------------
-
-The :rst:dir:`toctree` directive, which generates tables of contents of
-subdocuments, is described in :ref:`toctree-directive`.
-
-For local tables of contents, use the standard reST :dudir:`contents directive
-<table-of-contents>`.
-
-
 .. _glossary-directive:
 
 Glossary
@@ -222,11 +207,11 @@ the definition of the symbol.  There is this directive:
 
 .. rst:directive:: .. productionlist:: [name]
 
-   This directive is used to enclose a group of productions.  Each production is
+   This directive is used to enclose a group of productions.  Each production
-   given on a single line and consists of a name, separated by a colon from the
+   is given on a single line and consists of a name, separated by a colon from
-   following definition.  If the definition spans multiple lines, each
+   the following definition.  If the definition spans multiple lines, each
-   continuation line must begin with a colon placed at the same column as in the
+   continuation line must begin with a colon placed at the same column as in
-   first line.
+   the first line.
 
    The argument to :rst:dir:`productionlist` serves to distinguish different
    sets of production lists that belong to different grammars.
@@ -234,9 +219,10 @@ the definition of the symbol.  There is this directive:
    Blank lines are not allowed within ``productionlist`` directive arguments.
 
    The definition can contain token names which are marked as interpreted text
-   (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
+   (e.g. ``sum ::= `integer` "+" `integer```) -- this generates
-   to the productions of these tokens.  Outside of the production list, you can
+   cross-references to the productions of these tokens.  Outside of the
-   reference to token productions using :rst:role:`token`.
+   production list, you can reference to token productions using
+   :rst:role:`token`.
 
    Note that no further reST parsing is done in the production, so that you
    don't have to escape ``*`` or ``|`` characters.

doc/markup/toctree.rst

@@ -1,8 +1,8 @@
 .. highlight:: rst
 .. _toctree-directive:
 
-The TOC tree
+Table of contents
-============
+-----------------
 
 .. index:: pair: table of; contents
 
@@ -16,6 +16,11 @@ tables of contents.  The ``toctree`` directive is the central element.
    Simple "inclusion" of one file in another can be done with the
    :dudir:`include` directive.
 
+.. note::
+
+   For local tables of contents, use the standard reST :dudir:`contents
+   directive <table-of-contents>`.
+
 .. rst:directive:: toctree
 
    This directive inserts a "TOC tree" at the current location, using the
@@ -192,7 +197,7 @@ tables of contents.  The ``toctree`` directive is the central element.
       Added "caption" and "name" option.
 
 Special names
--------------
+^^^^^^^^^^^^^
 
 Sphinx reserves some document names for its own use; you should not try to
 create documents with these names -- it will cause problems.
@@ -204,11 +209,12 @@ The special document names (and pages generated for them) are:
   These are used for the general index, the Python module index, and the search
   page, respectively.
 
-  The general index is populated with entries from modules, all index-generating
+  The general index is populated with entries from modules, all
-  :ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index`
+  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
-  directives.
+  :rst:dir:`index` directives.
 
-  The Python module index contains one entry per :rst:dir:`py:module` directive.
+  The Python module index contains one entry per :rst:dir:`py:module`
+  directive.
 
   The search page contains a form that uses the generated JSON search index and
   JavaScript to full-text search the generated documents for search words; it
@@ -216,9 +222,9 @@ The special document names (and pages generated for them) are:
 
 * every name beginning with ``_``
 
-  Though only few such names are currently used by Sphinx, you should not create
+  Though only few such names are currently used by Sphinx, you should not
-  documents or document-containing directories with such names.  (Using ``_`` as
+  create documents or document-containing directories with such names.  (Using
-  a prefix for a custom template directory is fine.)
+  ``_`` as a prefix for a custom template directory is fine.)
 
 .. warning::
 
@@ -238,5 +244,5 @@ The special document names (and pages generated for them) are:
 
 .. [#] A note on available globbing syntax: you can use the standard shell
        constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
-       these all don't match slashes.  A double star ``**`` can be used to match
+       these all don't match slashes.  A double star ``**`` can be used to
-       any sequence of characters *including* slashes.
+       match any sequence of characters *including* slashes.