1 | % |
---|
2 | % python.sty for the Python docummentation [works only with Latex2e] |
---|
3 | % |
---|
4 | |
---|
5 | \NeedsTeXFormat{LaTeX2e}[1995/12/01] |
---|
6 | \ProvidesPackage{python} |
---|
7 | [1998/01/11 LaTeX package (Python markup)] |
---|
8 | |
---|
9 | \RequirePackage{longtable} |
---|
10 | \RequirePackage{underscore} |
---|
11 | |
---|
12 | % Uncomment these two lines to ignore the paper size and make the page |
---|
13 | % size more like a typical published manual. |
---|
14 | %\renewcommand{\paperheight}{9in} |
---|
15 | %\renewcommand{\paperwidth}{8.5in} % typical squarish manual |
---|
16 | %\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' |
---|
17 | |
---|
18 | % These packages can be used to add marginal annotations which indicate |
---|
19 | % index entries and labels; useful for reviewing this messy documentation! |
---|
20 | % |
---|
21 | %\RequirePackage{showkeys} |
---|
22 | %\RequirePackage{showidx} |
---|
23 | |
---|
24 | % If we ever want to indent paragraphs, this needs to be changed. |
---|
25 | % This is used inside the macros defined here instead of coding |
---|
26 | % \noindent directly. |
---|
27 | \let\py@parindent=\noindent |
---|
28 | |
---|
29 | % for PDF output, use maximal compression & a lot of other stuff |
---|
30 | % (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>) |
---|
31 | % |
---|
32 | \newif\ifpy@doing@page@targets |
---|
33 | \py@doing@page@targetsfalse |
---|
34 | |
---|
35 | \newif\ifpdf\pdffalse |
---|
36 | \ifx\pdfoutput\undefined\else\ifcase\pdfoutput |
---|
37 | \else |
---|
38 | \pdftrue |
---|
39 | \input{pdfcolor} |
---|
40 | \let\py@LinkColor=\NavyBlue |
---|
41 | \let\py@NormalColor=\Black |
---|
42 | \pdfcompresslevel=9 |
---|
43 | \pdfpagewidth=\paperwidth % page width of PDF output |
---|
44 | \pdfpageheight=\paperheight % page height of PDF output |
---|
45 | % |
---|
46 | % Pad the number with '0' to 3 digits wide so no page name is a prefix |
---|
47 | % of any other. |
---|
48 | % |
---|
49 | \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1} |
---|
50 | \newcommand{\py@pageno}{\py@targetno\thepage} |
---|
51 | % |
---|
52 | % This definition allows the entries in the page-view of the ToC to be |
---|
53 | % active links. Some work, some don't. |
---|
54 | % |
---|
55 | \let\py@OldContentsline=\contentsline |
---|
56 | % |
---|
57 | % Backward compatibility hack: pdfTeX 0.13 defined \pdfannotlink, |
---|
58 | % but it changed to \pdfstartlink in 0.14. This let's us use either |
---|
59 | % version and still get useful behavior. |
---|
60 | % |
---|
61 | \@ifundefined{pdfstartlink}{ |
---|
62 | \let\pdfstartlink=\pdfannotlink |
---|
63 | }{} |
---|
64 | % |
---|
65 | % The \py@parindent here is a hack -- we're forcing pdfTeX into |
---|
66 | % horizontal mode since \pdfstartlink requires that. |
---|
67 | \def\py@pdfstartlink{% |
---|
68 | \ifvmode\py@parindent\fi% |
---|
69 | \pdfstartlink% |
---|
70 | } |
---|
71 | % |
---|
72 | % Macro that takes two args: the name to link to and the content of |
---|
73 | % the link. This takes care of the PDF magic, getting the colors |
---|
74 | % the same for each link, and avoids having lots of garbage all over |
---|
75 | % this style file. |
---|
76 | \newcommand{\py@linkToName}[2]{% |
---|
77 | \py@pdfstartlink attr{/Border [0 0 0]} goto name{#1}% |
---|
78 | \py@LinkColor#2\py@NormalColor% |
---|
79 | \pdfendlink% |
---|
80 | } |
---|
81 | % Compute the padded page number separately since we end up with a pair of |
---|
82 | % \relax tokens; this gets the right string computed and works. |
---|
83 | \renewcommand{\contentsline}[3]{% |
---|
84 | \def\my@pageno{\py@targetno{#3}}% |
---|
85 | \py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}% |
---|
86 | } |
---|
87 | \AtEndDocument{ |
---|
88 | \def\_{\string_} |
---|
89 | \InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{} |
---|
90 | } |
---|
91 | \newcommand{\py@target}[1]{% |
---|
92 | \ifpy@doing@page@targets% |
---|
93 | {\pdfdest name{#1} xyz}% |
---|
94 | \fi% |
---|
95 | } |
---|
96 | \let\py@OldLabel=\label |
---|
97 | \renewcommand{\label}[1]{% |
---|
98 | \py@OldLabel{#1}% |
---|
99 | \py@target{label-#1}% |
---|
100 | } |
---|
101 | % This stuff adds a page# destination to every PDF page, where # is three |
---|
102 | % digits wide, padded with leading zeros. This doesn't really help with |
---|
103 | % the frontmatter, but does fine with the body. |
---|
104 | % |
---|
105 | % This is *heavily* based on the hyperref package. |
---|
106 | % |
---|
107 | \def\@begindvi{% |
---|
108 | \unvbox \@begindvibox |
---|
109 | \@hyperfixhead |
---|
110 | } |
---|
111 | \def\@hyperfixhead{% |
---|
112 | \let\H@old@thehead\@thehead |
---|
113 | \global\def\@foo{\py@target{page\py@pageno}}% |
---|
114 | \expandafter\ifx\expandafter\@empty\H@old@thehead |
---|
115 | \def\H@old@thehead{\hfil}\fi |
---|
116 | \def\@thehead{\@foo\relax\H@old@thehead}% |
---|
117 | } |
---|
118 | \fi\fi |
---|
119 | |
---|
120 | % Increase printable page size (copied from fullpage.sty) |
---|
121 | \topmargin 0pt |
---|
122 | \advance \topmargin by -\headheight |
---|
123 | \advance \topmargin by -\headsep |
---|
124 | |
---|
125 | % attempt to work a little better for A4 users |
---|
126 | \textheight \paperheight |
---|
127 | \advance\textheight by -2in |
---|
128 | |
---|
129 | \oddsidemargin 0pt |
---|
130 | \evensidemargin 0pt |
---|
131 | %\evensidemargin -.25in % for ``manual size'' documents |
---|
132 | \marginparwidth 0.5in |
---|
133 | |
---|
134 | \textwidth \paperwidth |
---|
135 | \advance\textwidth by -2in |
---|
136 | |
---|
137 | |
---|
138 | % Style parameters and macros used by most documents here |
---|
139 | \raggedbottom |
---|
140 | \sloppy |
---|
141 | \parindent = 0mm |
---|
142 | \parskip = 2mm |
---|
143 | \hbadness = 5000 % don't print trivial gripes |
---|
144 | |
---|
145 | \pagestyle{empty} % start this way; change for |
---|
146 | \pagenumbering{roman} % ToC & chapters |
---|
147 | |
---|
148 | % Use this to set the font family for headers and other decor: |
---|
149 | \newcommand{\py@HeaderFamily}{\sffamily} |
---|
150 | |
---|
151 | % Set up abstract ways to get the normal and smaller font sizes that |
---|
152 | % work even in footnote context. |
---|
153 | \newif\ifpy@infootnote \py@infootnotefalse |
---|
154 | \let\py@oldmakefntext\@makefntext |
---|
155 | \def\@makefntext#1{% |
---|
156 | \bgroup% |
---|
157 | \py@infootnotetrue |
---|
158 | \py@oldmakefntext{#1}% |
---|
159 | \egroup% |
---|
160 | } |
---|
161 | \def\py@defaultsize{% |
---|
162 | \ifpy@infootnote\footnotesize\else\normalsize\fi% |
---|
163 | } |
---|
164 | \def\py@smallsize{% |
---|
165 | \ifpy@infootnote\scriptsize\else\small\fi% |
---|
166 | } |
---|
167 | |
---|
168 | % Redefine the 'normal' header/footer style when using "fancyhdr" package: |
---|
169 | \@ifundefined{fancyhf}{}{ |
---|
170 | % Use \pagestyle{normal} as the primary pagestyle for text. |
---|
171 | \fancypagestyle{normal}{ |
---|
172 | \fancyhf{} |
---|
173 | \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
---|
174 | \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} |
---|
175 | \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} |
---|
176 | \renewcommand{\headrulewidth}{0pt} |
---|
177 | \renewcommand{\footrulewidth}{0.4pt} |
---|
178 | } |
---|
179 | % Update the plain style so we get the page number & footer line, |
---|
180 | % but not a chapter or section title. This is to keep the first |
---|
181 | % page of a chapter and the blank page between chapters `clean.' |
---|
182 | \fancypagestyle{plain}{ |
---|
183 | \fancyhf{} |
---|
184 | \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
---|
185 | \renewcommand{\headrulewidth}{0pt} |
---|
186 | \renewcommand{\footrulewidth}{0.4pt} |
---|
187 | } |
---|
188 | % Redefine \cleardoublepage so that the blank page between chapters |
---|
189 | % gets the plain style and not the fancy style. This is described |
---|
190 | % in the documentation for the fancyhdr package by Piet von Oostrum. |
---|
191 | \@ifundefined{chapter}{}{ |
---|
192 | \renewcommand{\cleardoublepage}{ |
---|
193 | \clearpage\if@openright \ifodd\c@page\else |
---|
194 | \hbox{} |
---|
195 | \thispagestyle{plain} |
---|
196 | \newpage |
---|
197 | \if@twocolumn\hbox{}\newpage\fi\fi\fi |
---|
198 | } |
---|
199 | } |
---|
200 | } |
---|
201 | |
---|
202 | % This sets up the {verbatim} environment to be indented and a minipage, |
---|
203 | % and to have all the other mostly nice properties that we want for |
---|
204 | % code samples. |
---|
205 | |
---|
206 | \let\py@OldVerbatim=\verbatim |
---|
207 | \let\py@OldEndVerbatim=\endverbatim |
---|
208 | \RequirePackage{verbatim} |
---|
209 | \let\py@OldVerbatimInput=\verbatiminput |
---|
210 | |
---|
211 | % Variable used by begin code command |
---|
212 | \newlength{\py@codewidth} |
---|
213 | |
---|
214 | \renewcommand{\verbatim}{% |
---|
215 | \setlength{\parindent}{1cm}% |
---|
216 | % Calculate the text width for the minipage: |
---|
217 | \setlength{\py@codewidth}{\linewidth}% |
---|
218 | \addtolength{\py@codewidth}{-\parindent}% |
---|
219 | % |
---|
220 | \par\indent% |
---|
221 | \begin{minipage}[t]{\py@codewidth}% |
---|
222 | \small% |
---|
223 | \py@OldVerbatim% |
---|
224 | } |
---|
225 | \renewcommand{\endverbatim}{% |
---|
226 | \py@OldEndVerbatim% |
---|
227 | \end{minipage}% |
---|
228 | } |
---|
229 | \renewcommand{\verbatiminput}[1]{% |
---|
230 | {\setlength{\parindent}{1cm}% |
---|
231 | % Calculate the text width for the minipage: |
---|
232 | \setlength{\py@codewidth}{\linewidth}% |
---|
233 | \addtolength{\py@codewidth}{-\parindent}% |
---|
234 | % |
---|
235 | \small% |
---|
236 | \begin{list}{}{\setlength{\leftmargin}{1cm}} |
---|
237 | \item% |
---|
238 | \py@OldVerbatimInput{#1}% |
---|
239 | \end{list} |
---|
240 | }% |
---|
241 | } |
---|
242 | |
---|
243 | % This does a similar thing for the {alltt} environment: |
---|
244 | \RequirePackage{alltt} |
---|
245 | \let\py@OldAllTT=\alltt |
---|
246 | \let\py@OldEndAllTT=\endalltt |
---|
247 | |
---|
248 | \renewcommand{\alltt}{% |
---|
249 | \setlength{\parindent}{1cm}% |
---|
250 | % Calculate the text width for the minipage: |
---|
251 | \setlength{\py@codewidth}{\linewidth}% |
---|
252 | \addtolength{\py@codewidth}{-\parindent}% |
---|
253 | \let\e=\textbackslash% |
---|
254 | % |
---|
255 | \par\indent% |
---|
256 | \begin{minipage}[t]{\py@codewidth}% |
---|
257 | \small% |
---|
258 | \py@OldAllTT% |
---|
259 | } |
---|
260 | \renewcommand{\endalltt}{% |
---|
261 | \py@OldEndAllTT% |
---|
262 | \end{minipage}% |
---|
263 | } |
---|
264 | |
---|
265 | |
---|
266 | \newcommand{\py@modulebadkey}{{--just-some-junk--}} |
---|
267 | |
---|
268 | |
---|
269 | %% Lots of index-entry generation support. |
---|
270 | |
---|
271 | % Command to wrap around stuff that refers to function / module / |
---|
272 | % attribute names in the index. Default behavior: like \code{}. To |
---|
273 | % just keep the index entries in the roman font, uncomment the second |
---|
274 | % definition; it matches O'Reilly style more. |
---|
275 | % |
---|
276 | \newcommand{\py@idxcode}[1]{\texttt{#1}} |
---|
277 | %\renewcommand{\py@idxcode}[1]{#1} |
---|
278 | |
---|
279 | % Command to generate two index entries (using subentries) |
---|
280 | \newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}} |
---|
281 | |
---|
282 | % And three entries (using only one level of subentries) |
---|
283 | \newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}} |
---|
284 | |
---|
285 | % And four (again, using only one level of subentries) |
---|
286 | \newcommand{\indexiv}[4]{ |
---|
287 | \index{#1!#2 #3 #4} |
---|
288 | \index{#2!#3 #4, #1} |
---|
289 | \index{#3!#4, #1 #2} |
---|
290 | \index{#4!#1 #2 #3} |
---|
291 | } |
---|
292 | |
---|
293 | % Command to generate a reference to a function, statement, keyword, |
---|
294 | % operator. |
---|
295 | \newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}} |
---|
296 | \newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}} |
---|
297 | \newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}} |
---|
298 | \newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}} |
---|
299 | \newcommand{\obindex}[1]{\indexii{object}{#1}} |
---|
300 | \newcommand{\bifuncindex}[1]{% |
---|
301 | \index{#1@{\py@idxcode{#1()}} (built-in function)}} |
---|
302 | |
---|
303 | % Add an index entry for a module |
---|
304 | \newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}} |
---|
305 | \newcommand{\refmodindex}[1]{\py@refmodule{#1}{}} |
---|
306 | \newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }} |
---|
307 | \newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }} |
---|
308 | \newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }} |
---|
309 | |
---|
310 | % Refer to a module's documentation using a hyperlink of the module's |
---|
311 | % name, at least if we're building PDF: |
---|
312 | \ifpdf |
---|
313 | \newcommand{\refmodule}[2][\py@modulebadkey]{% |
---|
314 | \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
---|
315 | \py@linkToName{label-module-\py@modulekey}{\module{#2}}% |
---|
316 | } |
---|
317 | \else |
---|
318 | \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}} |
---|
319 | \fi |
---|
320 | |
---|
321 | % support for the module index |
---|
322 | \newif\ifpy@UseModuleIndex |
---|
323 | \py@UseModuleIndexfalse |
---|
324 | |
---|
325 | \newcommand{\makemodindex}{ |
---|
326 | \newwrite\modindexfile |
---|
327 | \openout\modindexfile=mod\jobname.idx |
---|
328 | \py@UseModuleIndextrue |
---|
329 | } |
---|
330 | |
---|
331 | % Add the defining entry for a module |
---|
332 | \newcommand{\py@modindex}[2]{% |
---|
333 | \renewcommand{\py@thismodule}{#1} |
---|
334 | \setindexsubitem{(in module #1)}% |
---|
335 | \index{#1@{\py@idxcode{#1}} (#2module)|textbf}% |
---|
336 | \ifpy@UseModuleIndex% |
---|
337 | \@ifundefined{py@modplat@\py@thismodulekey}{ |
---|
338 | \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}% |
---|
339 | }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} % |
---|
340 | \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}% |
---|
341 | } |
---|
342 | \fi% |
---|
343 | } |
---|
344 | |
---|
345 | % *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! *** |
---|
346 | |
---|
347 | % built-in & Python modules in the main distribution |
---|
348 | \newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }% |
---|
349 | \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
---|
350 | \newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }% |
---|
351 | \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
---|
352 | |
---|
353 | % Python & extension modules outside the main distribution |
---|
354 | \newcommand{\modindex}[1]{\py@modindex{#1}{}% |
---|
355 | \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
---|
356 | \newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }% |
---|
357 | \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
---|
358 | |
---|
359 | % Additional string for an index entry |
---|
360 | \newif\ifpy@usingsubitem\py@usingsubitemfalse |
---|
361 | \newcommand{\py@indexsubitem}{} |
---|
362 | \newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}% |
---|
363 | \py@usingsubitemtrue} |
---|
364 | \newcommand{\ttindex}[1]{% |
---|
365 | \ifpy@usingsubitem |
---|
366 | \index{#1@{\py@idxcode{#1}}\py@indexsubitem}% |
---|
367 | \else% |
---|
368 | \index{#1@{\py@idxcode{#1}}}% |
---|
369 | \fi% |
---|
370 | } |
---|
371 | \newcommand{\withsubitem}[2]{% |
---|
372 | \begingroup% |
---|
373 | \def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}% |
---|
374 | #2% |
---|
375 | \endgroup% |
---|
376 | } |
---|
377 | |
---|
378 | |
---|
379 | % Module synopsis processing ----------------------------------------------- |
---|
380 | % |
---|
381 | \newcommand{\py@thisclass}{} |
---|
382 | \newcommand{\py@thismodule}{} |
---|
383 | \newcommand{\py@thismodulekey}{} |
---|
384 | \newcommand{\py@thismoduletype}{} |
---|
385 | |
---|
386 | \newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }} |
---|
387 | \newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }} |
---|
388 | \newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }} |
---|
389 | \newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}} |
---|
390 | |
---|
391 | \newif\ifpy@HaveModSynopsis \py@HaveModSynopsisfalse |
---|
392 | \newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse |
---|
393 | \newif\ifpy@HaveModPlatform \py@HaveModPlatformfalse |
---|
394 | |
---|
395 | % \declaremodule[key]{type}{name} |
---|
396 | \newcommand{\declaremodule}[3][\py@modulebadkey]{ |
---|
397 | \py@openModSynopsisFile |
---|
398 | \renewcommand{\py@thismoduletype}{#2} |
---|
399 | \ifx\py@modulebadkey#1 |
---|
400 | \renewcommand{\py@thismodulekey}{#3} |
---|
401 | \else |
---|
402 | \renewcommand{\py@thismodulekey}{#1} |
---|
403 | \fi |
---|
404 | \@ifundefined{py@#2IndexModule}{% |
---|
405 | \typeout{*** MACRO declaremodule called with unknown module type: `#2'} |
---|
406 | \py@IndexModule{#3}% |
---|
407 | }{% |
---|
408 | \csname py@#2IndexModule\endcsname{#3}% |
---|
409 | } |
---|
410 | \label{module-\py@thismodulekey} |
---|
411 | } |
---|
412 | \newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse |
---|
413 | \newcommand{\py@ModPlatformFilename}{\jobname.pla} |
---|
414 | \newcommand{\platform}[1]{ |
---|
415 | \ifpy@ModPlatformFileIsOpen\else |
---|
416 | \newwrite\py@ModPlatformFile |
---|
417 | \openout\py@ModPlatformFile=\py@ModPlatformFilename |
---|
418 | \py@ModPlatformFileIsOpentrue |
---|
419 | \fi |
---|
420 | } |
---|
421 | \InputIfFileExists{\jobname.pla}{}{} |
---|
422 | \newcommand{\py@platformof}[2][\py@modulebadkey]{% |
---|
423 | \ifx\py@modulebadkey#1 \def\py@key{#2}% |
---|
424 | \else \def\py@key{#1}% |
---|
425 | \fi% |
---|
426 | \csname py@modplat@\py@key\endcsname% |
---|
427 | } |
---|
428 | \newcommand{\ignorePlatformAnnotation}[1]{} |
---|
429 | |
---|
430 | % \moduleauthor{name}{email} |
---|
431 | \newcommand{\moduleauthor}[2]{} |
---|
432 | |
---|
433 | % \sectionauthor{name}{email} |
---|
434 | \newcommand{\sectionauthor}[2]{} |
---|
435 | |
---|
436 | |
---|
437 | \newcommand{\py@defsynopsis}{Module has no synopsis.} |
---|
438 | \newcommand{\py@modulesynopsis}{\py@defsynopsis} |
---|
439 | \newcommand{\modulesynopsis}[1]{ |
---|
440 | \py@HaveModSynopsistrue |
---|
441 | \renewcommand{\py@modulesynopsis}{#1} |
---|
442 | } |
---|
443 | |
---|
444 | % define the file |
---|
445 | \newwrite\py@ModSynopsisFile |
---|
446 | |
---|
447 | % hacked from \addtocontents from latex.ltx: |
---|
448 | \long\def\py@writeModSynopsisFile#1{% |
---|
449 | \protected@write\py@ModSynopsisFile% |
---|
450 | {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}% |
---|
451 | {\string#1}% |
---|
452 | } |
---|
453 | \newcommand{\py@closeModSynopsisFile}{ |
---|
454 | \ifpy@ModSynopsisFileIsOpen |
---|
455 | \closeout\py@ModSynopsisFile |
---|
456 | \py@ModSynopsisFileIsOpenfalse |
---|
457 | \fi |
---|
458 | } |
---|
459 | \newcommand{\py@openModSynopsisFile}{ |
---|
460 | \ifpy@ModSynopsisFileIsOpen\else |
---|
461 | \openout\py@ModSynopsisFile=\py@ModSynopsisFilename |
---|
462 | \py@ModSynopsisFileIsOpentrue |
---|
463 | \fi |
---|
464 | } |
---|
465 | |
---|
466 | \newcommand{\py@ProcessModSynopsis}{ |
---|
467 | \ifpy@HaveModSynopsis |
---|
468 | \py@writeModSynopsisFile{\modulesynopsis% |
---|
469 | {\py@thismodulekey}{\py@thismodule}% |
---|
470 | {\py@thismoduletype}{\py@modulesynopsis}}% |
---|
471 | \py@HaveModSynopsisfalse |
---|
472 | \fi |
---|
473 | \renewcommand{\py@modulesynopsis}{\py@defsynopsis} |
---|
474 | } |
---|
475 | \AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile} |
---|
476 | |
---|
477 | |
---|
478 | \long\def\py@writeModPlatformFile#1{% |
---|
479 | \protected@write\py@ModPlatformFile% |
---|
480 | {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}% |
---|
481 | {\string#1}% |
---|
482 | } |
---|
483 | |
---|
484 | |
---|
485 | \newcommand{\localmoduletable}{ |
---|
486 | \IfFileExists{\py@ModSynopsisFilename}{ |
---|
487 | \begin{synopsistable} |
---|
488 | \input{\py@ModSynopsisFilename} |
---|
489 | \end{synopsistable} |
---|
490 | }{} |
---|
491 | } |
---|
492 | |
---|
493 | \ifpdf |
---|
494 | \newcommand{\py@ModSynopsisSummary}[4]{% |
---|
495 | \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\ |
---|
496 | } |
---|
497 | \else |
---|
498 | \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\} |
---|
499 | \fi |
---|
500 | \newenvironment{synopsistable}{ |
---|
501 | % key, name, type, synopsis |
---|
502 | \let\modulesynopsis=\py@ModSynopsisSummary |
---|
503 | \begin{tabular}{ll} |
---|
504 | }{ |
---|
505 | \end{tabular} |
---|
506 | } |
---|
507 | % |
---|
508 | % -------------------------------------------------------------------------- |
---|
509 | |
---|
510 | |
---|
511 | \newcommand{\py@reset}{ |
---|
512 | \py@usingsubitemfalse |
---|
513 | \py@ProcessModSynopsis |
---|
514 | \renewcommand{\py@thisclass}{} |
---|
515 | \renewcommand{\py@thismodule}{} |
---|
516 | \renewcommand{\py@thismodulekey}{} |
---|
517 | \renewcommand{\py@thismoduletype}{} |
---|
518 | } |
---|
519 | |
---|
520 | % Augment the sectioning commands used to get our own font family in place, |
---|
521 | % and reset some internal data items: |
---|
522 | \renewcommand{\section}{\py@reset% |
---|
523 | \@startsection{section}{1}{\z@}% |
---|
524 | {-3.5ex \@plus -1ex \@minus -.2ex}% |
---|
525 | {2.3ex \@plus.2ex}% |
---|
526 | {\reset@font\Large\py@HeaderFamily}} |
---|
527 | \renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}% |
---|
528 | {-3.25ex\@plus -1ex \@minus -.2ex}% |
---|
529 | {1.5ex \@plus .2ex}% |
---|
530 | {\reset@font\large\py@HeaderFamily}} |
---|
531 | \renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}% |
---|
532 | {-3.25ex\@plus -1ex \@minus -.2ex}% |
---|
533 | {1.5ex \@plus .2ex}% |
---|
534 | {\reset@font\normalsize\py@HeaderFamily}} |
---|
535 | \renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}% |
---|
536 | {3.25ex \@plus1ex \@minus.2ex}% |
---|
537 | {-1em}% |
---|
538 | {\reset@font\normalsize\py@HeaderFamily}} |
---|
539 | \renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}% |
---|
540 | {3.25ex \@plus1ex \@minus .2ex}% |
---|
541 | {-1em}% |
---|
542 | {\reset@font\normalsize\py@HeaderFamily}} |
---|
543 | |
---|
544 | |
---|
545 | % Now for a lot of semantically-loaded environments that do a ton of magical |
---|
546 | % things to get the right formatting and index entries for the stuff in |
---|
547 | % Python modules and C API. |
---|
548 | |
---|
549 | |
---|
550 | % {fulllineitems} is used in one place in libregex.tex, but is really for |
---|
551 | % internal use in this file. |
---|
552 | % |
---|
553 | \newcommand{\py@itemnewline}[1]{% |
---|
554 | \@tempdima\linewidth% |
---|
555 | \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% |
---|
556 | } |
---|
557 | |
---|
558 | \newenvironment{fulllineitems}{ |
---|
559 | \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt |
---|
560 | \rightmargin 0pt \topsep -\parskip \partopsep \parskip |
---|
561 | \itemsep -\parsep |
---|
562 | \let\makelabel=\py@itemnewline} |
---|
563 | }{\end{list}} |
---|
564 | |
---|
565 | % \optional is mostly for use in the arguments parameters to the various |
---|
566 | % {*desc} environments defined below, but may be used elsewhere. Known to |
---|
567 | % be used in the debugger chapter. |
---|
568 | % |
---|
569 | % Typical usage: |
---|
570 | % |
---|
571 | % \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}} |
---|
572 | % ^^^ ^^^ |
---|
573 | % No space here No space here |
---|
574 | % |
---|
575 | % When a function has multiple optional parameters, \optional should be |
---|
576 | % nested, not chained. This is right: |
---|
577 | % |
---|
578 | % \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}} |
---|
579 | % |
---|
580 | \let\py@badkey=\@undefined |
---|
581 | |
---|
582 | \newcommand{\optional}[1]{% |
---|
583 | {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} |
---|
584 | |
---|
585 | % This can be used when a function or method accepts an varying number |
---|
586 | % of arguments, such as by using the *args syntax in the parameter list. |
---|
587 | \newcommand{\py@moreargs}{...} |
---|
588 | |
---|
589 | % This can be used when you don't want to document the parameters to a |
---|
590 | % function or method, but simply state that it's an alias for |
---|
591 | % something else. |
---|
592 | \newcommand{\py@unspecified}{...} |
---|
593 | |
---|
594 | |
---|
595 | \newlength{\py@argswidth} |
---|
596 | \newcommand{\py@sigparams}[1]{% |
---|
597 | \parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}} |
---|
598 | \newcommand{\py@sigline}[2]{% |
---|
599 | \settowidth{\py@argswidth}{#1\code{(}}% |
---|
600 | \addtolength{\py@argswidth}{-2\py@argswidth}% |
---|
601 | \addtolength{\py@argswidth}{\textwidth}% |
---|
602 | \item[#1\code{(}\py@sigparams{#2}]} |
---|
603 | |
---|
604 | % C functions ------------------------------------------------------------ |
---|
605 | % \begin{cfuncdesc}[refcount]{type}{name}{arglist} |
---|
606 | % Note that the [refcount] slot should only be filled in by |
---|
607 | % tools/anno-api.py; it pulls the value from the refcounts database. |
---|
608 | \newcommand{\cfuncline}[3]{ |
---|
609 | \py@sigline{\code{#1 \bfcode{#2}}}{#3}% |
---|
610 | \index{#2@{\py@idxcode{#2()}}} |
---|
611 | } |
---|
612 | \newenvironment{cfuncdesc}[4][\py@badkey]{ |
---|
613 | \begin{fulllineitems} |
---|
614 | \cfuncline{#2}{#3}{#4} |
---|
615 | \ifx#1\@undefined\else% |
---|
616 | \emph{Return value: \textbf{#1}.}\\ |
---|
617 | \fi |
---|
618 | }{\end{fulllineitems}} |
---|
619 | |
---|
620 | % C variables ------------------------------------------------------------ |
---|
621 | % \begin{cvardesc}{type}{name} |
---|
622 | \newenvironment{cvardesc}[2]{ |
---|
623 | \begin{fulllineitems} |
---|
624 | \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}] |
---|
625 | }{\end{fulllineitems}} |
---|
626 | |
---|
627 | % C data types ----------------------------------------------------------- |
---|
628 | % \begin{ctypedesc}[index name]{typedef name} |
---|
629 | \newenvironment{ctypedesc}[2][\py@badkey]{ |
---|
630 | \begin{fulllineitems} |
---|
631 | \item[\bfcode{#2}% |
---|
632 | \ifx#1\@undefined% |
---|
633 | \index{#2@{\py@idxcode{#2}} (C type)} |
---|
634 | \else% |
---|
635 | \index{#2@{\py@idxcode{#1}} (C type)} |
---|
636 | \fi] |
---|
637 | }{\end{fulllineitems}} |
---|
638 | |
---|
639 | % C type fields ---------------------------------------------------------- |
---|
640 | % \begin{cmemberdesc}{container type}{ctype}{membername} |
---|
641 | \newcommand{\cmemberline}[3]{ |
---|
642 | \item[\code{#2 \bfcode{#3}}] |
---|
643 | \index{#3@{\py@idxcode{#3}} (#1 member)} |
---|
644 | } |
---|
645 | \newenvironment{cmemberdesc}[3]{ |
---|
646 | \begin{fulllineitems} |
---|
647 | \cmemberline{#1}{#2}{#3} |
---|
648 | }{\end{fulllineitems}} |
---|
649 | |
---|
650 | % Funky macros ----------------------------------------------------------- |
---|
651 | % \begin{csimplemacrodesc}{name} |
---|
652 | % -- "simple" because it has no args; NOT for constant definitions! |
---|
653 | \newenvironment{csimplemacrodesc}[1]{ |
---|
654 | \begin{fulllineitems} |
---|
655 | \item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}] |
---|
656 | }{\end{fulllineitems}} |
---|
657 | |
---|
658 | % simple functions (not methods) ----------------------------------------- |
---|
659 | % \begin{funcdesc}{name}{args} |
---|
660 | \newcommand{\funcline}[2]{% |
---|
661 | \funclineni{#1}{#2}% |
---|
662 | \index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}} |
---|
663 | \newenvironment{funcdesc}[2]{ |
---|
664 | \begin{fulllineitems} |
---|
665 | \funcline{#1}{#2} |
---|
666 | }{\end{fulllineitems}} |
---|
667 | |
---|
668 | % similar to {funcdesc}, but doesn't add to the index |
---|
669 | \newcommand{\funclineni}[2]{% |
---|
670 | \py@sigline{\bfcode{#1}}{#2}} |
---|
671 | \newenvironment{funcdescni}[2]{ |
---|
672 | \begin{fulllineitems} |
---|
673 | \funclineni{#1}{#2} |
---|
674 | }{\end{fulllineitems}} |
---|
675 | |
---|
676 | % classes ---------------------------------------------------------------- |
---|
677 | % \begin{classdesc}{name}{constructor args} |
---|
678 | \newenvironment{classdesc}[2]{ |
---|
679 | % Using \renewcommand doesn't work for this, for unknown reasons: |
---|
680 | \global\def\py@thisclass{#1} |
---|
681 | \begin{fulllineitems} |
---|
682 | \py@sigline{\strong{class }\bfcode{#1}}{#2}% |
---|
683 | \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)} |
---|
684 | }{\end{fulllineitems}} |
---|
685 | |
---|
686 | % \begin{classdesc*}{name} |
---|
687 | \newenvironment{classdesc*}[1]{ |
---|
688 | % Using \renewcommand doesn't work for this, for unknown reasons: |
---|
689 | \global\def\py@thisclass{#1} |
---|
690 | \begin{fulllineitems} |
---|
691 | \item[\strong{class }\code{\bfcode{#1}}% |
---|
692 | \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}] |
---|
693 | }{\end{fulllineitems}} |
---|
694 | |
---|
695 | % \begin{excclassdesc}{name}{constructor args} |
---|
696 | % but indexes as an exception |
---|
697 | \newenvironment{excclassdesc}[2]{ |
---|
698 | % Using \renewcommand doesn't work for this, for unknown reasons: |
---|
699 | \global\def\py@thisclass{#1} |
---|
700 | \begin{fulllineitems} |
---|
701 | \py@sigline{\strong{exception }\bfcode{#1}}{#2}% |
---|
702 | \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)} |
---|
703 | }{\end{fulllineitems}} |
---|
704 | |
---|
705 | % There is no corresponding {excclassdesc*} environment. To describe |
---|
706 | % a class exception without parameters, use the {excdesc} environment. |
---|
707 | |
---|
708 | |
---|
709 | \let\py@classbadkey=\@undefined |
---|
710 | |
---|
711 | % object method ---------------------------------------------------------- |
---|
712 | % \begin{methoddesc}[classname]{methodname}{args} |
---|
713 | \newcommand{\methodline}[3][\@undefined]{ |
---|
714 | \methodlineni{#2}{#3} |
---|
715 | \ifx#1\@undefined |
---|
716 | \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)} |
---|
717 | \else |
---|
718 | \index{#2@{\py@idxcode{#2()}} (#1 method)} |
---|
719 | \fi |
---|
720 | } |
---|
721 | \newenvironment{methoddesc}[3][\@undefined]{ |
---|
722 | \begin{fulllineitems} |
---|
723 | \ifx#1\@undefined |
---|
724 | \methodline{#2}{#3} |
---|
725 | \else |
---|
726 | \def\py@thisclass{#1} |
---|
727 | \methodline{#2}{#3} |
---|
728 | \fi |
---|
729 | }{\end{fulllineitems}} |
---|
730 | |
---|
731 | % similar to {methoddesc}, but doesn't add to the index |
---|
732 | % (never actually uses the optional argument) |
---|
733 | \newcommand{\methodlineni}[3][\py@classbadkey]{% |
---|
734 | \py@sigline{\bfcode{#2}}{#3}} |
---|
735 | \newenvironment{methoddescni}[3][\py@classbadkey]{ |
---|
736 | \begin{fulllineitems} |
---|
737 | \methodlineni{#2}{#3} |
---|
738 | }{\end{fulllineitems}} |
---|
739 | |
---|
740 | % object data attribute -------------------------------------------------- |
---|
741 | % \begin{memberdesc}[classname]{membername} |
---|
742 | \newcommand{\memberline}[2][\py@classbadkey]{% |
---|
743 | \ifx#1\@undefined |
---|
744 | \memberlineni{#2} |
---|
745 | \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)} |
---|
746 | \else |
---|
747 | \memberlineni{#2} |
---|
748 | \index{#2@{\py@idxcode{#2}} (#1 attribute)} |
---|
749 | \fi |
---|
750 | } |
---|
751 | \newenvironment{memberdesc}[2][\py@classbadkey]{ |
---|
752 | \begin{fulllineitems} |
---|
753 | \ifx#1\@undefined |
---|
754 | \memberline{#2} |
---|
755 | \else |
---|
756 | \def\py@thisclass{#1} |
---|
757 | \memberline{#2} |
---|
758 | \fi |
---|
759 | }{\end{fulllineitems}} |
---|
760 | |
---|
761 | % similar to {memberdesc}, but doesn't add to the index |
---|
762 | % (never actually uses the optional argument) |
---|
763 | \newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]} |
---|
764 | \newenvironment{memberdescni}[2][\py@classbadkey]{ |
---|
765 | \begin{fulllineitems} |
---|
766 | \memberlineni{#2} |
---|
767 | }{\end{fulllineitems}} |
---|
768 | |
---|
769 | % For exceptions: -------------------------------------------------------- |
---|
770 | % \begin{excdesc}{name} |
---|
771 | % -- for constructor information, use excclassdesc instead |
---|
772 | \newenvironment{excdesc}[1]{ |
---|
773 | \begin{fulllineitems} |
---|
774 | \item[\strong{exception }\bfcode{#1}% |
---|
775 | \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}] |
---|
776 | }{\end{fulllineitems}} |
---|
777 | |
---|
778 | % Module data or constants: ---------------------------------------------- |
---|
779 | % \begin{datadesc}{name} |
---|
780 | \newcommand{\dataline}[1]{% |
---|
781 | \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}} |
---|
782 | \newenvironment{datadesc}[1]{ |
---|
783 | \begin{fulllineitems} |
---|
784 | \dataline{#1} |
---|
785 | }{\end{fulllineitems}} |
---|
786 | |
---|
787 | % similar to {datadesc}, but doesn't add to the index |
---|
788 | \newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak} |
---|
789 | \newenvironment{datadescni}[1]{ |
---|
790 | \begin{fulllineitems} |
---|
791 | \datalineni{#1} |
---|
792 | }{\end{fulllineitems}} |
---|
793 | |
---|
794 | % bytecode instruction --------------------------------------------------- |
---|
795 | % \begin{opcodedesc}{name}{var} |
---|
796 | % -- {var} may be {} |
---|
797 | \newenvironment{opcodedesc}[2]{ |
---|
798 | \begin{fulllineitems} |
---|
799 | \item[\bfcode{#1}\quad\var{#2}] |
---|
800 | }{\end{fulllineitems}} |
---|
801 | |
---|
802 | |
---|
803 | \newcommand{\nodename}[1]{\label{#1}} |
---|
804 | |
---|
805 | % For these commands, use \command{} to get the typography right, not |
---|
806 | % {\command}. This works better with the texinfo translation. |
---|
807 | \newcommand{\ABC}{{\sc abc}} |
---|
808 | \newcommand{\UNIX}{{\sc Unix}} |
---|
809 | \newcommand{\POSIX}{POSIX} |
---|
810 | \newcommand{\ASCII}{{\sc ascii}} |
---|
811 | \newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}} |
---|
812 | \newcommand{\C}{C} |
---|
813 | \newcommand{\EOF}{{\sc eof}} |
---|
814 | \newcommand{\NULL}{\constant{NULL}} |
---|
815 | \newcommand{\infinity}{\ensuremath{\infty}} |
---|
816 | \newcommand{\plusminus}{\ensuremath{\pm}} |
---|
817 | |
---|
818 | % \guilabel{Start} |
---|
819 | \newcommand{\guilabel}[1]{\textsf{#1}} |
---|
820 | % \menuselection{Start \sub Programs \sub Python} |
---|
821 | \newcommand{\menuselection}[1]{\guilabel{{\def\sub{ \ensuremath{>} }#1}}} |
---|
822 | |
---|
823 | % Also for consistency: spell Python "Python", not "python"! |
---|
824 | |
---|
825 | % code is the most difficult one... |
---|
826 | \newcommand{\code}[1]{\textrm{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}% |
---|
827 | \texttt{#1}}} |
---|
828 | |
---|
829 | \newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font |
---|
830 | \newcommand{\csimplemacro}[1]{\code{#1}} |
---|
831 | \newcommand{\kbd}[1]{\code{#1}} |
---|
832 | \newcommand{\samp}[1]{`\code{#1}'} |
---|
833 | \newcommand{\var}[1]{% |
---|
834 | \ifmmode% |
---|
835 | \hbox{\py@defaultsize\textrm{\textit{#1\/}}}% |
---|
836 | \else% |
---|
837 | \py@defaultsize\textrm{\textit{#1\/}}% |
---|
838 | \fi% |
---|
839 | } |
---|
840 | \renewcommand{\emph}[1]{{\em #1}} |
---|
841 | \newcommand{\dfn}[1]{\emph{#1}} |
---|
842 | \newcommand{\strong}[1]{{\bf #1}} |
---|
843 | % let's experiment with a new font: |
---|
844 | \newcommand{\file}[1]{`\filenq{#1}'} |
---|
845 | \newcommand{\filenq}[1]{{\py@smallsize\textsf{\let\e=\textbackslash#1}}} |
---|
846 | |
---|
847 | % Use this def/redef approach for \url{} since hyperref defined this already, |
---|
848 | % but only if we actually used hyperref: |
---|
849 | \ifpdf |
---|
850 | \newcommand{\url}[1]{{% |
---|
851 | \py@pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}% |
---|
852 | \py@LinkColor% color of the link text |
---|
853 | \py@smallsize\sf #1% |
---|
854 | \py@NormalColor% Turn it back off; these are declarative |
---|
855 | \pdfendlink}% and don't appear bound to the current |
---|
856 | }% formatting "box". |
---|
857 | \else |
---|
858 | \newcommand{\url}[1]{\mbox{\py@smallsize\textsf{#1}}} |
---|
859 | \fi |
---|
860 | \newcommand{\email}[1]{{\py@smallsize\textsf{#1}}} |
---|
861 | \newcommand{\newsgroup}[1]{{\py@smallsize\textsf{#1}}} |
---|
862 | |
---|
863 | \newcommand{\py@varvars}[1]{{% |
---|
864 | {\let\unspecified=\py@unspecified% |
---|
865 | \let\moreargs=\py@moreargs% |
---|
866 | \var{#1}}}} |
---|
867 | |
---|
868 | % I'd really like to get rid of this! |
---|
869 | \newif\iftexi\texifalse |
---|
870 | |
---|
871 | % This is used to get l2h to put the copyright and abstract on |
---|
872 | % a separate HTML page. |
---|
873 | \newif\ifhtml\htmlfalse |
---|
874 | |
---|
875 | |
---|
876 | % These should be used for all references to identifiers which are |
---|
877 | % used to refer to instances of specific language constructs. See the |
---|
878 | % names for specific semantic assignments. |
---|
879 | % |
---|
880 | % For now, don't do anything really fancy with them; just use them as |
---|
881 | % logical markup. This might change in the future. |
---|
882 | % |
---|
883 | \newcommand{\module}[1]{\texttt{#1}} |
---|
884 | \newcommand{\keyword}[1]{\texttt{#1}} |
---|
885 | \newcommand{\exception}[1]{\texttt{#1}} |
---|
886 | \newcommand{\class}[1]{\texttt{#1}} |
---|
887 | \newcommand{\function}[1]{\texttt{#1}} |
---|
888 | \newcommand{\member}[1]{\texttt{#1}} |
---|
889 | \newcommand{\method}[1]{\texttt{#1}} |
---|
890 | |
---|
891 | \newcommand{\pytype}[1]{#1} % built-in Python type |
---|
892 | |
---|
893 | \newcommand{\cfunction}[1]{\texttt{#1}} |
---|
894 | \newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name |
---|
895 | \newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global |
---|
896 | |
---|
897 | \newcommand{\mailheader}[1]{{\py@smallsize\textsf{#1:}}} |
---|
898 | \newcommand{\mimetype}[1]{{\py@smallsize\textsf{#1}}} |
---|
899 | % The \! is a "negative thin space" in math mode. |
---|
900 | \newcommand{\regexp}[1]{% |
---|
901 | {\tiny$^{^\lceil}\!\!$% |
---|
902 | {\py@defaultsize\code{#1}}% |
---|
903 | $\!\rfloor\!$% |
---|
904 | }} |
---|
905 | \newcommand{\envvar}[1]{% |
---|
906 | #1% |
---|
907 | \index{#1}% |
---|
908 | \index{environment variables!{#1}}% |
---|
909 | } |
---|
910 | \newcommand{\makevar}[1]{#1} % variable in a Makefile |
---|
911 | \newcommand{\character}[1]{\samp{#1}} |
---|
912 | |
---|
913 | % constants defined in Python modules or C headers, not language constants: |
---|
914 | \newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic |
---|
915 | |
---|
916 | \newcommand{\manpage}[2]{{\emph{#1}(#2)}} |
---|
917 | \newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}} |
---|
918 | \newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}} |
---|
919 | \newcommand{\program}[1]{\strong{#1}} |
---|
920 | \newcommand{\programopt}[1]{\strong{#1}} |
---|
921 | % Note that \longprogramopt provides the '--'! |
---|
922 | \newcommand{\longprogramopt}[1]{\strong{-{}-#1}} |
---|
923 | |
---|
924 | % \ulink{link text}{URL} |
---|
925 | \ifpdf |
---|
926 | \newcommand{\ulink}[2]{{% |
---|
927 | % For PDF, we *should* only generate a link when the URL is absolute. |
---|
928 | \py@pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#2)}% |
---|
929 | \py@LinkColor% color of the link text |
---|
930 | #1% |
---|
931 | \py@NormalColor% Turn it back off; these are declarative |
---|
932 | \pdfendlink}% and don't appear bound to the current |
---|
933 | }% formatting "box". |
---|
934 | \else |
---|
935 | \newcommand{\ulink}[2]{#1} |
---|
936 | \fi |
---|
937 | |
---|
938 | % cited titles: \citetitle{Title of Work} |
---|
939 | % online: \citetitle[url-to-resource]{Title of Work} |
---|
940 | \ifpdf |
---|
941 | \newcommand{\citetitle}[2][\py@modulebadkey]{% |
---|
942 | \ifx\py@modulebadkey#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi% |
---|
943 | } |
---|
944 | \else |
---|
945 | \newcommand{\citetitle}[2][URL]{\emph{#2}} |
---|
946 | \fi |
---|
947 | |
---|
948 | |
---|
949 | |
---|
950 | % This version is being checked in for the historical record; it shows |
---|
951 | % how I've managed to get some aspects of this to work. It will not |
---|
952 | % be used in practice, so a subsequent revision will change things |
---|
953 | % again. This version has problems, but shows how to do something |
---|
954 | % that proved more tedious than I'd expected, so I don't want to lose |
---|
955 | % the example completely. |
---|
956 | % |
---|
957 | \newcommand{\grammartoken}[1]{\texttt{#1}} |
---|
958 | \newenvironment{productionlist}[1][\py@badkey]{ |
---|
959 | \def\optional##1{{\Large[}##1{\Large]}} |
---|
960 | \def\production##1##2{\code{##1}&::=&\code{##2}\\} |
---|
961 | \def\productioncont##1{& &\code{##1}\\} |
---|
962 | \def\token##1{##1} |
---|
963 | \let\grammartoken=\token |
---|
964 | \parindent=2em |
---|
965 | \indent |
---|
966 | \begin{tabular}{lcl} |
---|
967 | }{% |
---|
968 | \end{tabular} |
---|
969 | } |
---|
970 | |
---|
971 | \newlength{\py@noticelength} |
---|
972 | |
---|
973 | \newcommand{\py@heavybox}{ |
---|
974 | \setlength{\fboxrule}{2pt} |
---|
975 | \setlength{\fboxsep}{7pt} |
---|
976 | \setlength{\py@noticelength}{\linewidth} |
---|
977 | \addtolength{\py@noticelength}{-2\fboxsep} |
---|
978 | \addtolength{\py@noticelength}{-2\fboxrule} |
---|
979 | \setlength{\shadowsize}{3pt} |
---|
980 | \Sbox |
---|
981 | \minipage{\py@noticelength} |
---|
982 | } |
---|
983 | \newcommand{\py@endheavybox}{ |
---|
984 | \endminipage |
---|
985 | \endSbox |
---|
986 | \fbox{\TheSbox} |
---|
987 | } |
---|
988 | |
---|
989 | % a 'note' is as plain as it gets: |
---|
990 | \newcommand{\py@noticelabel@note}{Note:} |
---|
991 | \newcommand{\py@noticestart@note}{} |
---|
992 | \newcommand{\py@noticeend@note}{} |
---|
993 | |
---|
994 | % a 'warning' gets more visible distinction: |
---|
995 | \newcommand{\py@noticelabel@warning}{Warning:} |
---|
996 | \newcommand{\py@noticestart@warning}{\py@heavybox} |
---|
997 | \newcommand{\py@noticeend@warning}{\py@endheavybox} |
---|
998 | |
---|
999 | \newenvironment{notice}[1][note]{ |
---|
1000 | \def\py@noticetype{#1} |
---|
1001 | \csname py@noticestart@#1\endcsname |
---|
1002 | \par\strong{\csname py@noticelabel@#1\endcsname} |
---|
1003 | }{\csname py@noticeend@\py@noticetype\endcsname} |
---|
1004 | \newcommand{\note}[1]{\strong{\py@noticelabel@note} #1} |
---|
1005 | \newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1} |
---|
1006 | |
---|
1007 | % Deprecation stuff. |
---|
1008 | % Should be extended to allow an index / list of deprecated stuff. But |
---|
1009 | % there's a lot of stuff that needs to be done to make that automatable. |
---|
1010 | % |
---|
1011 | % First parameter is the release number that deprecates the feature, the |
---|
1012 | % second is the action the should be taken by users of the feature. |
---|
1013 | % |
---|
1014 | % Example: |
---|
1015 | % \deprecated{1.5.1}{Use \method{frobnicate()} instead.} |
---|
1016 | % |
---|
1017 | \newcommand{\deprecated}[2]{% |
---|
1018 | \strong{Deprecated since release #1.} #2\par} |
---|
1019 | |
---|
1020 | % New stuff. |
---|
1021 | % This should be used to mark things which have been added to the |
---|
1022 | % development tree but that aren't in the release, but are documented. |
---|
1023 | % This allows release of documentation that already includes updated |
---|
1024 | % descriptions. Place at end of descriptor environment. |
---|
1025 | % |
---|
1026 | % Example: |
---|
1027 | % \versionadded{1.5.2} |
---|
1028 | % \versionchanged[short explanation]{2.0} |
---|
1029 | % |
---|
1030 | \newcommand{\versionadded}[2][\py@badkey]{% |
---|
1031 | \ifx#1\@undefined% |
---|
1032 | { New in version #2. }% |
---|
1033 | \else% |
---|
1034 | { New in version #2:\ #1. }% |
---|
1035 | \fi% |
---|
1036 | } |
---|
1037 | \newcommand{\versionchanged}[2][\py@badkey]{% |
---|
1038 | \ifx#1\@undefined% |
---|
1039 | { Changed in version #2. }% |
---|
1040 | \else% |
---|
1041 | { Changed in version #2:\ #1. }% |
---|
1042 | \fi% |
---|
1043 | } |
---|
1044 | |
---|
1045 | |
---|
1046 | % Tables. |
---|
1047 | % |
---|
1048 | \newenvironment{tableii}[4]{% |
---|
1049 | \begin{center}% |
---|
1050 | \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}% |
---|
1051 | \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline% |
---|
1052 | }{% |
---|
1053 | \end{tabular}% |
---|
1054 | \end{center}% |
---|
1055 | } |
---|
1056 | |
---|
1057 | \newenvironment{longtableii}[4]{% |
---|
1058 | \begin{center}% |
---|
1059 | \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}% |
---|
1060 | \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead% |
---|
1061 | }{% |
---|
1062 | \end{longtable}% |
---|
1063 | \end{center}% |
---|
1064 | } |
---|
1065 | |
---|
1066 | \newenvironment{tableiii}[5]{% |
---|
1067 | \begin{center}% |
---|
1068 | \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}% |
---|
1069 | \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\% |
---|
1070 | \hline% |
---|
1071 | }{% |
---|
1072 | \end{tabular}% |
---|
1073 | \end{center}% |
---|
1074 | } |
---|
1075 | |
---|
1076 | \newenvironment{longtableiii}[5]{% |
---|
1077 | \begin{center}% |
---|
1078 | \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}% |
---|
1079 | \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\% |
---|
1080 | \hline\endhead% |
---|
1081 | }{% |
---|
1082 | \end{longtable}% |
---|
1083 | \end{center}% |
---|
1084 | } |
---|
1085 | |
---|
1086 | \newenvironment{tableiv}[6]{% |
---|
1087 | \begin{center}% |
---|
1088 | \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}% |
---|
1089 | \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\% |
---|
1090 | \hline% |
---|
1091 | }{% |
---|
1092 | \end{tabular}% |
---|
1093 | \end{center}% |
---|
1094 | } |
---|
1095 | |
---|
1096 | \newenvironment{longtableiv}[6]{% |
---|
1097 | \begin{center}% |
---|
1098 | \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}% |
---|
1099 | \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}% |
---|
1100 | \\% |
---|
1101 | \hline\endhead% |
---|
1102 | }{% |
---|
1103 | \end{longtable}% |
---|
1104 | \end{center}% |
---|
1105 | } |
---|
1106 | |
---|
1107 | \newenvironment{tablev}[7]{% |
---|
1108 | \begin{center}% |
---|
1109 | \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}% |
---|
1110 | \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7} \\% |
---|
1111 | \hline% |
---|
1112 | }{% |
---|
1113 | \end{tabular}% |
---|
1114 | \end{center}% |
---|
1115 | } |
---|
1116 | |
---|
1117 | \newenvironment{longtablev}[7]{% |
---|
1118 | \begin{center}% |
---|
1119 | \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}% |
---|
1120 | \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7}% |
---|
1121 | \\% |
---|
1122 | \hline\endhead% |
---|
1123 | }{% |
---|
1124 | \end{longtable}% |
---|
1125 | \end{center}% |
---|
1126 | } |
---|
1127 | |
---|
1128 | % XXX Don't think we can use this yet, though it cleans up some |
---|
1129 | % tedious markup. There's no equivalent for the HTML transform yet, |
---|
1130 | % and that needs to exist. I don't know how to write it. |
---|
1131 | % |
---|
1132 | % This should really have something that makes it easier to bind a |
---|
1133 | % table's ``Notes'' column and an associated tablenotes environment, |
---|
1134 | % and generates the right magic for getting the numbers right in the |
---|
1135 | % table. |
---|
1136 | % |
---|
1137 | % So this is quite incomplete. |
---|
1138 | % |
---|
1139 | \newcounter{py@tablenotescounter} |
---|
1140 | \newenvironment{tablenotes}{% |
---|
1141 | \noindent Notes: |
---|
1142 | \par |
---|
1143 | \setcounter{py@tablenotescounter}{0} |
---|
1144 | \begin{list}{(\arabic{py@tablenotescounter})}% |
---|
1145 | {\usecounter{py@tablenotescounter}} |
---|
1146 | }{\end{list}} |
---|
1147 | |
---|
1148 | |
---|
1149 | % Cross-referencing (AMK, new impl. FLD) |
---|
1150 | % Sample usage: |
---|
1151 | % \begin{seealso} |
---|
1152 | % \seemodule{rand}{Uniform random number generator.}; % Module xref |
---|
1153 | % \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book |
---|
1154 | % |
---|
1155 | % % A funky case: module name contains '_'; have to supply an optional key |
---|
1156 | % \seemodule[copyreg]{copy_reg}{Interface constructor registration for |
---|
1157 | % \module{pickle}.} |
---|
1158 | % \end{seealso} |
---|
1159 | % |
---|
1160 | % Note that the last parameter for \seemodule and \seetext should be complete |
---|
1161 | % sentences and be terminated with the proper punctuation. |
---|
1162 | |
---|
1163 | \ifpdf |
---|
1164 | \newcommand{\py@seemodule}[3][\py@modulebadkey]{% |
---|
1165 | \par% |
---|
1166 | \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
---|
1167 | \begin{fulllineitems} |
---|
1168 | \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}} |
---|
1169 | (section \ref{module-\py@modulekey}):] |
---|
1170 | #3 |
---|
1171 | \end{fulllineitems} |
---|
1172 | } |
---|
1173 | \else |
---|
1174 | \newcommand{\py@seemodule}[3][\py@modulebadkey]{% |
---|
1175 | \par% |
---|
1176 | \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
---|
1177 | \begin{fulllineitems} |
---|
1178 | \item[Module \module{#2} (section \ref{module-\py@modulekey}):] |
---|
1179 | #3 |
---|
1180 | \end{fulllineitems} |
---|
1181 | } |
---|
1182 | \fi |
---|
1183 | |
---|
1184 | % \seelink{url}{link text}{why it's interesting} |
---|
1185 | \newcommand{\py@seelink}[3]{% |
---|
1186 | \par |
---|
1187 | \begin{fulllineitems} |
---|
1188 | \item[\ulink{#2}{#1}] |
---|
1189 | #3 |
---|
1190 | \end{fulllineitems} |
---|
1191 | } |
---|
1192 | % \seetitle[url]{title}{why it's interesting} |
---|
1193 | \newcommand{\py@seetitle}[3][\py@modulebadkey]{% |
---|
1194 | \par |
---|
1195 | \begin{fulllineitems} |
---|
1196 | \item[\citetitle{#2}] |
---|
1197 | \ifx\py@modulebadkey#1\else |
---|
1198 | \item[{\small{(\url{#1})}}] |
---|
1199 | \fi |
---|
1200 | #3 |
---|
1201 | \end{fulllineitems} |
---|
1202 | } |
---|
1203 | % \seepep{number}{title}{why it's interesting} |
---|
1204 | \newcommand{\py@seepep}[3]{% |
---|
1205 | \par% |
---|
1206 | \begin{fulllineitems} |
---|
1207 | \item[\pep{#1}, ``\emph{#2}''] |
---|
1208 | #3 |
---|
1209 | \end{fulllineitems} |
---|
1210 | } |
---|
1211 | % \seerfc{number}{title}{why it's interesting} |
---|
1212 | \newcommand{\py@seerfc}[3]{% |
---|
1213 | \par% |
---|
1214 | \begin{fulllineitems} |
---|
1215 | \item[\rfc{#1}, ``\emph{#2}''] |
---|
1216 | #3 |
---|
1217 | \end{fulllineitems} |
---|
1218 | } |
---|
1219 | % \seeurl{url}{why it's interesting} |
---|
1220 | \newcommand{\py@seeurl}[2]{% |
---|
1221 | \par% |
---|
1222 | \begin{fulllineitems} |
---|
1223 | \item[\url{#1}] |
---|
1224 | #2 |
---|
1225 | \end{fulllineitems} |
---|
1226 | } |
---|
1227 | |
---|
1228 | \newenvironment{seealso*}{ |
---|
1229 | \par |
---|
1230 | \def\seetext##1{\par{##1}} |
---|
1231 | \let\seemodule=\py@seemodule |
---|
1232 | \let\seepep=\py@seepep |
---|
1233 | \let\seerfc=\py@seerfc |
---|
1234 | \let\seetitle=\py@seetitle |
---|
1235 | \let\seeurl=\py@seeurl |
---|
1236 | \let\seelink=\py@seelink |
---|
1237 | }{\par} |
---|
1238 | \newenvironment{seealso}{ |
---|
1239 | \par |
---|
1240 | \strong{See Also:} |
---|
1241 | \par |
---|
1242 | \def\seetext##1{\par{##1}} |
---|
1243 | \let\seemodule=\py@seemodule |
---|
1244 | \let\seepep=\py@seepep |
---|
1245 | \let\seerfc=\py@seerfc |
---|
1246 | \let\seetitle=\py@seetitle |
---|
1247 | \let\seeurl=\py@seeurl |
---|
1248 | \let\seelink=\py@seelink |
---|
1249 | }{\par} |
---|
1250 | |
---|
1251 | % Allow the Python release number to be specified independently of the |
---|
1252 | % \date{}. This allows the date to reflect the document's date and |
---|
1253 | % release to specify the Python release that is documented. |
---|
1254 | % |
---|
1255 | \newcommand{\py@release}{} |
---|
1256 | \newcommand{\version}{} |
---|
1257 | \newcommand{\shortversion}{} |
---|
1258 | \newcommand{\releaseinfo}{} |
---|
1259 | \newcommand{\releasename}{Release} |
---|
1260 | \newcommand{\release}[1]{% |
---|
1261 | \renewcommand{\py@release}{\releasename\space\version}% |
---|
1262 | \renewcommand{\version}{#1}} |
---|
1263 | \newcommand{\setshortversion}[1]{% |
---|
1264 | \renewcommand{\shortversion}{#1}} |
---|
1265 | \newcommand{\setreleaseinfo}[1]{% |
---|
1266 | \renewcommand{\releaseinfo}{#1}} |
---|
1267 | |
---|
1268 | % Allow specification of the author's address separately from the |
---|
1269 | % author's name. This can be used to format them differently, which |
---|
1270 | % is a good thing. |
---|
1271 | % |
---|
1272 | \newcommand{\py@authoraddress}{} |
---|
1273 | \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}} |
---|
1274 | \let\developersaddress=\authoraddress |
---|
1275 | \let\developer=\author |
---|
1276 | \let\developers=\author |
---|
1277 | |
---|
1278 | % This sets up the fancy chapter headings that make the documents look |
---|
1279 | % at least a little better than the usual LaTeX output. |
---|
1280 | % |
---|
1281 | \@ifundefined{ChTitleVar}{}{ |
---|
1282 | \ChNameVar{\raggedleft\normalsize\py@HeaderFamily} |
---|
1283 | \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} |
---|
1284 | \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily} |
---|
1285 | % This creates chapter heads without the leading \vspace*{}: |
---|
1286 | \def\@makechapterhead#1{% |
---|
1287 | {\parindent \z@ \raggedright \normalfont |
---|
1288 | \ifnum \c@secnumdepth >\m@ne |
---|
1289 | \DOCH |
---|
1290 | \fi |
---|
1291 | \interlinepenalty\@M |
---|
1292 | \DOTI{#1} |
---|
1293 | } |
---|
1294 | } |
---|
1295 | } |
---|
1296 | |
---|
1297 | |
---|
1298 | % Definition lists; requested by AMK for HOWTO documents. Probably useful |
---|
1299 | % elsewhere as well, so keep in in the general style support. |
---|
1300 | % |
---|
1301 | \newenvironment{definitions}{% |
---|
1302 | \begin{description}% |
---|
1303 | \def\term##1{\item[##1]\mbox{}\\*[0mm]} |
---|
1304 | }{% |
---|
1305 | \end{description}% |
---|
1306 | } |
---|
1307 | |
---|
1308 | % Tell TeX about pathological hyphenation cases: |
---|
1309 | \hyphenation{Base-HTTP-Re-quest-Hand-ler} |
---|