Doc/libtemplate.tex

   1 % Template for a library manual section.
   2 % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
   3
   4
   5 % ==== 1. ====
   6 % Choose one of the following section headers and index entries;
   7 % \section{} generates the section header,
   8 % \bimodindex{} or \stmodundex{} generates an index entry for this module
   9
  10 \section{Built-in module \sectcode{spam}}       % If implemented in C
  11 \bimodindex[spam}
  12
  13 \section{Standard module \sectcode{spam}}       % If implemented in Python
  14 \stmodindex{spam}
  15
  16
  17 % ==== 2. ====
  18 % Give a short overview of what the module does.
  19 % If it is platform specific, mention this.
  20 % Mention other important restrictions or general operating principles.
  21 % For example:
  22
  23 The \code{spam} module defines operations for handling cans of Spam.
  24 It knows the four generally available Spam varieties and understands
  25 both can sizes.
  26
  27 Because spamification requires UNIX process management, the module is
  28 only available on genuine UNIX systems.
  29
  30
  31 % ==== 3. ====
  32 % List the public functions defined by the module.  Begin with a
  33 % standard phrase.  You may also list the exceptions and other data
  34 % items defined in the module, insofar as they are important for the
  35 % user.
  36
  37 The \code{spam} module defines the following functions:
  38
  39 % ---- 3.1. ----
  40 % Redefine the ``indexsubitem'' macro to point to this module
  41 % (alternatively, you can put this at the top of the file):
  42
  43 \renewcommand{\indexsubitem}{(in module spam)}
  44
  45 % ---- 3.2. ----
  46 % For each function, use a ``funcdesc'' block.  This has exactly two
  47 % parameters (each parameters is contained in a set of curly braces):
  48 % the first parameter is the function name (this automatically
  49 % generates an index entry); the second parameter is the function's
  50 % argument list.  If there are no arguments, use an empty pair of
  51 % curly braces.  If there is more than one argument, separate the
  52 % arguments with backslash-comma.  Optional parts of the parameter
  53 % list are contained in \optional{...} (this generates a set of square
  54 % brackets around its parameter).  Arguments are automatically set in
  55 % italics in the parameter list.  Each argument should be mentioned at
  56 % least once in the description; each usage (even inside \code{...})
  57 % should be enclosed in \var{...}.
  58
  59 \begin{funcdesc}{open}{filename\optional{\, mode\, buffersize}}
  60 Open the file \var{filename} as a can of Spam.  The optional
  61 \var{mode} and \var{buffersize} arguments specify the read-write mode
  62 (\code{'r'} (default) or \code{'w'}) and the buffer size (default:
  63 system dependent).
  64 \end{funcdesc}
  65
  66 % ---- 3.3. ----
  67 % Data items are described using a ``datadesc'' block.  This has only
  68 % one parameter: the item's name.
  69
  70 \begin{datadesc}{cansize}
  71 The default can size, in ounces.  Legal values are 7 and 12.  The
  72 default varies per supermarket.  This variable should not be changed
  73 once the \code{open()} function has been called.
  74 \end{datadesc}
  75
  76 % --- 3.4. ---
  77 % Exceptions are described using a ``excdesc'' block.  This has only
  78 % one parameter: the exception name.
  79
  80 \begin{excdesc}{error}
  81 Exception raised when an operation fails for a Spam specific reason.
  82 The exception argument is a string describing the reason of the
  83 failure.
  84 \end{excdesc}
  85
  86 % ---- 3.5. ----
  87 % There is no standard block type for classes.  I generally use
  88 % ``funcdesc'' blocks, since class instantiation looks very much like
  89 % a function call.
  90
  91
  92 % ==== 4. ====
  93 % Now is probably a good time for a complete example.  (Alternatively,
  94 % an example giving the flavor of the module may be given before the
  95 % detailed list of functions.)
  96
  97 Example:
  98
  99 \begin{verbatim}
 100 >>> import spam
 101 >>> can = spam.open('/etc/passwd')
 102 >>> can.empty()
 103 >>> can.close()
 104 \end{verbatim}
 105
 106 % ==== 5. ====
 107 % If your module defines new object types (for a built-in module) or
 108 % classes (for a module written in Python), you should list the
 109 % methods and instance variables (if any) of each type or class in a
 110 % separate subsection.  It is important to redefine ``indexsubitem''
 111 % for each subsection.
 112
 113 \subsection{Spam methods}
 114
 115 Spam objects (returned by \code{open()} above) have the following
 116 methods.
 117
 118 \renewcommand{\indexsubitem}{(spam method)}
 119
 120 \begin{funcdesc}{empty}{}
 121 Empty the can into the trash.
 122 \end{funcdesc}