Move inline markup description to domains page.

doc/domains.rst

@@ -90,6 +90,24 @@ giving the domain name, i.e. ::
    Reference to :func:`pyfunc`.
 
 
+Cross-referencing syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For cross-reference roles provided by domains, the same facilities exist as for
+general cross-references.  See :ref:`xref-syntax`.
+
+In short:
+
+* You may supply an explicit title and reference target: ``: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.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+
+
 The Python Domain
 -----------------
 
@@ -280,6 +298,75 @@ This will render like this:
       :rtype: list of strings
 
 
+Cross-referencing Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. role:: py:mod
+
+   Reference a module; a dotted name may be used.  This should also be used for
+   package names.
+
+.. role:: py:func
+
+   Reference a Python function; dotted names may be used.  The role text needs
+   not include trailing parentheses to enhance readability; they will be added
+   automatically by Sphinx if the :confval:`add_function_parentheses` config
+   value is true (the default).
+
+.. role:: py:data
+
+   Reference a module-level variable.
+
+.. role:: py:const
+
+   Reference a "defined" constant.  This may be a C-language ``#define`` or a
+   Python variable that is not intended to be changed.
+
+.. role:: py:class
+
+   Reference a class; a dotted name may be used.
+
+.. role:: py:meth
+
+   Reference a method of an object.  The role text can include the type name and
+   the method name; if it occurs within the description of a type, the type name
+   can be omitted.  A dotted name may be used.
+
+.. role:: py:attr
+
+   Reference a data attribute of an object.
+
+.. role:: py:exc
+
+   Reference an exception.  A dotted name may be used.
+
+.. role:: py:obj
+
+   Reference an object of unspecified type.  Useful e.g. as the
+   :confval:`default_role`.
+
+   .. versionadded:: 0.4
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:py:func:`filter``` could refer to a function named ``filter`` in
+the current module, or the built-in function of that name.  In contrast,
+``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
+``foo`` 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 Python's
+:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
+function, while ``:py: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.
+
+
 The C Domain
 ------------
 
@@ -328,6 +415,29 @@ The C domain (name **c**) is suited for documentation of C API.
       .. c:var:: PyObject* PyClass_Type
 
 
+Cross-referencing C constructs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles create cross-references to C-language constructs if they are
+defined in the documentation:
+
+.. role:: c:data
+
+   Reference a C-language variable.
+
+.. role:: c:func
+
+   Reference a C-language function. Should include trailing parentheses.
+
+.. role:: c:macro
+
+   Reference a "simple" C macro, as defined above.
+
+.. role:: c:type
+
+   Reference a C-language type.
+
+
 The Standard Domain
 -------------------
 

doc/intro.rst

@@ -56,5 +56,5 @@ or some (not broken) SVN trunk snapshot.
 Usage
 -----
 
-See :doc:`the tutorial <tutorial>` for an introduction.  It also contains links
+See :doc:`tutorial` for an introduction.  It also contains links to more
-to more advanced sections in this manual for the topics it discusses.
+advanced sections in this manual for the topics it discusses.

doc/markup/inline.rst

@@ -12,11 +12,13 @@ They are written as ``:rolename:`content```.
    free to use it for anything you like, e.g. variable names; use the
    :confval:`default_role` config value to set it to a known role.
 
+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
@@ -32,149 +34,14 @@ more versatile:
 
 * 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
