doc/tools/templates/module.tex

   1 % Template for a library manual section.
   2 % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
   3
   4 % ==== 0. ====
   5 % Copy this file to <mydir>/lib<mymodule>.tex, and edit that file
   6 % according to the instructions below.
   7
   8
   9 % ==== 1. ====
  10 % The section prologue.  Give the section a title and provide some
  11 % meta-information.  References to the module should use
  12 % \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
  13 % appropriate.
  14
  15 \section{\module{spam} ---
  16          Short descrition, for section title}
  17
  18 % Choose one of these to specify the module module name.  If there's
  19 % an underscore in the name, use
  20 % \declaremodule[modname]{...}{mod_name} instead.
  21 %
  22 \declaremodule{builtin}{spam}           % standard library, in C
  23 \declaremodule{standard}{spam}          % standard library, in Python
  24 \declaremodule{extension}{spam}         % not standard, in C
  25 \declaremodule{}{spam}                  % not standard, in Python
  26
  27 % Portability statement:  Uncomment and fill in the parameter to specify the
  28 % availability of the module.  The parameter can be Unix, IRIX, SunOS, Mac,
  29 % Windows, or lots of other stuff.  When ``Mac'' is specified, the availability
  30 % statement will say ``Macintosh'' and the Module Index may say ``Mac''.
  31 % Please use a name that has already been used whenever applicable.  If this
  32 % is omitted, no availability statement is produced or implied.
  33 %
  34 %   \platform{UNIX}
  35
  36 % These apply to all modules:
  37
  38 \moduleauthor{name}{email}              % Author of the module code;
  39                                         % omit if not known.
  40 \sectionauthor{name}{email}             % Author of the documentation,
  41                                         % even if not a module section.
  42
  43
  44 % Leave at least one blank line after this, to simplify ad-hoc tools
  45 % that are sometimes used to massage these files.
  46 \modulesynopsis{This is a one-line descrition, for the chapter header.}
  47
  48
  49 % ==== 2. ====
  50 % Give a short overview of what the module does.
  51 % If it is platform specific, mention this.
  52 % Mention other important restrictions or general operating principles.
  53 % For example:
  54
  55 The \module{spam} module defines operations for handling cans of Spam.
  56 It knows the four generally available Spam varieties and understands
  57 both can sizes.
  58
  59 Because spamification requires \UNIX{} process management, the module
  60 is only available on genuine \UNIX{} systems.
  61
  62
  63 % ==== 3. ====
  64 % List the public functions defined by the module.  Begin with a
  65 % standard phrase.  You may also list the exceptions and other data
  66 % items defined in the module, insofar as they are important for the
  67 % user.
  68
  69 The \module{spam} module defines the following functions:
  70
  71 % ---- 3.1. ----
  72 % For each function, use a ``funcdesc'' block.  This has exactly two
  73 % parameters (each parameters is contained in a set of curly braces):
  74 % the first parameter is the function name (this automatically
  75 % generates an index entry); the second parameter is the function's
  76 % argument list.  If there are no arguments, use an empty pair of
  77 % curly braces.  If there is more than one argument, separate the
  78 % arguments with backslash-comma.  Optional parts of the parameter
  79 % list are contained in \optional{...} (this generates a set of square
  80 % brackets around its parameter).  Arguments are automatically set in
  81 % italics in the parameter list.  Each argument should be mentioned at
  82 % least once in the description; each usage (even inside \code{...})
  83 % should be enclosed in \var{...}.
  84
  85 \begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
  86 Open the file \var{filename} as a can of Spam.  The optional
  87 \var{mode} and \var{buffersize} arguments specify the read/write mode
  88 (\code{'r'} (default) or \code{'w'}) and the buffer size (default:
  89 system dependent).
  90 \end{funcdesc}
  91
  92 % ---- 3.2. ----
  93 % Data items are described using a ``datadesc'' block.  This has only
  94 % one parameter: the item's name.
  95
  96 \begin{datadesc}{cansize}
  97 The default can size, in ounces.  Legal values are 7 and 12.  The
  98 default varies per supermarket.  This variable should not be changed
  99 once the \function{open()} function has been called.
 100 \end{datadesc}
 101
 102 % --- 3.3. ---
 103 % Exceptions are described using a ``excdesc'' block.  This has only
 104 % one parameter: the exception name.  Exceptions defined as classes in
 105 % the source code should be documented using this environment, but
 106 % constructor parameters must be ommitted.
 107
 108 \begin{excdesc}{error}
 109 Exception raised when an operation fails for a Spam specific reason.
 110 The exception argument is a string describing the reason of the
 111 failure.
 112 \end{excdesc}
 113
 114 % ---- 3.4. ----
 115 % Other standard environments:
 116 %
 117 %  classdesc    - Python classes; same arguments are funcdesc
 118 %  methoddesc   - methods, like funcdesc but has an optional parameter
 119 %                 to give the type name: \begin{methoddesc}[mytype]{name}{args}
 120 %                 By default, the type name will be the name of the
 121 %                 last class defined using classdesc.  The type name
 122 %                 is required if the type is implemented in C (because
 123 %                 there's no classdesc) or if the class isn't directly
 124 %                 documented (if it's private).
 125 %  memberdesc   - data members, like datadesc, but with an optional
 126 %                 type name like methoddesc.
 127
 128
 129 % ==== 4. ====
 130 % Now is probably a good time for a complete example.  (Alternatively,
 131 % an example giving the flavor of the module may be given before the
 132 % detailed list of functions.)
 133
 134 \subsection{Example \label{spam-example}}
 135
 136 The following example demonstrates how to open a can of spam using the
 137 \module{spam} module.
 138
 139 \begin{verbatim}
 140 >>> import spam
 141 >>> can = spam.open('/etc/passwd')
 142 >>> can.empty()
 143 >>> can.close()
 144 \end{verbatim}
 145 % Note that there is no trailing ">>> " prompt shown.
 146
 147 % ==== 5. ====
 148 % If your module defines new object types (for a built-in module) or
 149 % classes (for a module written in Python), you should list the
 150 % methods and instance variables (if any) of each type or class in a
 151 % separate subsection.
 152
 153 \subsection{Spam Objects}
 154 \label{spam-objects}
 155 % This label is generally useful for referencing this section, but is
 156 % also used to give a filename when generating HTML.
 157
 158 Spam objects, as returned by \function{open()} above, have the
 159 following methods:
 160
 161 \begin{methoddesc}[spam]{empty}{}
 162 Empty the can into the trash.
 163 \end{methoddesc}