source: trunk/essentials/dev-lang/python/Doc/templates/module.tex@ 3315

% Template for a library manual section.
% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
%
% Complete documentation on the extended LaTeX markup used for Python
% documentation is available in ``Documenting Python'', which is part
% of the standard documentation for Python.  It may be found online
% at:
%
%     http://www.python.org/doc/current/doc/doc.html

% ==== 0. ====
% Copy this file to <mydir>/lib<mymodule>.tex, and edit that file
% according to the instructions below.


% ==== 1. ====
% The section prologue.  Give the section a title and provide some
% meta-information.  References to the module should use
% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
% appropriate.

\section{\module{spam} ---
         Short description, for section title and table of contents}

% Choose one of these to specify the module module name.  If there's
% an underscore in the name, use
% \declaremodule[modname]{...}{mod_name} instead.
%
\declaremodule{builtin}{spam}           % standard library, in C
\declaremodule{standard}{spam}          % standard library, in Python
\declaremodule{extension}{spam}         % not standard, in C
\declaremodule{}{spam}                  % not standard, in Python

% Portability statement:  Uncomment and fill in the parameter to specify the
% availability of the module.  The parameter can be Unix, IRIX, SunOS, Mac,
% Windows, or lots of other stuff.  When ``Mac'' is specified, the availability
% statement will say ``Macintosh'' and the Module Index may say ``Mac''.
% Please use a name that has already been used whenever applicable.  If this
% is omitted, no availability statement is produced or implied.
%
%   \platform{Unix}

% These apply to all modules, and may be given more than once:

\moduleauthor{name}{email}              % Author of the module code;
                                        % omit if not known.
\sectionauthor{name}{email}             % Author of the documentation,
                                        % even if not a module section.


% Leave at least one blank line after this, to simplify ad-hoc tools
% that are sometimes used to massage these files.
\modulesynopsis{This is a one-line description, for the chapter header.}


% ==== 2. ====
% Give a short overview of what the module does.
% If it is platform specific, mention this.
% Mention other important restrictions or general operating principles.
% For example:

The \module{spam} module defines operations for handling cans of Spam.
It knows the four generally available Spam varieties and understands
both can sizes.

Because spamification requires \UNIX{} process management, the module
is only available on genuine \UNIX{} systems.


% ==== 3. ====
% List the public functions defined by the module.  Begin with a
% standard phrase.  You may also list the exceptions and other data
% items defined in the module, insofar as they are important for the
% user.

The \module{spam} module defines the following functions:

% ---- 3.1. ----
% For each function, use a ``funcdesc'' block.  This has exactly two
% parameters (each parameters is contained in a set of curly braces):
% the first parameter is the function name (this automatically
% generates an index entry); the second parameter is the function's
% argument list.  If there are no arguments, use an empty pair of
% curly braces.  If there is more than one argument, separate the
% arguments with backslash-comma.  Optional parts of the parameter
% list are contained in \optional{...} (this generates a set of square
% brackets around its parameter).  Arguments are automatically set in
% italics in the parameter list.  Each argument should be mentioned at
% least once in the description; each usage (even inside \code{...})
% should be enclosed in \var{...}.

\begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
Open the file \var{filename} as a can of Spam.  The optional
\var{mode} and \var{buffersize} arguments specify the read/write mode
(\code{'r'} (default) or \code{'w'}) and the buffer size (default:
system dependent).
\end{funcdesc}

% ---- 3.2. ----
% Data items are described using a ``datadesc'' block.  This has only
% one parameter: the item's name.

\begin{datadesc}{cansize}
The default can size, in ounces.  Legal values are 7 and 12.  The
default varies per supermarket.  This variable should not be changed
once the \function{open()} function has been called.
\end{datadesc}

% --- 3.3. ---
% Exceptions are described using a ``excdesc'' block.  This has only
% one parameter: the exception name.  Exceptions defined as classes in
% the source code should be documented using this environment, but
% constructor parameters must be omitted.

\begin{excdesc}{error}
Exception raised when an operation fails for a Spam specific reason.
The exception argument is a string describing the reason of the
failure.
\end{excdesc}

% ---- 3.4. ----
% Other standard environments:
%
%  classdesc    - Python classes; same arguments are funcdesc
%  methoddesc   - methods, like funcdesc but has an optional parameter 
%                 to give the type name: \begin{methoddesc}[mytype]{name}{args}
%                 By default, the type name will be the name of the
%                 last class defined using classdesc.  The type name
%                 is required if the type is implemented in C (because 
%                 there's no classdesc) or if the class isn't directly 
%                 documented (if it's private).
%  memberdesc   - data members, like datadesc, but with an optional
%                 type name like methoddesc.


% ==== 4. ====
% Now is probably a good time for a complete example.  (Alternatively,
% an example giving the flavor of the module may be given before the
% detailed list of functions.)

\subsection{Example \label{spam-example}}

The following example demonstrates how to open a can of spam using the
\module{spam} module.

\begin{verbatim}
>>> import spam
>>> can = spam.open('/etc/passwd')
>>> can.empty()
>>> can.close()
\end{verbatim}
% Note that there is no trailing ">>> " prompt shown.

% ==== 5. ====
% If your module defines new object types (for a built-in module) or
% classes (for a module written in Python), you should list the
% methods and instance variables (if any) of each type or class in a
% separate subsection.

\subsection{Spam Objects}
\label{spam-objects}
% This label is generally useful for referencing this section, but is
% also used to give a filename when generating HTML.

Spam objects, as returned by \function{open()} above, have the
following methods:

\begin{methoddesc}[spam]{empty}{}
Empty the can into the trash.
\end{methoddesc}