Update documentation, add more content.

1 files changed, 89 insertions, 55 deletions

diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index d0f52342a..2349bf7ea 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -1,10 +1,9 @@
 .. highlight:: rest
 
 Inline markup
--------------
+=============
 
-As said before, Sphinx uses interpreted text roles to insert semantic markup in
-documents.
+Sphinx uses interpreted text roles to insert semantic markup into documents.
 
 Variable names are an exception, they should be marked simply with ``*var*``.
 
@@ -12,8 +11,38 @@ For all other roles, you have to write ``:rolename:`content```.
 
 .. note::
 
-   For all cross-referencing roles, if you prefix the content with ``!``, no
-   reference/hyperlink will be created.
+   The default role (```content```) has no special meaning by default.  You are
+   free to use it for anything you like. 
+
+
+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
+to the item named *target* of the type indicated by *role*.  The links's text
+will be the same as *target*.
+
+There are some additional facilities, however, that make cross-referencing 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
+  text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* For the Python object roles, if you prefix the content with ``~``, the link
+  text will only be the last component of the target.  For example,
+  ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
+  display ``get`` as the link text.
+
+  In HTML output, the link's ``title`` attribute (that is e.g. shown as a
+  tool-tip on mouse-hover) will always be the full target name.
+
+
+Cross-referencing Python objects
+--------------------------------
 
 The following roles refer to objects in modules and are possibly hyperlinked if
 a matching identifier is found:
@@ -64,15 +93,19 @@ module.
 Normally, names in these roles are searched first without any further
 qualification, then with the current module name prepended, then with the
 current module and class name (if any) prepended.  If you prefix the name with a
-dot, this order is reversed.  For example, in the documentation of the
+dot, this order is reversed.  For example, in the documentation of Python's
 :mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
 while ``:func:`.open``` refers to :func:`codecs.open`.
 
 A similar heuristic is used to determine whether the name is an attribute of
 the currently documented class.
 
+
+Cross-referencing C constructs
+------------------------------
+
 The following roles create cross-references to C-language constructs if they
-are defined in the API documentation:
+are defined in the documentation:
 
 .. role:: cdata
 
@@ -91,19 +124,33 @@ are defined in the API documentation:
    The name of a C-language type.
 
 
-The following roles do possibly create a cross-reference, but do not refer
-to objects:
+Cross-referencing other items of interest
+-----------------------------------------
+
+The following roles do possibly create a cross-reference, but do not refer to
+objects:
+
+.. role:: envvar
+
+   An environment variable.  Index entries are generated.  Also generates a link
+   to the matching :dir:`envvar` directive, if it exists.
 
 .. role:: token
 
-   The name of a grammar token (used in the reference manual to create links
-   between production displays).
+   The name of a grammar token (used to create links between
+   :dir:`productionlist` directives).
 
 .. role:: keyword
 
    The name of a keyword in Python.  This creates a link to a reference label
    with that name, if it exists.
 
+.. role:: option
+
+   A command-line option to an executable program.  The leading hyphen(s) must
+   be included.  This generates a link to a :dir:`cmdoption` directive, if it
+   exists.
+
 
 The following role creates a cross-reference to the term in the glossary:
 
@@ -118,7 +165,37 @@ The following role creates a cross-reference to the term in the glossary:
    If you use a term that's not explained in a glossary, you'll get a warning
    during build.
 
----------
+
+Cross-referencing arbitrary locations
+-------------------------------------
+
+To support cross-referencing to arbitrary locations in the documentation, the
+standard reST labels used.  Of course, for this to work label names must be
+unique throughout the entire documentation.  There are two ways in which you can
+refer to labels:
+
+* If you place a label directly before a section title, you can reference to it
+  with ``:ref:`label-name```.  Example::
+
+     .. _my-reference-label:
+
+     Section to cross-reference
+     --------------------------
+
+     This is the text of the section.
+
+     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
+  title being "Section to cross-reference".
+
+* Labels that aren't placed before a section title can still be referenced to,
+  but you must give the link an explicit title, using this syntax: ``:ref:`Link
+  title <label-name>```.
+
+
+Other semantic markup
+---------------------
 
 The following roles don't do anything special except formatting the text
 in a different style:
@@ -132,10 +209,6 @@ in a different style:
    Mark the defining instance of a term in the text.  (No index entries are
    generated.)
 
-.. role:: envvar
-
-   An environment variable.  Index entries are generated.
-
 .. role:: file
 
    The name of a file or directory.  Within the contents, you can use curly
@@ -209,11 +282,6 @@ in a different style:
 
    The name of a Usenet newsgroup.
 
-.. role:: option
-
-   A command-line option to an executable program.  The leading hyphen(s) must
-   be included.
-
 .. role:: program
 
    The name of an executable program.  This may differ from the file name for
@@ -232,10 +300,6 @@ in a different style:
    If you don't need the "variable part" indication, use the standard
    ````code```` instead.   
 
-.. role:: var
-
-   A Python or C variable or parameter name.
-
 
 The following roles generate external links:
 
@@ -279,33 +343,3 @@ They are set in the build configuration file.
    Replaced by either today's date, or the date set in the build configuration
    file.  Normally has the format ``April 14, 2007``.  Set by
    :confval:`today_fmt` and :confval:`today`.
-
-
-.. _doc-ref-role:
-
-Cross-linking markup
---------------------
-
-To support cross-referencing to arbitrary sections in the documentation, the
-standard reST labels used.  Of course, for this to work label names must be
-unique throughout the entire documentation.  There are two ways in which you can
-refer to labels:
-
-* If you place a label directly before a section title, you can reference to it
-  with ``:ref:`label-name```.  Example::
-
-     .. _my-reference-label:
-
-     Section to cross-reference
-     --------------------------
-
-     This is the text of the section.
-
-     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
-  title being "Section to cross-reference".
-
-* Labels that aren't placed before a section title can still be referenced to,
-  but you must give the link an explicit title, using this syntax: ``:ref:`Link
-  title <label-name>```.