Doc/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 one-line 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 % These apply to all modules:
  28
  29 \moduleauthor{name}{email}              % Author of the module code;
  30                                         % omit if not known.
  31 \sectionauthor{name}{email}             % Author of the documentation.
  32
  33
  34 % Leave at least one blank line after this, to simplify ad-hoc tools
  35 % that are sometimes used to massage these files.
  36 \modulesynopsis{This is a one-line descrition, for the chapter header.}
  37
  38
  39 % ==== 2. ====
  40 % Give a short overview of what the module does.
  41 % If it is platform specific, mention this.
  42 % Mention other important restrictions or general operating principles.
  43 % For example:
  44
  45 The \module{spam} module defines operations for handling cans of Spam.
  46 It knows the four generally available Spam varieties and understands
  47 both can sizes.
  48
  49 Because spamification requires \UNIX{} process management, the module
  50 is only available on genuine \UNIX{} systems.
  51
  52
  53 % ==== 3. ====
  54 % List the public functions defined by the module.  Begin with a
  55 % standard phrase.  You may also list the exceptions and other data
  56 % items defined in the module, insofar as they are important for the
  57 % user.
  58
  59 The \module{spam} module defines the following functions:
  60
  61 % ---- 3.1. ----
  62 % For each function, use a ``funcdesc'' block.  This has exactly two
  63 % parameters (each parameters is contained in a set of curly braces):
  64 % the first parameter is the function name (this automatically
  65 % generates an index entry); the second parameter is the function's
  66 % argument list.  If there are no arguments, use an empty pair of
  67 % curly braces.  If there is more than one argument, separate the
  68 % arguments with backslash-comma.  Optional parts of the parameter
  69 % list are contained in \optional{...} (this generates a set of square
  70 % brackets around its parameter).  Arguments are automatically set in
  71 % italics in the parameter list.  Each argument should be mentioned at
  72 % least once in the description; each usage (even inside \code{...})
  73 % should be enclosed in \var{...}.
  74
  75 \begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
  76 Open the file \var{filename} as a can of Spam.  The optional
  77 \var{mode} and \var{buffersize} arguments specify the read-write mode
  78 (\code{'r'} (default) or \code{'w'}) and the buffer size (default:
  79 system dependent).
  80 \end{funcdesc}
  81
  82 % ---- 3.2. ----
  83 % Data items are described using a ``datadesc'' block.  This has only
  84 % one parameter: the item's name.
  85
  86 \begin{datadesc}{cansize}
  87 The default can size, in ounces.  Legal values are 7 and 12.  The
  88 default varies per supermarket.  This variable should not be changed
  89 once the \function{open()} function has been called.
  90 \end{datadesc}
  91
  92 % --- 3.3. ---
  93 % Exceptions are described using a ``excdesc'' block.  This has only
  94 % one parameter: the exception name.
  95
  96 \begin{excdesc}{error}
  97 Exception raised when an operation fails for a Spam specific reason.
  98 The exception argument is a string describing the reason of the
  99 failure.
 100 \end{excdesc}
 101
 102 % ---- 3.4. ----
 103 % Other standard environments:
 104 %
 105 %  classdesc    - Python classes; same arguments are funcdesc
 106 %  methoddesc   - methods, like funcdesc but has an optional parameter
 107 %                 to give the type name: \begin{methoddesc}[mytype]{name}{args}
 108 %                 By default, the type name will be the name of the
 109 %                 last class defined using classdesc.  The type name
 110 %                 is required if the type is implemented in C (because
 111 %                 there's no classdesc) or if the class isn't directly
 112 %                 documented (if it's private).
 113 %  memberdesc   - data members, like datadesc, but with an optional
 114 %                 type name like methoddesc.
 115
 116
 117 % ==== 4. ====
 118 % Now is probably a good time for a complete example.  (Alternatively,
 119 % an example giving the flavor of the module may be given before the
 120 % detailed list of functions.)
 121
 122 Example:
 123
 124 \begin{verbatim}
 125 >>> import spam
 126 >>> can = spam.open('/etc/passwd')
 127 >>> can.empty()
 128 >>> can.close()
 129 \end{verbatim}
 130 % Note that there is no trailing ">>> " prompt shown.
 131
 132 % ==== 5. ====
 133 % If your module defines new object types (for a built-in module) or
 134 % classes (for a module written in Python), you should list the
 135 % methods and instance variables (if any) of each type or class in a
 136 % separate subsection.
 137
 138 \subsection{Spam Objects}
 139 \label{spam-objects}
 140 % This label is generally useful for referencing this section, but is
 141 % also used to give a filename when generating HTML.
 142
 143 Spam objects, as returned by \function{open()} above, have the
 144 following methods:
 145
 146 \begin{methoddesc}[spam]{empty}{}
 147 Empty the can into the trash.
 148 \end{methoddesc}