Acceptable first pass at content test documentation. En passant fixes.

 * runtimes.ini: clarify that version_adjust needs to work with py2.0;
   markup fix.
 * content_tests/stddef.ini, survey-scan: remove vestigial feature
   so I don't have to document it.
 * doc/conf.py: better pygments style.

config/runtimes.ini

@@ -61,7 +61,9 @@
 ##     numbers to reflect how people actually refer to the OS, for
 ##     instance.  If omitted, no transformation is made.  Put a
 ##     vertical bar at the beginning of each line to make sure the
-##     indentation is preserved.
+##     indentation is preserved.  This code is executed by
+##     :command:`survey-scan`, so it should not use any language
+##     features or library functions added after Python 2.0.
 ##
 ## .. prop:: max_features_macros
 ##
@@ -201,7 +203,7 @@ version_adjust =
 ## appear on other systems, it would be helpful to add it.
 ##
 ## The first two lines of the regex prune all the *standard* macros
-## that <errno.h> is expected to define.  On a modern system, this
+## that :file:`errno.h` is expected to define.  On a modern system, this
 ## ought to leave only macros within the "system namespace"
 ## (i.e. beginning with either two underscores, or an underscore and
 ## then a capital letter).  The remainder of the list is grouped into

content_tests/CATEGORIES.ini

@@ -7,29 +7,38 @@
 # http://www.apache.org/licenses/LICENSE-2.0
 # There is NO WARRANTY.
 
-# This config file defines all of the categories used in decltests.
-# There are two kinds of categories: standards, and modules.  Every
-# block of tests in a decltest must be labeled with a standard, and
-# may also be labeled with a module.  This is done with structure
-# within the section header:
-#
-#     [TESTCLASS:STANDARD]
-#
-# or
-#
-#     [TESTCLASS:STANDARD:MODULE]
-#
-# Modules allow for better annotations in the generated table when an
-# entire related group of features is missing.  Modules are also how
-# we tag things as optional. By default a module is optional, but if
-# it's in the [required_modules] section instead of the [modules]
-# section, then it's required.
-#
-# Currently, the only thing this file needs to define is the tag and
-# human-readable label for each module or standard.  Tags must be
-# identifiers; labels can use arbitrary HTML.  The profusion of
-# cryptic three-letter module tags are mostly taken verbatim from the
-# Single Unix Standard.
+## File Structure
+## --------------
+##
+## Content test files are organized into sections.  The special
+## ``[preamble]`` section declares properties of the test itself.
+## All the other sections have structured names which indicate both
+## the kind of declarations being tested, and information about its
+## standard of origin.  There are two forms for section names:
+##
+##    :samp:`[{symbol-kind}:{standard}]`
+##
+## or
+##
+##    :samp:`[{symbol-kind}:{standard}:{module}]`
+##
+## The :samp:`{standard}` and :samp:`{module}`, if any, are
+## collectively referred to as the :dfn:`category` for a test.
+## Modules allow for better annotations in the generated report, when
+## an entire related group of features is missing.  Modules also allow
+## us to distinguish optional from required features.
+##
+## The configuration file :file:`content_tests/CATEGORIES.ini` defines
+## the tags that can be used for :samp:`{standard}` and
+## :samp:`{module}`.  It has three sections, ``[standards]``,
+## ``[modules]``, and ``[required_modules]``, all with the same
+## key-value format:
+##
+##     :samp:`{tag} = {human-readable label}`
+##
+## Symbols without a module, and symbols whose module is defined in
+## the ``[required_modules]`` section, are required; symbols whose
+## module is defined in the ``[modules]`` section are optional.
 
 [standards]
 c89   = ISO C1989
@@ -64,6 +73,10 @@ atomic_typedefs =
 # POSIX generally
 xsi = X/Open System Interfaces Extension
 
+# The profusion of cryptic three-letter module tags are mostly taken
+# verbatim from the indicated version of the Single Unix Standard,
+# which has many optional components.
+
 # X5
 aio   = asynchronous I/O
 fsc   = <code>fsync</code>

content_tests/stddef.ini

@@ -17,4 +17,5 @@ wchar_t   = integral
 NULL = struct x *
 
 [special:c89]
-offsetof = size_t : return offsetof(struct x, b);
+__rtype__ = size_t
+offsetof = return offsetof(struct x, b);

doc/conf.py

@@ -55,7 +55,7 @@
 #html_theme_options = {}
 #html_logo = None
 #html_favicon = None
-pygments_style = 'colorful'
+pygments_style = 'sphinx.pygments_styles.PyramidStyle'
 
 # Indexing is disabled until we figure out just what should be indexed.
 html_use_index = False