The markup described in this section is used to provide information
about a module being documented. Each module should be documented
in its own \section. A typical use of this markup
appears at the top of that section and might look like this:
\section{\module{spam} ---
Access to the SPAM facility}
\declaremodule{extension}{spam}
\platform{Unix}
\modulesynopsis{Access to the SPAM facility of \UNIX.}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
Python packages -- collections of modules that can
be described as a unit -- are documented using the same markup as
modules. The name for a module in a package should be typed in
``fully qualified'' form (it should include the package name).
For example, a module ``foo'' in package ``bar'' should be marked as
\module{bar.foo}, and the beginning of the reference
section would appear as:
\section{\module{bar.foo} ---
Module from the \module{bar} package}
\declaremodule{extension}{bar.foo}
\modulesynopsis{Nifty module from the \module{bar} package.}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
Note that the name of a package is also marked using
\module.
\declaremodule[key]{type}{name}
Requires two parameters: module type ("standard",
"builtin", "extension", or ""), and the module
name. An optional parameter should be given as the basis for the
module's ``key'' used for linking to or referencing the section.
The ``key'' should only be given if the module's name contains any
underscores, and should be the name with the underscores stripped.
Note that the type parameter must be one of the values
listed above or an error will be printed. For modules which are
contained in packages, the fully-qualified name should be given as
name parameter. This should be the first thing after the
\section used to introduce the module.
\platform{specifier}
Specifies the portability of the module. specifier is a
comma-separated list of keys that specify what platforms the
module is available on. The keys are short identifiers;
examples that are in use include "IRIX", "Mac",
"Windows", and "Unix". It is important to use a key
which has already been used when applicable. This is used to
provide annotations in the Module Index and the HTML and GNU info
output.
\modulesynopsis{text}
The text is a short, ``one line'' description of the
module that can be used as part of the chapter introduction.
This is must be placed after \declaremodule.
The synopsis is used in building the contents of the table
inserted as the \localmoduletable. No text is
produced at the point of the markup.
\moduleauthor{name}{email}
This macro is used to encode information about who authored a
module. This is currently not used to generate output, but can be
used to help determine the origin of the module.
