A bit of domain documentation.

5 files changed, 42 insertions, 1 deletions

diff --git a/doc/contents.rst b/doc/contents.rst
index 1f3860ea8..3393f4a8f 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -10,6 +10,7 @@ Sphinx documentation contents
    concepts
    rest
    markup/index
+   domains
    builders
    config
    theming
diff --git a/doc/domains.rst b/doc/domains.rst
new file mode 100644
index 000000000..990a3ca4b
--- /dev/null
+++ b/doc/domains.rst
@@ -0,0 +1,6 @@
+.. _domains:
+
+Sphinx Domains
+==============
+
+.. todo:: Write this section.
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 13316900b..0c7725b81 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -19,6 +19,31 @@ Glossary
       the :term:`source directory`, but can be set differently with the **-c**
       command-line option.
 
+   directive
+      A reStructuredText markup element that allows marking a block of content
+      with special meaning.  Directives are supplied not only by docutils, but
+      Sphinx and custom extensions can add their own.  The basic directive
+      syntax looks like this::
+
+         .. directivename:: argument ...
+            :option: value
+
+            Content of the directive.
+
+      See :ref:`directives` for more information.
+
+   domain
+      A domain is a collection of markup (reStructuredText :term:`directive`\ s
+      and :term:`role`\ s) to describe and link to :term:`object`\ s belonging
+      together, e.g. elements of a programming language.  Directive and role
+      names in a domain have names like ``domain:name``, e.g. ``py:function``.
+
+      Having domains means that there are no naming problems when one set of
+      documentation wants to refer to e.g. C++ and Python classes.  It also
+      means that extensions that support the documentation of whole new
+      languages are much easier to write.  For more information about domains,
+      see the chapter :ref:`domains`.
+
    environment
       A structure where information about all documents under the root is saved,
       and used for cross-referencing.  The environment is pickled after the
@@ -30,6 +55,11 @@ Glossary
       directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;
       and most objects can be cross-referenced to.
 
+   role
+      A reStructuredText markup element that allows marking a piece of text.
+      Like directives, roles are extensible.  The basic syntax looks like this:
+      ``:rolename:`content```.  See :ref:`inlinemarkup` for details.
+
    source directory
       The directory which, including its subdirectories, contains all source
       files for one Sphinx project.
diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst
index c51c6211c..c8dec77c3 100644
--- a/doc/markup/desc.rst
+++ b/doc/markup/desc.rst
@@ -245,7 +245,7 @@ Info field lists
 
 .. versionadded:: 0.4
 
-.. XXX this is only for Python
+.. XXX this is only correct for Python
 
 Inside object description directives, reST field lists with these fields are
 recognized and formatted nicely:
diff --git a/doc/rest.rst b/doc/rest.rst
index e70fa105b..273bd31fd 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -23,6 +23,8 @@ is significant in reST, so all lines of the same paragraph must be left-aligned
 to the same level of indentation.
 
 
+.. _inlinemarkup:
+
 Inline markup
 -------------
 
@@ -179,6 +181,8 @@ paragraphs.  This may all sound a bit complicated, but it is intuitive enough
 when you write it.)
 
 
+.. _directives:
+
 Directives
 ----------