diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 4b704228f..35981edc2 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -141,8 +141,50 @@ Referencing downloadable files
    suitable link generated to it.
 
 
+Cross-referencing other items of interest
+-----------------------------------------
+
+The following roles do possibly create a cross-reference, but do not refer to
+objects:
+
+.. rst:role:: envvar
+
+   An environment variable.  Index entries are generated.  Also generates a link
+   to the matching :rst:dir:`envvar` directive, if it exists.
+
+.. rst:role:: token
+
+   The name of a grammar token (used to create links between
+   :rst:dir:`productionlist` directives).
+
+.. rst:role:: keyword
+
+   The name of a keyword in Python.  This creates a link to a reference label
+   with that name, if it exists.
+
+.. rst:role:: option
+
+   A command-line option to an executable program.  The leading hyphen(s) must
+   be included.  This generates a link to a :rst:dir:`option` directive, if it
+   exists.
+
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. rst: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.
+
+
 Other semantic markup
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 The following roles don't do anything special except formatting the text
 in a different style:
@@ -289,52 +331,10 @@ 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:
-
-.. rst:role:: envvar
-
-   An environment variable.  Index entries are generated.  Also generates a link
-   to the matching :rst:dir:`envvar` directive, if it exists.
-
-.. rst:role:: token
-
-   The name of a grammar token (used to create links between
-   :rst:dir:`productionlist` directives).
-
-.. rst:role:: keyword
-
-   The name of a keyword in Python.  This creates a link to a reference label
-   with that name, if it exists.
-
-.. rst:role:: option
-
-   A command-line option to an executable program.  The leading hyphen(s) must
-   be included.  This generates a link to a :rst:dir:`option` directive, if it
-   exists.
-
-
-The following role creates a cross-reference to the term in the glossary:
-
-.. rst: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
--------------
+~~~~~~~~~~~~~
 
 The documentation system provides three substitutions that are defined by default.
 They are set in the build configuration file.