6.7 Module-specific Markup

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.

See About this document... for information on suggesting changes.