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>

5 files changed, 72 insertions, 79 deletions

diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 19ec0cc4c..3152630f4 100644
--- a/doc/markup/code.rst
+++ b/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
-an "unused" primary prompt; this is an example of what *not* to do::
+sessions.  After the last line of input or output presented, there should not
+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
-  ``'python'`` as the majority of files will have to highlight Python snippets,
-  but the doc-wide default can be set with the :confval:`highlight_language`
-  config value.
+* There is a "highlighting language" for each source file.  Per default, this
+  is ``'python'`` as the majority of files will have to highlight Python
+  snippets, but the doc-wide default can be set with the
+  :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
-switched on in a :rst:dir:`highlight` directive, with the ``linenothreshold``
-option::
+automatically-highlighted blocks (those started by ``::``), line numbers must
+be switched on in a :rst:dir:`highlight` directive, with the
+``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
-   is absolute (starting with ``/``), it is relative to the top source
+   The file name is usually relative to the current file's path.  However, if
+   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
-   the ``Timer`` class within the file.
+   This would only include the code lines belonging to the ``start()`` method
+   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
-   line containing that string are included.  If ``end-before`` is given as a
-   string option, only lines that precede the first lines containing that string
-   are included.
+   ``start-after`` is given as a string option, only lines that follow the
+   first line containing that string are included.  If ``end-before`` is given
+   as a string option, only lines that precede the first lines containing that
+   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
-   line numbers in ``emphasize-lines`` refer to those selected lines, counted
+   When lines have been selected in any of the ways described above, the line
+   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 giving a ``diff`` option::
+   If you want to show the diff of the code, you can specify the old 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
-   format.
+   This shows the diff between ``example.py`` and ``example.py.orig`` with
+   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
-filename will be exactly the one given as an argument.
-
+``caption`` has an additional feature that if you leave the value empty, the
+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.
diff --git a/doc/markup/index.rst b/doc/markup/index.rst
index c3f23967e..33e876556 100644
--- a/doc/markup/index.rst
+++ b/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
-markup`_.  This section contains the reference material for these facilities.
+Sphinx adds a lot of new directives and interpreted text roles to `standard
+reST markup`_.  This section contains the reference material for these
+facilities.
 
 .. toctree::
 
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index a4fbce5a0..5705edf8d 100644
--- a/doc/markup/misc.rst
+++ b/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
-HTML output, however there are some gotchas when using tables in LaTeX: the
-column width is hard to determine correctly automatically.  For this reason, the
-following directive exists:
+They work fine in HTML output, however there are some gotchas when using tables
+in LaTeX: the column width is hard to determine correctly automatically.  For
+this reason, the 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.
-
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index ba2cc52f5..9dae710d3 100644
--- a/doc/markup/para.rst
+++ b/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
-   given on a single line and consists of a name, separated by a colon from 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
-   first line.
+   This directive is used to enclose a group of productions.  Each production
+   is given on a single line and consists of a name, separated by a colon from
+   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 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
-   to the productions of these tokens.  Outside of the production list, you can
-   reference to token productions using :rst:role:`token`.
+   (e.g. ``sum ::= `integer` "+" `integer```) -- this generates
+   cross-references to the productions of these tokens.  Outside of the
+   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.
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 78a72c1b4..51401ba50 100644
--- a/doc/markup/toctree.rst
+++ b/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
-  :ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index`
-  directives.
+  The general index is populated with entries from modules, all
+  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
+  :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
-  documents or document-containing directories with such names.  (Using ``_`` as
-  a prefix for a custom template directory is fine.)
+  Though only few such names are currently used by Sphinx, you should not
+  create documents or document-containing directories with such names.  (Using
+  ``_`` 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
-       any sequence of characters *including* slashes.
+       these all don't match slashes.  A double star ``**`` can be used to
+       match any sequence of characters *including* slashes.