+* If you prefix the content with ``~``, the link text will only be the last
-  text will only be the last component of the target.  For example,
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
-  ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
-  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:
-
-.. role:: mod
-
-   The name of a module; a dotted name may be used.  This should also be used for
-   package names.
-
-.. role:: func
-
-   The name of a Python function; dotted names may be used.  The role text
-   needs not include trailing parentheses to enhance readability; they will be
-   added automatically by Sphinx if the :confval:`add_function_parentheses`
-   config value is true (the default).
-
-.. role:: data
-
-   The name of a module-level variable.
-
-.. role:: const
-
-   The name of a "defined" constant.  This may be a C-language ``#define``
-   or a Python variable that is not intended to be changed.
-
-.. role:: class
-
-   A class name; a dotted name may be used.
-
-.. role:: meth
-
-   The name of a method of an object.  The role text should include the type
-   name and the method name; if it occurs within the description of a type,
-   the type name can be omitted.  A dotted name may be used.
-
-.. role:: attr
-
-   The name of a data attribute of an object.
-
-.. role:: exc
-
-   The name of an exception. A dotted name may be used.
-
-.. role:: obj
-
-   The name of an object of unspecified type.  Useful e.g. as the
-   :confval:`default_role`.
-
-   .. versionadded:: 0.4
-
-The name enclosed in this markup can include a module name and/or a class name.
-For example, ``:func:`filter``` could refer to a function named ``filter`` in
-the current module, or the built-in function of that name.  In contrast,
-``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
-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 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 documentation:
-
-.. role:: cdata
-
-   The name of a C-language variable.
-
-.. role:: cfunc
-
-   The name of a C-language function. Should include trailing parentheses.
-
-.. role:: cmacro
-
-   The name of a "simple" C macro, as defined above.
-
-.. role:: ctype
-
-   The name of a C-language type.
-
-
-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 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:
-
-.. role:: term
-
-   Reference to a term in the glossary.  The glossary is created using the
-   ``glossary`` directive containing a definition list with terms and
-   definitions.  It does not have to be in the same file as the ``term`` markup,
-   for example the Python docs have one global glossary in the ``glossary.rst``
-   file.
-
-   If you use a term that's not explained in a glossary, you'll get a warning
-   during build.
-
-
 .. _ref-role:
 
 Cross-referencing arbitrary locations
@@ -405,6 +272,48 @@ Note that there are no special roles for including hyperlinks as you can use
 the standard reST markup for that purpose.
 
 
+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 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:`option` directive, if it
+   exists.
+
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. role:: term
+
+   Reference to a term in the glossary.  The glossary is created using the
+   ``glossary`` directive containing a definition list with terms and
+   definitions.  It does not have to be in the same file as the ``term`` markup,
+   for example the Python docs have one global glossary in the ``glossary.rst``
+   file.
+
+   If you use a term that's not explained in a glossary, you'll get a warning
+   during build.
+
+
 .. _default-substitutions:
 
 Substitutions

doc/markup/misc.rst

@@ -87,10 +87,10 @@ Including content based on tags
 Tables
 ------
 
-Use standard reStructuredText tables.  They work fine in HTML output, however
+Use :ref:`standard reStructuredText tables <rst-tables>`.  They work fine in
-there are some gotchas when using tables in LaTeX: the column width is hard to
+HTML output, however there are some gotchas when using tables in LaTeX: the
-determine correctly automatically.  For this reason, the following directive
+column width is hard to determine correctly automatically.  For this reason, the
-exists:
+following directive exists:
 
 .. directive:: .. tabularcolumns:: column spec
 

doc/markup/para.rst

@@ -231,7 +231,7 @@ derived forms), but provides enough to allow context-free grammars to be
 displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
 the definition of the symbol.  There is this directive:
 
-.. directive:: productionlist
+.. 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
@@ -239,17 +239,19 @@ the definition of the symbol.  There is this directive:
    continuation line must begin with a colon placed at the same column as in the
    first line.
 
+   The argument to :dir:`productionlist` serves to distinguish different sets of
+   production lists that belong to different grammars.
+
    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.
+   to the productions of these tokens.  Outside of the production list, you can
+   reference to token productions using :role:`token`.
 
    Note that no further reST parsing is done in the production, so that you
    don't have to escape ``*`` or ``|`` characters.
 
-.. XXX describe optional first parameter
-
 The following is an example taken from the Python Reference Manual::
 
    .. productionlist::

doc/rest.rst

@@ -140,6 +140,8 @@ That way, the second sentence in the above example's first paragraph would be
 rendered as "The next paragraph is a code sample:".
 
 
+.. _rst-tables:
+
 Tables
 ------