<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"doc.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"doc.html" title='Documenting Python'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"library-markup.html" />
<link rel=
"prev" href=
"misc-text-markup.html" />
<link rel=
"parent" href=
"special-constructs.html" />
<link rel=
"next" href=
"library-markup.html" />
<meta name='aesop' content='information'
/>
<title>6.7 Module-specific Markup
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"6.6 Miscellaneous Text Markup"
href=
"misc-text-markup.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"6 Special Markup Constructs"
href=
"special-constructs.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"6.8 Library-level Markup"
href=
"library-markup.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Documenting Python
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"misc-text-markup.html">6.6 Miscellaneous Text Markup
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"special-constructs.html">6 Special Markup Constructs
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"library-markup.html">6.8 Library-level Markup
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION000770000000000000000"></A><A NAME=
"module-markup"></A>
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
<tt class='macro'
>\section
</tt>. A typical use of this markup
appears at the top of that section and might look like this:
<div class=
"verbatim"><pre>
\section{\module{spam} ---
Access to the SPAM facility}
\declaremodule{extension}{spam}
\modulesynopsis{Access to the SPAM facility of \UNIX.}
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
Python packages
<a id='l2h-
4' xml:id='l2h-
4'
></a> -- 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
<code>\module{bar.foo}
</code>, and the beginning of the reference
<div class=
"verbatim"><pre>
\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
<tt class='macro'
>\module
</tt>.
<dt><b><tt class='macro'
>\declaremodule
</tt></b>
<tt>[
</tt><var>key
</var><tt>]
</tt><tt>{
</tt><var>type
</var><tt>}
</tt><tt>{
</tt><var>name
</var><tt>}
</tt></dt>
Requires two parameters: module type (
"<tt class="samp
">standard</tt>",
"<tt class="samp
">builtin</tt>",
"<tt class="samp
">extension</tt>", or
"<tt class="samp
"></tt>"), 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
<var>type
</var> 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
<var>name
</var> parameter. This should be the first thing after the
<tt class='macro'
>\section
</tt> used to introduce the module.
<dt><b><tt class='macro'
>\platform
</tt></b>
<tt>{
</tt><var>specifier
</var><tt>}
</tt></dt>
Specifies the portability of the module.
<var>specifier
</var> 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
"<tt class="samp
">IRIX</tt>",
"<tt class="samp
">Mac</tt>",
"<tt class="samp
">Windows</tt>", and
"<tt class="samp
">Unix</tt>". 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
<dt><b><tt class='macro'
>\modulesynopsis
</tt></b>
<tt>{
</tt><var>text
</var><tt>}
</tt></dt>
The
<var>text
</var> 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
<tt class='macro'
>\declaremodule
</tt>.
The synopsis is used in building the contents of the table
inserted as the
<tt class='macro'
>\localmoduletable
</tt>. No text is
produced at the point of the markup.
<dt><b><tt class='macro'
>\moduleauthor
</tt></b>
<tt>{
</tt><var>name
</var><tt>}
</tt><tt>{
</tt><var>email
</var><tt>}
</tt></dt>
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.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"6.6 Miscellaneous Text Markup"
href=
"misc-text-markup.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"6 Special Markup Constructs"
href=
"special-constructs.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"6.8 Library-level Markup"
href=
"library-markup.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Documenting Python
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"misc-text-markup.html">6.6 Miscellaneous Text Markup
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"special-constructs.html">6 Special Markup Constructs
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"library-markup.html">6.8 Library-level Markup
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob