/[escript]/trunk/doc/install/python.sty
ViewVC logotype

Contents of /trunk/doc/install/python.sty

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26