1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
\documentclass{howto}
% This is a template for short or medium-size Python-related documents,
% mostly notably the series of HOWTOs, but it can be used for any
% document you like.
% The title should be descriptive enough for people to be able to find
% the relevant document.
\title{Spammifying Sprockets in Python}
% Increment the release number whenever significant changes are made.
% The author and/or editor can define 'significant' however they like.
\release{0.00}
% At minimum, give your name and an e-mail address. You can include a
% snail-mail address if you like.
\author{Me, 'cause I wrote it}
\authoraddress{Me, 'cause I'm self-employed.}
\begin{document}
\maketitle
% This makes the Abstract go on a separate page in the HTML version;
% if a copyright notice is used, it should go immediately after this.
%
\ifhtml
\chapter*{Front Matter\label{front}}
\fi
% Copyright statement should go here, if needed.
% ...
% The abstract should be a paragraph or two long, and describe the
% scope of the document.
\begin{abstract}
\noindent
This document describes how to spammify sprockets. It is a useful
example of a Python HOWTO document. It is not dependent on any
particular sprocket implementation, and includes a Python-based
implementation in the \module{sprunkit} module.
\end{abstract}
\tableofcontents
Spammifying sprockets from Python is both fun and entertaining.
Applying the techniques described here, you can also fill your hard
disk quite effectively.
\section{What is Sprocket Spammification?}
You have to ask? It's the only thing to do to your sprockets!
\section{Why Use Python?}
Python is an excellent language from which to spammify your sprockets
since you can do it on any platform.
\section{Software Requirements}
You need to have the following software installed:
% The {itemize} environment uses a bullet for each \item. If you want the
% \item's numbered, use the {enumerate} environment instead.
\begin{itemize}
\item Python 1.9.
\item Some sprocket definition files.
\item At least one sprocket system implementation.
\end{itemize}
Note that the \module{sprunkit} is provided with this package and
implements ActiveSprockets in Python.
% The preceding sections will have been written in a gentler,
% introductory style. You may also wish to include a reference
% section, documenting all the functions/exceptions/constants.
% The following is a model for such a reference section, for
% an extension module written in C.
\section{Extension Module \module{spamsprock}}
\exmodindex{spamsprock} % Set the module name for the index
\label{module-spamsprock} % Create a label for cross-references
A \C{} module is provided to perform spammification operations very
quickly. It exports a function, an exception, and some constants.
% A function definition
\begin{funcdesc}{spammify}{sprocket\optional{, options}}
Spammify the sprocket given as \var{sprocket}. Flags my be
bitwise-ORed together and passed as \var{options}.
\end{funcdesc}
% An exception definition
\begin{excdesc}{SpamError}
The exception that is raised when spammification fails, or just takes
too long.
\end{excdesc}
% A definition of two constants
\begin{datadesc}{FROBNICATE}
Value to be used for the \var{options} parameter to
\function{spammify()} to indicate that the \var{sprocket} parameter to
that function should be frobnicated as well as spammified.
\end{datadesc}
\begin{datadesc}{NO_FROBNICATE}
As with \constant{FROBNICATE}, but indicates that frobnication should
not be performed. The default is to frobnicate randomly.
\end{datadesc}
% The following section is a model for documenting modules written in
% Python.
\section{Module \module{sprunkit}}
\modindex{ezspam}
\label{module-sprunkit}
This module provides a high level interface to spammification
operations. It provides an interesting base class and an exception.
% A class definition
\begin{classdesc}{SprunkSprocket}{\optional{path}}
A Python-only implementation of a persistent sprocket. The \var{path}
parameter should refer to a spocket definition file. If omitted, a
new sprocket is created.
\end{classdesc}
% An exception definition
\begin{excdesc}{PersistenceError}
Exception raised when the \method{save()} method of a
\class{SprunkSprockit} instance fails.
\end{excdesc}
\subsection{\class{SprunkSprocket} Objects}
\class{SprunkSprocket} objects have the following methods:
\begin{funcdesc}{save}{\optional{path}}
Save the sprocket in the file specified by \var{path}. If \var{path}
is omitted, the \var{path} specified to the constructor is used. If
neither was specified, raises the \exception{PersistenceError}
exception.
\end{funcdesc}
\begin{funcdesc}{persist}{path}
Set the default file name that the \method{save()} method will use.
\end{funcdesc}
\begin{funcdesc}{insist}{}
Make the sprocket assert itself. This method cannot fail.
\end{funcdesc}
\appendix
\section{This is an Appendix}
To create an appendix in a Python HOWTO document, use markup like
this:
\begin{verbatim}
\appendix
\section{This is an Appendix}
To create an appendix in a Python HOWTO document, ....
\section{This is another}
Just add another \section{}, but don't say \appendix again.
\end{verbatim}
\end{document}
|
