Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 1 | % Template for a library manual section. |
| 2 | % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 3 | |
Fred Drake | 0618f5e | 1998-08-11 17:43:45 +0000 | [diff] [blame] | 4 | % ==== 0. ==== |
| 5 | % Copy this file to <mydir>/lib<mymodule>.tex, and edit that file |
| 6 | % according to the instructions below. |
| 7 | |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 8 | |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 9 | % ==== 1. ==== |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 14 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 15 | \section{\module{spam} --- |
Fred Drake | 46a9438 | 1999-03-02 16:24:22 +0000 | [diff] [blame] | 16 | Short descrition, for section title} |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 17 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 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 |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 26 | |
Fred Drake | 46a9438 | 1999-03-02 16:24:22 +0000 | [diff] [blame] | 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 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 36 | % These apply to all modules: |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 37 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 38 | \moduleauthor{name}{email} % Author of the module code; |
| 39 | % omit if not known. |
Fred Drake | 5eecd7b | 1998-12-22 18:15:04 +0000 | [diff] [blame] | 40 | \sectionauthor{name}{email} % Author of the documentation, |
| 41 | % even if not a module section. |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 42 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 43 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 44 | % Leave at least one blank line after this, to simplify ad-hoc tools |
| 45 | % that are sometimes used to massage these files. |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 46 | \modulesynopsis{This is a one-line descrition, for the chapter header.} |
| 47 | |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 48 | |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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 | |
Fred Drake | d10d0fa | 1998-02-24 21:43:05 +0000 | [diff] [blame] | 55 | The \module{spam} module defines operations for handling cans of Spam. |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 56 | It knows the four generally available Spam varieties and understands |
| 57 | both can sizes. |
| 58 | |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 59 | Because spamification requires \UNIX{} process management, the module |
| 60 | is only available on genuine \UNIX{} systems. |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 61 | |
| 62 | |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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 | |
Fred Drake | d10d0fa | 1998-02-24 21:43:05 +0000 | [diff] [blame] | 69 | The \module{spam} module defines the following functions: |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 70 | |
| 71 | % ---- 3.1. ---- |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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 | |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 85 | \begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}} |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 86 | Open the file \var{filename} as a can of Spam. The optional |
Fred Drake | e1a85f5 | 2000-07-06 16:12:47 +0000 | [diff] [blame] | 87 | \var{mode} and \var{buffersize} arguments specify the read/write mode |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 88 | (\code{'r'} (default) or \code{'w'}) and the buffer size (default: |
| 89 | system dependent). |
| 90 | \end{funcdesc} |
| 91 | |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 92 | % ---- 3.2. ---- |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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 |
Fred Drake | d10d0fa | 1998-02-24 21:43:05 +0000 | [diff] [blame] | 99 | once the \function{open()} function has been called. |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 100 | \end{datadesc} |
| 101 | |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 102 | % --- 3.3. --- |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 103 | % Exceptions are described using a ``excdesc'' block. This has only |
Fred Drake | e1a85f5 | 2000-07-06 16:12:47 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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 | |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 127 | |
| 128 | |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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.) |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 133 | |
Fred Drake | e1a85f5 | 2000-07-06 16:12:47 +0000 | [diff] [blame] | 134 | \subsection{Example \label{spam-example}} |
Skip Montanaro | 8968a82 | 2000-07-06 13:43:37 +0000 | [diff] [blame] | 135 | |
| 136 | The following example demonstrates how to open a can of spam using the |
| 137 | \module{spam} module. |
Guido van Rossum | 6a11eb4 | 1992-06-03 17:59:07 +0000 | [diff] [blame] | 138 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 139 | \begin{verbatim} |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 140 | >>> import spam |
| 141 | >>> can = spam.open('/etc/passwd') |
| 142 | >>> can.empty() |
| 143 | >>> can.close() |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 144 | \end{verbatim} |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 145 | % Note that there is no trailing ">>> " prompt shown. |
| 146 | |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 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 |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 151 | % separate subsection. |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 152 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 153 | \subsection{Spam Objects} |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 157 | |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 158 | Spam objects, as returned by \function{open()} above, have the |
| 159 | following methods: |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 160 | |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 161 | \begin{methoddesc}[spam]{empty}{} |
Guido van Rossum | 51bbdfb | 1995-03-01 14:07:08 +0000 | [diff] [blame] | 162 | Empty the can into the trash. |
Fred Drake | 07bcd99 | 1998-04-03 21:25:16 +0000 | [diff] [blame] | 163 | \end{methoddesc} |