doc: Add "roles" doc to restructuredtext section

This is essentially the 'markup/inline' with a few small fixes. There
are also some modifications to the basic rST guide to highlight what a
role is; we were doing this for directives but not roles.

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

doc/glossary.rst

@@ -81,7 +81,7 @@ Glossary
    role
       A reStructuredText markup element that allows marking a piece of text.
       Like directives, roles are extensible.  The basic syntax looks like this:
-      ``:rolename:`content```.  See :ref:`inlinemarkup` for details.
+      ``:rolename:`content```.  See :ref:`rst-inline-markup` for details.
 
    source directory
       The directory which, including its subdirectories, contains all source

doc/markup/index.rst

@@ -11,7 +11,6 @@ markup`_.  This section contains the reference material for these facilities.
    toctree
    para
    code
-   inline
    misc
 
 More markup is added by :ref:`domains`.

doc/usage/restructuredtext/basics.rst

@@ -27,7 +27,7 @@ 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.
 
 
-.. _inlinemarkup:
+.. _rst-inline-markup:
 
 Inline markup
 -------------
@@ -50,22 +50,8 @@ Be aware of some restrictions of this markup:
 
 These restrictions may be lifted in future versions of the docutils.
 
-reST also allows for custom "interpreted text roles", which signify that the
+It is also possible to replace or expand upon some of this inline markup with
-enclosed text should be interpreted in a specific way.  Sphinx uses this to
+roles. Refer to :ref:`rst-roles-alt` for more information.
-provide semantic markup and cross-referencing of identifiers, as described in
-the appropriate section.  The general syntax is ``:rolename:`content```.
-
-Standard reST provides the following roles:
-
-* :durole:`emphasis` -- alternate spelling for ``*emphasis*``
-* :durole:`strong` -- alternate spelling for ``**strong**``
-* :durole:`literal` -- alternate spelling for ````literal````
-* :durole:`subscript` -- subscript text
-* :durole:`superscript` -- superscript text
-* :durole:`title-reference` -- for titles of books, periodicals, and other
-  materials
-
-See :ref:`inline-markup` for roles added by Sphinx.
 
 
 Lists and Quote-like blocks
@@ -249,6 +235,33 @@ documentation), and use a deeper nesting level, but keep in mind that most
 target formats (HTML, LaTeX) have a limited supported nesting depth.
 
 
+.. TODO This ref should be 'rst-roles', but that already exists. Rename the
+.. other ones
+
+.. _rst-roles-alt:
+
+Roles
+-----
+
+A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline
+piece of explicit markup. It signifies that that the enclosed text should be
+interpreted in a specific way.  Sphinx uses this to provide semantic markup and
+cross-referencing of identifiers, as described in the appropriate section.  The
+general syntax is ``:rolename:`content```.
+
+Docutils supports the following roles:
+
+* :durole:`emphasis` -- equivalent of ``*emphasis*``
+* :durole:`strong` -- equivalent of ``**strong**``
+* :durole:`literal` -- equivalent of ````literal````
+* :durole:`subscript` -- subscript text
+* :durole:`superscript` -- superscript text
+* :durole:`title-reference` -- for titles of books, periodicals, and other
+  materials
+
+Refer to :doc:`roles` for roles added by Sphinx.
+
+
 Explicit Markup
 ---------------
 

doc/usage/restructuredtext/index.rst

@@ -16,3 +16,4 @@ __ http://docutils.sourceforge.net/rst.html
    :maxdepth: 2
 
    basics
+   roles

doc/usage/restructuredtext/roles.rst

@@ -1,9 +1,8 @@
-.. highlight:: rest
+.. highlight:: rst
 
-.. _inline-markup:
+=====
-
+Roles
-Inline markup
+=====
-=============
 
 Sphinx uses interpreted text roles to insert semantic markup into documents.
 They are written as ``:rolename:`content```.
@@ -22,15 +21,15 @@ See :ref:`domains` for roles added by domains.
 .. _xref-syntax:
 
 Cross-referencing syntax
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 Cross-references are generated by many semantic interpreted text roles.
-Basically, you only need to write ``:role:`target```, and a link will be created
+Basically, you only need to write ``:role:`target```, and a link will be
-to the item named *target* of the type indicated by *role*.  The link's text
+created to the item named *target* of the type indicated by *role*.  The link's
-will be the same as *target*.
+text will be the same as *target*.
 
-There are some additional facilities, however, that make cross-referencing roles
+There are some additional facilities, however, that make cross-referencing
-more versatile:
+roles more versatile:
 
 * You may supply an explicit title and reference target, like in reST direct
   hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
@@ -50,7 +49,7 @@ more versatile:
 .. _any-role:
 
 Cross-referencing anything
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. rst:role:: any
 
@@ -90,9 +89,8 @@ Cross-referencing anything
    :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
    found, all object types of intersphinx inventories are also searched.
 
-
 Cross-referencing objects
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 These roles are described with their respective domains:
 
@@ -106,7 +104,7 @@ These roles are described with their respective domains:
 .. _ref-role:
 
 Cross-referencing arbitrary locations
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. rst:role:: ref
 
@@ -116,7 +114,7 @@ Cross-referencing arbitrary locations
    refer to labels:
 
    * If you place a label directly before a section title, you can reference to
-     it with ``:ref:`label-name```.  Example::
+     it with ``:ref:`label-name```.  For example::
 
         .. _my-reference-label:
 
@@ -127,11 +125,11 @@ Cross-referencing arbitrary locations
 
         It refers to the section itself, see :ref:`my-reference-label`.
 
-     The ``:ref:`` role would then generate a link to the section, with the link
+     The ``:ref:`` role would then generate a link to the section, with the
-     title being "Section to cross-reference".  This works just as well when
+     link title being "Section to cross-reference".  This works just as well
-     section and reference are in different source files.
+     when section and reference are in different source files.
 
-     Automatic labels also work with figures: given ::
+     Automatic labels also work with figures. For example::
 
         .. _my-figure:
 
@@ -139,8 +137,8 @@ Cross-referencing arbitrary locations
 
            Figure caption
 
-     a reference ``:ref:`my-figure``` would insert a reference to the figure
+     In this case, a  reference ``:ref:`my-figure``` would insert a reference
-     with link text "Figure caption".
+     to the figure with link text "Figure caption".
 
      The same works for tables that are given an explicit caption using the
      :dudir:`table` directive.
@@ -151,17 +149,17 @@ Cross-referencing arbitrary locations
 
    .. note::
 
-      Reference labels must start with an underscore. When referencing a
+      Reference labels must start with an underscore. When referencing a label,
-      label, the underscore must be omitted (see examples above).
+      the underscore must be omitted (see examples above).
 
    Using :rst:role:`ref` is advised over standard reStructuredText links to
    sections (like ```Section title`_``) because it works across files, when
-   section headings are changed, and for all builders that support
+   section headings are changed, will raise warnings if incorrect, and works
-   cross-references.
+   for all builders that support cross-references.
 
 
 Cross-referencing documents
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 0.6
 
@@ -180,7 +178,7 @@ There is also a way to directly link to documents:
 
 
 Referencing downloadable files
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 0.6
 
@@ -213,7 +211,7 @@ Referencing downloadable files
          See :download:`this example script <../example.py>`.
 
 Cross-referencing figures by figure number
-------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 1.3
 
@@ -238,7 +236,7 @@ Cross-referencing figures by figure number
    so this role inserts not a reference but the label or the link text.
 
 Cross-referencing other items of interest
------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following roles do possibly create a cross-reference, but do not refer to
 objects:
@@ -280,10 +278,10 @@ The following role creates a cross-reference to a term in a
 
 
 Other semantic markup
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
-The following roles don't do anything special except formatting the text
+The following roles don't do anything special except formatting the text in a
-in a different style:
+different style:
 
 .. rst:role:: abbr
 
@@ -331,22 +329,22 @@ in a different style:
 .. rst:role:: kbd
 
    Mark a sequence of keystrokes.  What form the key sequence takes may depend
-   on platform- or application-specific conventions.  When there are no relevant
+   on platform- or application-specific conventions.  When there are no
-   conventions, the names of modifier keys should be spelled out, to improve
+   relevant conventions, the names of modifier keys should be spelled out, to
-   accessibility for new users and non-native speakers.  For example, an
+   improve accessibility for new users and non-native speakers.  For example,
-   *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
+   an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
    reference to a specific application or platform, the same sequence should be
    marked as ``:kbd:`Control-x Control-f```.
 
 .. rst:role:: mailheader
 
    The name of an RFC 822-style mail header.  This markup does not imply that
-   the header is being used in an email message, but can be used to refer to any
+   the header is being used in an email message, but can be used to refer to
-   header of the same "style."  This is also used for headers defined by the
+   any header of the same "style."  This is also used for headers defined by
-   various MIME specifications.  The header name should be entered in the same
+   the various MIME specifications.  The header name should be entered in the
-   way it would normally be found in practice, with the camel-casing conventions
+   same way it would normally be found in practice, with the camel-casing
-   being preferred where there is more than one common usage. For example:
+   conventions being preferred where there is more than one common usage. For
-   ``:mailheader:`Content-Type```.
+   example: ``:mailheader:`Content-Type```.
 
 .. rst:role:: makevar
 
@@ -354,9 +352,9 @@ in a different style:
 
 .. rst:role:: manpage
 
-   A reference to a Unix manual page including the section,
+   A reference to a Unix manual page including the section, e.g.
-   e.g. ``:manpage:`ls(1)```. Creates a hyperlink to an external site
+   ``:manpage:`ls(1)```. Creates a hyperlink to an external site rendering the
-   rendering the manpage if :confval:`manpages_url` is defined.
+   manpage if :confval:`manpages_url` is defined.
 
 .. rst:role:: menuselection
 
@@ -370,8 +368,8 @@ in a different style:
 
       :menuselection:`Start --> Programs`
 
-   When including a selection that includes some trailing indicator, such as the
+   When including a selection that includes some trailing indicator, such as
-   ellipsis some operating systems use to indicate that the command opens a
+   the ellipsis some operating systems use to indicate that the command opens a
    dialog, the indicator should be omitted from the selection name.
 
    ``menuselection`` also supports ampersand accelerators just like
@@ -386,6 +384,8 @@ in a different style:
 
    The name of a Usenet newsgroup.
 
+.. todo:: Is this not part of the standard domain?
+
 .. rst:role:: program
 
    The name of an executable program.  This may differ from the file name for
@@ -432,7 +432,7 @@ the standard reST markup for that purpose.
 .. _default-substitutions:
 
 Substitutions
-~~~~~~~~~~~~~
+-------------
 
 The documentation system provides three substitutions that are defined by
 default. They are set in the build configuration file.