diff -r 8d5d1f2c7378 documenting.rst
--- a/documenting.rst	Sat May 10 21:01:39 2014 -0700
+++ b/documenting.rst	Sat Jun 07 11:51:37 2014 -0700
@@ -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:
 
@@ -970,8 +972,27 @@
    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 module objects, but may possibly 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
 
@@ -979,6 +1000,8 @@
    between production displays).
 
 
+---------
+
 The following role creates a cross-reference to the term in the glossary:
 
 .. describe:: term
@@ -1006,10 +1029,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 +1058,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 +1102,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