[Python-checkins] devguide: Closes #15569: some roles do create more than formatting

[georg.brandl]

https://hg.python.org/devguide/rev/bef3ddfe5d09
changeset:   716:bef3ddfe5d09
user:        Georg Brandl <georg at python.org>
date:        Sat Oct 11 14:39:21 2014 +0200
summary:
  Closes #15569: some roles do create more than formatting

files:
  documenting.rst |  42 ++++++++++++++++++++----------------
  1 files changed, 23 insertions(+), 19 deletions(-)


diff --git a/documenting.rst b/documenting.rst
--- a/documenting.rst
+++ b/documenting.rst
@@ -946,6 +946,8 @@
 A similar heuristic is used to determine whether the name is an attribute of
 the currently documented class.
 
+---------
+
 The following roles create cross-references to C-language constructs if they
 are defined in the API documentation:
 
@@ -969,15 +971,34 @@
 
    The name of a C type member, as defined above.
 
+---------
 
-The following role does possibly create a cross-reference, but does not refer
-to objects:
+The following roles do not refer to objects, but can create cross-references or
+internal links:
+
+.. describe:: envvar
+
+   An environment variable.  Index entries are generated.
+
+.. describe:: keyword
+
+   The name of a Python keyword.  Using this role will generate a link to the
+   documentation of the keyword.  ``True``, ``False`` and ``None`` do not use
+   this role, but simple code markup (````True````), given that they're
+   fundamental to the language and should be known to any programmer.
+
+.. describe:: option
+
+   A command-line option of Python.  The leading hyphen(s) must be included.
+   If a matching ``cmdoption`` directive exists, it is linked to.  For options
+   of other programs or scripts, use simple ````code```` markup.
 
 .. describe:: token
 
    The name of a grammar token (used in the reference manual to create links
    between production displays).
 
+---------
 
 The following role creates a cross-reference to the term in the glossary:
 
@@ -1006,10 +1027,6 @@
    Mark the defining instance of a term in the text.  (No index entries are
    generated.)
 
-.. describe:: envvar
-
-   An environment variable.  Index entries are generated.
-
 .. describe:: file
 
    The name of a file or directory.  Within the contents, you can use curly
@@ -1039,13 +1056,6 @@
    reference to a specific application or platform, the same sequence should be
    marked as ``:kbd:`Control-x Control-f```.
 
-.. describe:: keyword
-
-   The name of a Python keyword.  Using this role will generate a link to the
-   documentation of the keyword.  ``True``, ``False`` and ``None`` do not use
-   this role, but simple code markup (````True````), given that they're
-   fundamental to the language and should be known to any programmer.
-
 .. describe:: mailheader
 
    The name of an RFC 822-style mail header.  This markup does not imply that
@@ -1090,12 +1100,6 @@
 
    The name of a Usenet newsgroup.
 
-.. describe:: option
-
-   A command-line option of Python.  The leading hyphen(s) must be included.
-   If a matching ``cmdoption`` directive exists, it is linked to.  For options
-   of other programs or scripts, use simple ````code```` markup.
-
 .. describe:: program
 
    The name of an executable program.  This may differ from the file name for

-- 
Repository URL: https://hg.python.org/devguide