Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtemplate.tex @ 5817:48b94de85bf3 legacy-trunk

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