1 % Template for a library manual section.
2 % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
5 % Copy this file to <mydir>/lib<mymodule>.tex, and edit that file
6 % according to the instructions below.
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
15 \section{\module{spam} ---
16 Short descrition, for section title}
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.
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
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.
36 % These apply to all modules:
38 \moduleauthor{name}{email} % Author of the module code;
40 \sectionauthor{name}{email} % Author of the documentation,
41 % even if not a module section.
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.}
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.
55 The \module{spam} module defines operations for handling cans of Spam.
56 It knows the four generally available Spam varieties and understands
59 Because spamification requires \UNIX{} process management, the module
60 is only available on genuine \UNIX{} systems.
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
69 The \module{spam} module defines the following functions:
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{...}.
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:
93 % Data items are described using a ``datadesc'' block. This has only
94 % one parameter: the item's name.
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.
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.
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
115 % Other standard environments:
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.
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.)
134 \subsection{Example \label{spam-example}}
136 The following example demonstrates how to open a can of spam using the
137 \module{spam} module.
141 >>> can = spam.open('/etc/passwd')
145 % Note that there is no trailing ">>> " prompt shown.
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.
153 \subsection{Spam Objects}
155 % This label is generally useful for referencing this section, but is
156 % also used to give a filename when generating HTML.
158 Spam objects, as returned by \function{open()} above, have the
161 \begin{methoddesc}[spam]{empty}{}
162 Empty the can into the trash.