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

Annotation of /trunk/doc/cookbook/python.sty

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2632 - (hide annotations)
Wed Aug 26 22:18:19 2009 UTC (9 years, 10 months ago) by ahallam
File size: 40151 byte(s)
Regigger of cookbook directory structure. Examlples->examples/cookbook TEXT->doc/cookbook Figures-> doc/cookbook/figures
1 ahallam 2392 % $Id: python.sty 82 2004-10-26 06:53:54Z jgs $
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     \else
305     \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}}
306     \fi
307    
308     % support for the module index
309     \newif\ifpy@UseModuleIndex
310     \py@UseModuleIndexfalse
311    
312     \newcommand{\makemodindex}{
313     \newwrite\modindexfile
314     \openout\modindexfile=mod\jobname.idx
315     \py@UseModuleIndextrue
316     }
317    
318     % Add the defining entry for a module
319     \newcommand{\py@modindex}[2]{%
320     \renewcommand{\py@thismodule}{#1}
321     \setindexsubitem{(in module #1)}%
322     \index{#1@{\py@idxcode{#1}} (#2module)|textbf}%
323     \ifpy@UseModuleIndex%
324     \@ifundefined{py@modplat@\py@thismodulekey}{
325     \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}%
326     }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} %
327     \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}%
328     }
329     \fi%
330     }
331    
332     % *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***
333    
334     % built-in & Python modules in the main distribution
335     \newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }%
336     \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
337     \newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }%
338     \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
339    
340     % Python & extension modules outside the main distribution
341     \newcommand{\modindex}[1]{\py@modindex{#1}{}%
342     \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
343     \newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }%
344     \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
345    
346     % Additional string for an index entry
347     \newif\ifpy@usingsubitem\py@usingsubitemfalse
348     \newcommand{\py@indexsubitem}{}
349     \newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}%
350     \py@usingsubitemtrue}
351     \newcommand{\ttindex}[1]{%
352     \ifpy@usingsubitem
353     \index{#1@{\py@idxcode{#1}}\py@indexsubitem}%
354     \else%
355     \index{#1@{\py@idxcode{#1}}}%
356     \fi%
357     }
358     \newcommand{\withsubitem}[2]{%
359     \begingroup%
360     \def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}%
361     #2%
362     \endgroup%
363     }
364    
365    
366     % Module synopsis processing -----------------------------------------------
367     %
368     \newcommand{\py@thisclass}{}
369     \newcommand{\py@thismodule}{}
370     \newcommand{\py@thismodulekey}{}
371     \newcommand{\py@thismoduletype}{}
372    
373     \newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }}
374     \newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }}
375     \newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }}
376     \newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}}
377    
378     \newif\ifpy@HaveModSynopsis \py@HaveModSynopsisfalse
379     \newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse
380     \newif\ifpy@HaveModPlatform \py@HaveModPlatformfalse
381    
382     % \declaremodule[key]{type}{name}
383     \newcommand{\declaremodule}[3][\py@modulebadkey]{
384     \py@openModSynopsisFile
385     \renewcommand{\py@thismoduletype}{#2}
386     \ifx\py@modulebadkey#1
387     \renewcommand{\py@thismodulekey}{#3}
388     \else
389     \renewcommand{\py@thismodulekey}{#1}
390     \fi
391     \@ifundefined{py@#2IndexModule}{%
392     \typeout{*** MACRO declaremodule called with unknown module type: `#2'}
393     \py@IndexModule{#3}%
394     }{%
395     \csname py@#2IndexModule\endcsname{#3}%
396     }
397     \label{module-\py@thismodulekey}
398     }
399     \newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse
400     \newcommand{\py@ModPlatformFilename}{\jobname.pla}
401     \newcommand{\platform}[1]{
402     \ifpy@ModPlatformFileIsOpen\else
403     \newwrite\py@ModPlatformFile
404     \openout\py@ModPlatformFile=\py@ModPlatformFilename
405     \py@ModPlatformFileIsOpentrue
406     \fi
407     }
408     \InputIfFileExists{\jobname.pla}{}{}
409     \newcommand{\py@platformof}[2][\py@modulebadkey]{%
410     \ifx\py@modulebadkey#1 \def\py@key{#2}%
411     \else \def\py@key{#1}%
412     \fi%
413     \csname py@modplat@\py@key\endcsname%
414     }
415     \newcommand{\ignorePlatformAnnotation}[1]{}
416    
417     % \moduleauthor{name}{email}
418     \newcommand{\moduleauthor}[2]{}
419    
420     % \sectionauthor{name}{email}
421     \newcommand{\sectionauthor}[2]{}
422    
423    
424     \newcommand{\py@defsynopsis}{Module has no synopsis.}
425     \newcommand{\py@modulesynopsis}{\py@defsynopsis}
426     \newcommand{\modulesynopsis}[1]{
427     \py@HaveModSynopsistrue
428     \renewcommand{\py@modulesynopsis}{#1}
429     }
430    
431     % define the file
432     \newwrite\py@ModSynopsisFile
433    
434     % hacked from \addtocontents from latex.ltx:
435     \long\def\py@writeModSynopsisFile#1{%
436     \protected@write\py@ModSynopsisFile%
437     {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
438     {\string#1}%
439     }
440     \newcommand{\py@closeModSynopsisFile}{
441     \ifpy@ModSynopsisFileIsOpen
442     \closeout\py@ModSynopsisFile
443     \py@ModSynopsisFileIsOpenfalse
444     \fi
445     }
446     \newcommand{\py@openModSynopsisFile}{
447     \ifpy@ModSynopsisFileIsOpen\else
448     \openout\py@ModSynopsisFile=\py@ModSynopsisFilename
449     \py@ModSynopsisFileIsOpentrue
450     \fi
451     }
452    
453     \newcommand{\py@ProcessModSynopsis}{
454     \ifpy@HaveModSynopsis
455     \py@writeModSynopsisFile{\modulesynopsis%
456     {\py@thismodulekey}{\py@thismodule}%
457     {\py@thismoduletype}{\py@modulesynopsis}}%
458     \py@HaveModSynopsisfalse
459     \fi
460     \renewcommand{\py@modulesynopsis}{\py@defsynopsis}
461     }
462     \AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile}
463    
464    
465     \long\def\py@writeModPlatformFile#1{%
466     \protected@write\py@ModPlatformFile%
467     {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
468     {\string#1}%
469     }
470    
471    
472     \newcommand{\localmoduletable}{
473     \IfFileExists{\py@ModSynopsisFilename}{
474     \begin{synopsistable}
475     \input{\py@ModSynopsisFilename}
476     \end{synopsistable}
477     }{}
478     }
479    
480     \ifpdf
481     \newcommand{\py@ModSynopsisSummary}[4]{%
482     \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\
483     }
484     \else
485     \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}
486     \fi
487     \newenvironment{synopsistable}{
488     % key, name, type, synopsis
489     \let\modulesynopsis=\py@ModSynopsisSummary
490     \begin{tabular}{ll}
491     }{
492     \end{tabular}
493     }
494     %
495     % --------------------------------------------------------------------------
496    
497    
498     \newcommand{\py@reset}{
499     \py@usingsubitemfalse
500     \py@ProcessModSynopsis
501     \renewcommand{\py@thisclass}{}
502     \renewcommand{\py@thismodule}{}
503     \renewcommand{\py@thismodulekey}{}
504     \renewcommand{\py@thismoduletype}{}
505     }
506    
507     % Augment the sectioning commands used to get our own font family in place,
508     % and reset some internal data items:
509     \renewcommand{\section}{\py@reset%
510     \@startsection{section}{1}{\z@}%
511     {-3.5ex \@plus -1ex \@minus -.2ex}%
512     {2.3ex \@plus.2ex}%
513     {\reset@font\Large\py@HeaderFamily}}
514     \renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
515     {-3.25ex\@plus -1ex \@minus -.2ex}%
516     {1.5ex \@plus .2ex}%
517     {\reset@font\large\py@HeaderFamily}}
518     \renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}%
519     {-3.25ex\@plus -1ex \@minus -.2ex}%
520     {1.5ex \@plus .2ex}%
521     {\reset@font\normalsize\py@HeaderFamily}}
522     \renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}%
523     {3.25ex \@plus1ex \@minus.2ex}%
524     {-1em}%
525     {\reset@font\normalsize\py@HeaderFamily}}
526     \renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}%
527     {3.25ex \@plus1ex \@minus .2ex}%
528     {-1em}%
529     {\reset@font\normalsize\py@HeaderFamily}}
530    
531    
532     % This gets the underscores closer to the right width; the only change
533     % from standard LaTeX is the width specified.
534    
535     \DeclareTextCommandDefault{\textunderscore}{%
536     \leavevmode \kern.06em\vbox{\hrule\@width.55em}}
537    
538     % Underscore hack (only act like subscript operator if in math mode)
539     %
540     % The following is due to Mark Wooding (the old version didn't work with
541     % Latex 2e.
542    
543     \DeclareRobustCommand\hackscore{%
544     \ifmmode_\else\textunderscore\fi%
545     }
546     \begingroup
547     \catcode`\_\active
548     \def\next{%
549     \AtBeginDocument{\catcode`\_\active\def_{\hackscore{}}}%
550     }
551     \expandafter\endgroup\next
552    
553    
554     % Now for a lot of semantically-loaded environments that do a ton of magical
555     % things to get the right formatting and index entries for the stuff in
556     % Python modules and C API.
557    
558    
559     % {fulllineitems} is used in one place in libregex.tex, but is really for
560     % internal use in this file.
561     %
562     \newcommand{\py@itemnewline}[1]{%
563     \@tempdima\linewidth%
564     \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
565     }
566    
567     \newenvironment{fulllineitems}{
568     \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
569     \rightmargin 0pt \topsep -\parskip \partopsep \parskip
570     \itemsep -\parsep
571     \let\makelabel=\py@itemnewline}
572     }{\end{list}}
573    
574     % \optional is mostly for use in the arguments parameters to the various
575     % {*desc} environments defined below, but may be used elsewhere. Known to
576     % be used in the debugger chapter.
577     %
578     % Typical usage:
579     %
580     % \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
581     % ^^^ ^^^
582     % No space here No space here
583     %
584     % When a function has multiple optional parameters, \optional should be
585     % nested, not chained. This is right:
586     %
587     % \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
588     %
589     \let\py@badkey=\@undefined
590    
591     \newcommand{\optional}[1]{%
592     {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
593    
594     % This can be used when a function or method accepts an varying number
595     % of arguments, such as by using the *args syntax in the parameter list.
596     \newcommand{\py@moreargs}{...}
597    
598     % This can be used when you don't want to document the parameters to a
599     % function or method, but simply state that it's an alias for
600     % something else.
601     \newcommand{\py@unspecified}{...}
602    
603    
604     \newlength{\py@argswidth}
605     \newcommand{\py@sigparams}[1]{%
606     \parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}}
607     \newcommand{\py@sigline}[2]{%
608     \settowidth{\py@argswidth}{#1\code{(}}%
609     \addtolength{\py@argswidth}{-2\py@argswidth}%
610     \addtolength{\py@argswidth}{\textwidth}%
611     \item[#1\code{(}\py@sigparams{#2}]}
612    
613     % C functions ------------------------------------------------------------
614     % \begin{cfuncdesc}[refcount]{type}{name}{arglist}
615     % Note that the [refcount] slot should only be filled in by
616     % tools/anno-api.py; it pulls the value from the refcounts database.
617     \newcommand{\cfuncline}[3]{
618     \py@sigline{\code{#1 \bfcode{#2}}}{#3}%
619     \index{#2@{\py@idxcode{#2()}}}
620     }
621     \newenvironment{cfuncdesc}[4][\py@badkey]{
622     \begin{fulllineitems}
623     \cfuncline{#2}{#3}{#4}
624     \ifx#1\@undefined\else%
625     \emph{Return value: \textbf{#1}.}\\
626     \fi
627     }{\end{fulllineitems}}
628    
629     % C variables ------------------------------------------------------------
630     % \begin{cvardesc}{type}{name}
631     \newenvironment{cvardesc}[2]{
632     \begin{fulllineitems}
633     \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}]
634     }{\end{fulllineitems}}
635    
636     % C data types -----------------------------------------------------------
637     % \begin{ctypedesc}[index name]{typedef name}
638     \newenvironment{ctypedesc}[2][\py@badkey]{
639     \begin{fulllineitems}
640     \item[\bfcode{#2}%
641     \ifx#1\@undefined%
642     \index{#2@{\py@idxcode{#2}} (C type)}
643     \else%
644     \index{#2@{\py@idxcode{#1}} (C type)}
645     \fi]
646     }{\end{fulllineitems}}
647    
648     % C type fields ----------------------------------------------------------
649     % \begin{cmemberdesc}{container type}{ctype}{membername}
650     \newcommand{\cmemberline}[3]{
651     \item[\code{#2 \bfcode{#3}}]
652     \index{#3@{\py@idxcode{#3}} (#1 member)}
653     }
654     \newenvironment{cmemberdesc}[3]{
655     \begin{fulllineitems}
656     \cmemberline{#1}{#2}{#3}
657     }{\end{fulllineitems}}
658    
659     % Funky macros -----------------------------------------------------------
660     % \begin{csimplemacrodesc}{name}
661     % -- "simple" because it has no args; NOT for constant definitions!
662     \newenvironment{csimplemacrodesc}[1]{
663     \begin{fulllineitems}
664     \item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}]
665     }{\end{fulllineitems}}
666    
667     % simple functions (not methods) -----------------------------------------
668     % \begin{funcdesc}{name}{args}
669     \newcommand{\funcline}[2]{%
670     \funclineni{#1}{#2}%
671     \index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}}
672     \newenvironment{funcdesc}[2]{
673     \begin{fulllineitems}
674     \funcline{#1}{#2}
675     }{\end{fulllineitems}}
676    
677     % similar to {funcdesc}, but doesn't add to the index
678     \newcommand{\funclineni}[2]{%
679     \py@sigline{\bfcode{#1}}{#2}}
680     \newenvironment{funcdescni}[2]{
681     \begin{fulllineitems}
682     \funclineni{#1}{#2}
683     }{\end{fulllineitems}}
684    
685     % classes ----------------------------------------------------------------
686     % \begin{classdesc}{name}{constructor args}
687     \newenvironment{classdesc}[2]{
688     % Using \renewcommand doesn't work for this, for unknown reasons:
689     \global\def\py@thisclass{#1}
690     \begin{fulllineitems}
691     \py@sigline{\strong{class }\bfcode{#1}}{#2}%
692     \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}
693     }{\end{fulllineitems}}
694    
695     % \begin{classdesc*}{name}
696     \newenvironment{classdesc*}[1]{
697     % Using \renewcommand doesn't work for this, for unknown reasons:
698     \global\def\py@thisclass{#1}
699     \begin{fulllineitems}
700     \item[\strong{class }\code{\bfcode{#1}}%
701     \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]
702     }{\end{fulllineitems}}
703    
704     % \begin{excclassdesc}{name}{constructor args}
705     % but indexes as an exception
706     \newenvironment{excclassdesc}[2]{
707     % Using \renewcommand doesn't work for this, for unknown reasons:
708     \global\def\py@thisclass{#1}
709     \begin{fulllineitems}
710     \py@sigline{\strong{exception }\bfcode{#1}}{#2}%
711     \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}
712     }{\end{fulllineitems}}
713    
714     % There is no corresponding {excclassdesc*} environment. To describe
715     % a class exception without parameters, use the {excdesc} environment.
716    
717    
718     \let\py@classbadkey=\@undefined
719    
720     % object method ----------------------------------------------------------
721     % \begin{methoddesc}[classname]{methodname}{args}
722     \newcommand{\methodline}[3][\@undefined]{
723     \methodlineni{#2}{#3}
724     \ifx#1\@undefined
725     \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}
726     \else
727     \index{#2@{\py@idxcode{#2()}} (#1 method)}
728     \fi
729     }
730     \newenvironment{methoddesc}[3][\@undefined]{
731     \begin{fulllineitems}
732     \ifx#1\@undefined
733     \methodline{#2}{#3}
734     \else
735     \def\py@thisclass{#1}
736     \methodline{#2}{#3}
737     \fi
738     }{\end{fulllineitems}}
739    
740     % similar to {methoddesc}, but doesn't add to the index
741     % (never actually uses the optional argument)
742     \newcommand{\methodlineni}[3][\py@classbadkey]{%
743     \py@sigline{\bfcode{#2}}{#3}}
744     \newenvironment{methoddescni}[3][\py@classbadkey]{
745     \begin{fulllineitems}
746     \methodlineni{#2}{#3}
747     }{\end{fulllineitems}}
748    
749     % object data attribute --------------------------------------------------
750     % \begin{memberdesc}[classname]{membername}
751     \newcommand{\memberline}[2][\py@classbadkey]{%
752     \ifx#1\@undefined
753     \memberlineni{#2}
754     \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}
755     \else
756     \memberlineni{#2}
757     \index{#2@{\py@idxcode{#2}} (#1 attribute)}
758     \fi
759     }
760     \newenvironment{memberdesc}[2][\py@classbadkey]{
761     \begin{fulllineitems}
762     \ifx#1\@undefined
763     \memberline{#2}
764     \else
765     \def\py@thisclass{#1}
766     \memberline{#2}
767     \fi
768     }{\end{fulllineitems}}
769    
770     % similar to {memberdesc}, but doesn't add to the index
771     % (never actually uses the optional argument)
772     \newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}
773     \newenvironment{memberdescni}[2][\py@classbadkey]{
774     \begin{fulllineitems}
775     \memberlineni{#2}
776     }{\end{fulllineitems}}
777    
778     % For exceptions: --------------------------------------------------------
779     % \begin{excdesc}{name}
780     % -- for constructor information, use excclassdesc instead
781     \newenvironment{excdesc}[1]{
782     \begin{fulllineitems}
783     \item[\strong{exception }\bfcode{#1}%
784     \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
785     }{\end{fulllineitems}}
786    
787     % Module data or constants: ----------------------------------------------
788     % \begin{datadesc}{name}
789     \newcommand{\dataline}[1]{%
790     \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}
791     \newenvironment{datadesc}[1]{
792     \begin{fulllineitems}
793     \dataline{#1}
794     }{\end{fulllineitems}}
795    
796     % similar to {datadesc}, but doesn't add to the index
797     \newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
798     \newenvironment{datadescni}[1]{
799     \begin{fulllineitems}
800     \datalineni{#1}
801     }{\end{fulllineitems}}
802    
803     % bytecode instruction ---------------------------------------------------
804     % \begin{opcodedesc}{name}{var}
805     % -- {var} may be {}
806     \newenvironment{opcodedesc}[2]{
807     \begin{fulllineitems}
808     \item[\bfcode{#1}\quad\var{#2}]
809     }{\end{fulllineitems}}
810    
811    
812     \newcommand{\nodename}[1]{\label{#1}}
813    
814     % For these commands, use \command{} to get the typography right, not
815     % {\command}. This works better with the texinfo translation.
816     \newcommand{\ABC}{{\sc abc}}
817     \newcommand{\UNIX}{{\sc Unix}}
818     \newcommand{\POSIX}{POSIX}
819     \newcommand{\ASCII}{{\sc ascii}}
820     \newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
821     \newcommand{\C}{C}
822     \newcommand{\EOF}{{\sc eof}}
823     \newcommand{\NULL}{\constant{NULL}}
824     \newcommand{\infinity}{\ensuremath{\infty}}
825     \newcommand{\plusminus}{\ensuremath{\pm}}
826     % \menuselection{Start \sub Programs \sub Python}
827     \newcommand{\menuselection}[1]{\textsf{\def\sub{ \ensuremath{>} }#1}}
828    
829     % Also for consistency: spell Python "Python", not "python"!
830    
831     % code is the most difficult one...
832     \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`\%}%
833     \texttt{#1}}}
834    
835     \newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
836     \newcommand{\csimplemacro}[1]{\code{#1}}
837     \newcommand{\kbd}[1]{\code{#1}}
838     \newcommand{\samp}[1]{`\code{#1}'}
839     \newcommand{\var}[1]{%
840     \ifmmode%
841     \hbox{\py@defaultsize\textrm{\textit{#1\/}}}%
842     \else%
843     \py@defaultsize\textrm{\textit{#1\/}}%
844     \fi%
845     }
846     \renewcommand{\emph}[1]{{\em #1}}
847     \newcommand{\dfn}[1]{\emph{#1}}
848     \newcommand{\strong}[1]{{\bf #1}}
849     % let's experiment with a new font:
850     \newcommand{\file}[1]{`\filenq{#1}'}
851     \newcommand{\filenq}[1]{{\py@smallsize\textsf{#1}}}
852    
853     % Use this def/redef approach for \url{} since hyperref defined this already,
854     % but only if we actually used hyperref:
855     \ifpdf
856     \newcommand{\url}[1]{{%
857     \noindent%
858     \pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
859     \py@LinkColor% color of the link text
860     \py@smallsize\sf #1%
861     \py@NormalColor% Turn it back off; these are declarative
862     \pdfendlink}% and don't appear bound to the current
863     }% formatting "box".
864     \else
865     \newcommand{\url}[1]{\mbox{\py@smallsize\textsf{#1}}}
866     \fi
867     \newcommand{\email}[1]{{\py@smallsize\textsf{#1}}}
868     \newcommand{\newsgroup}[1]{{\py@smallsize\textsf{#1}}}
869    
870     \newcommand{\py@varvars}[1]{{%
871     {\let\unspecified=\py@unspecified%
872     \let\moreargs=\py@moreargs%
873     \var{#1}}}}
874    
875     % I'd really like to get rid of this!
876     \newif\iftexi\texifalse
877    
878     % This is used to get l2h to put the copyright and abstract on
879     % a separate HTML page.
880     \newif\ifhtml\htmlfalse
881    
882    
883     % These should be used for all references to identifiers which are
884     % used to refer to instances of specific language constructs. See the
885     % names for specific semantic assignments.
886     %
887     % For now, don't do anything really fancy with them; just use them as
888     % logical markup. This might change in the future.
889     %
890     \newcommand{\module}[1]{\texttt{#1}}
891     \newcommand{\keyword}[1]{\texttt{#1}}
892     \newcommand{\exception}[1]{\texttt{#1}}
893     \newcommand{\class}[1]{\texttt{#1}}
894     \newcommand{\function}[1]{\texttt{#1}}
895     \newcommand{\member}[1]{\texttt{#1}}
896     \newcommand{\method}[1]{\texttt{#1}}
897    
898     \newcommand{\pytype}[1]{#1} % built-in Python type
899    
900     \newcommand{\cfunction}[1]{\texttt{#1}}
901     \newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name
902     \newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global
903    
904     \newcommand{\mailheader}[1]{{\py@smallsize\textsf{#1:}}}
905     \newcommand{\mimetype}[1]{{\py@smallsize\textsf{#1}}}
906     % The \! is a "negative thin space" in math mode.
907     \newcommand{\regexp}[1]{%
908     {\tiny$^{^\lceil}\!\!$%
909     {\py@defaultsize\code{#1}}%
910     $\!\rfloor\!$%
911     }}
912     \newcommand{\envvar}[1]{%
913     #1%
914     \index{#1}%
915     \index{environment variables!{#1}}%
916     }
917     \newcommand{\makevar}[1]{#1} % variable in a Makefile
918     \newcommand{\character}[1]{\samp{#1}}
919    
920     % constants defined in Python modules or C headers, not language constants:
921     \newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic
922    
923     \newcommand{\manpage}[2]{{\emph{#1}(#2)}}
924     \newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}
925     \newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
926     \newcommand{\program}[1]{\strong{#1}}
927     \newcommand{\programopt}[1]{\strong{#1}}
928     % Note that \longprogramopt provides the '--'!
929     \newcommand{\longprogramopt}[1]{\strong{-{}-#1}}
930    
931     % \ulink{link text}{URL}
932     \ifpdf
933     % The \noindent here is a hack -- we're forcing pdfTeX into
934     % horizontal mode since \pdfstartlink requires that.
935     \newcommand{\ulink}[2]{\noindent{%
936     \pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#2)}%
937     \py@LinkColor% color of the link text
938     #1%
939     \py@NormalColor% Turn it back off; these are declarative
940     \pdfendlink}% and don't appear bound to the current
941     }% formatting "box".
942     \else
943     \newcommand{\ulink}[2]{#1}
944     \fi
945    
946     % cited titles: \citetitle{Title of Work}
947     % online: \citetitle[url-to-resource]{Title of Work}
948     \ifpdf
949     \newcommand{\citetitle}[2][\py@modulebadkey]{%
950     \ifx\py@modulebadkey#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi%
951     }
952     \else
953     \newcommand{\citetitle}[2][URL]{\emph{#2}}
954     \fi
955    
956    
957    
958     % This version is being checked in for the historical record; it shows
959     % how I've managed to get some aspects of this to work. It will not
960     % be used in practice, so a subsequent revision will change things
961     % again. This version has problems, but shows how to do something
962     % that proved more tedious than I'd expected, so I don't want to lose
963     % the example completely.
964     %
965     \newcommand{\grammartoken}[1]{\texttt{#1}}
966     \newenvironment{productionlist}[1][\py@badkey]{
967     \def\optional##1{{\Large[}##1{\Large]}}
968     \def\production##1##2{\code{##1}&::=&\code{##2}\\}
969     \def\productioncont##1{& &\code{##1}\\}
970     \def\token##1{##1}
971     \let\grammartoken=\token
972     \parindent=2em
973     \indent
974     \begin{tabular}{lcl}
975     }{%
976     \end{tabular}
977     }
978    
979     \newcommand{\py@noticelabel@note}{Note:}
980     \newcommand{\py@noticelabel@warning}{Warning:}
981     \newenvironment{notice}[1][note]{
982     \par\strong{\csname py@noticelabel@#1\endcsname}
983     }{}
984     \newcommand{\note}[1]{\strong{\py@noticelabel@note} #1}
985     \newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1}
986    
987     % Deprecation stuff.
988     % Should be extended to allow an index / list of deprecated stuff. But
989     % there's a lot of stuff that needs to be done to make that automatable.
990     %
991     % First parameter is the release number that deprecates the feature, the
992     % second is the action the should be taken by users of the feature.
993     %
994     % Example:
995     % \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
996     %
997     \newcommand{\deprecated}[2]{%
998     \strong{Deprecated since release #1.} #2\par}
999    
1000     % New stuff.
1001     % This should be used to mark things which have been added to the
1002     % development tree but that aren't in the release, but are documented.
1003     % This allows release of documentation that already includes updated
1004     % descriptions. Place at end of descriptor environment.
1005     %
1006     % Example:
1007     % \versionadded{1.5.2}
1008     % \versionchanged[short explanation]{2.0}
1009     %
1010     \newcommand{\versionadded}[2][\py@badkey]{%
1011     \ifx#1\@undefined%
1012     { New in version #2. }%
1013     \else%
1014     { New in version #2:\ #1. }%
1015     \fi%
1016     }
1017     \newcommand{\versionchanged}[2][\py@badkey]{%
1018     \ifx#1\@undefined%
1019     { Changed in version #2. }%
1020     \else%
1021     { Changed in version #2:\ #1. }%
1022     \fi%
1023     }
1024    
1025    
1026     % Tables.
1027     %
1028     \newenvironment{tableii}[4]{%
1029     \begin{center}%
1030     \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
1031     \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline%
1032     }{%
1033     \end{tabular}%
1034     \end{center}%
1035     }
1036    
1037     \newenvironment{longtableii}[4]{%
1038     \begin{center}%
1039     \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
1040     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead%
1041     }{%
1042     \end{longtable}%
1043     \end{center}%
1044     }
1045    
1046     \newenvironment{tableiii}[5]{%
1047     \begin{center}%
1048     \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
1049     \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
1050     \hline%
1051     }{%
1052     \end{tabular}%
1053     \end{center}%
1054     }
1055    
1056     \newenvironment{longtableiii}[5]{%
1057     \begin{center}%
1058     \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
1059     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
1060     \hline\endhead%
1061     }{%
1062     \end{longtable}%
1063     \end{center}%
1064     }
1065    
1066     \newenvironment{tableiv}[6]{%
1067     \begin{center}%
1068     \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
1069     \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\%
1070     \hline%
1071     }{%
1072     \end{tabular}%
1073     \end{center}%
1074     }
1075    
1076     \newenvironment{longtableiv}[6]{%
1077     \begin{center}%
1078     \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
1079     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}%
1080     \\%
1081     \hline\endhead%
1082     }{%
1083     \end{longtable}%
1084     \end{center}%
1085     }
1086    
1087     \newenvironment{tablev}[7]{%
1088     \begin{center}%
1089     \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
1090     \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7} \\%
1091     \hline%
1092     }{%
1093     \end{tabular}%
1094     \end{center}%
1095     }
1096    
1097     \newenvironment{longtablev}[7]{%
1098     \begin{center}%
1099     \def\linev##1##2##3##4##5{\csname#2\endcsname{##1}&##2&##3&##4&##5\\}%
1100     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}&\strong{#7}%
1101     \\%
1102     \hline\endhead%
1103     }{%
1104     \end{longtable}%
1105     \end{center}%
1106     }
1107    
1108     % XXX Don't think we can use this yet, though it cleans up some
1109     % tedious markup. There's no equivalent for the HTML transform yet,
1110     % and that needs to exist. I don't know how to write it.
1111     %
1112     % This should really have something that makes it easier to bind a
1113     % table's ``Notes'' column and an associated tablenotes environment,
1114     % and generates the right magic for getting the numbers right in the
1115     % table.
1116     %
1117     % So this is quite incomplete.
1118     %
1119     \newcounter{py@tablenotescounter}
1120     \newenvironment{tablenotes}{%
1121     \noindent Notes:
1122     \par
1123     \setcounter{py@tablenotescounter}{0}
1124     \begin{list}{(\arabic{py@tablenotescounter})}%
1125     {\usecounter{py@tablenotescounter}}
1126     }{\end{list}}
1127    
1128    
1129     % Cross-referencing (AMK, new impl. FLD)
1130     % Sample usage:
1131     % \begin{seealso}
1132     % \seemodule{rand}{Uniform random number generator.}; % Module xref
1133     % \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book
1134     %
1135     % % A funky case: module name contains '_'; have to supply an optional key
1136     % \seemodule[copyreg]{copy_reg}{Interface constructor registration for
1137     % \module{pickle}.}
1138     % \end{seealso}
1139     %
1140     % Note that the last parameter for \seemodule and \seetext should be complete
1141     % sentences and be terminated with the proper punctuation.
1142    
1143     \ifpdf
1144     \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
1145     \par%
1146     \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
1147     \begin{fulllineitems}
1148     \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}}
1149     (section \ref{module-\py@modulekey}):]
1150     #3
1151     \end{fulllineitems}
1152     }
1153     \else
1154     \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
1155     \par%
1156     \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
1157     \begin{fulllineitems}
1158     \item[Module \module{#2} (section \ref{module-\py@modulekey}):]
1159     #3
1160     \end{fulllineitems}
1161     }
1162     \fi
1163    
1164     % \seetitle[url]{title}{why it's interesting}
1165     \newcommand{\py@seetitle}[3][\py@modulebadkey]{%
1166     \par
1167     \begin{fulllineitems}
1168     \item[\citetitle{#2}]
1169     \ifx\py@modulebadkey#1\else
1170     \item[{\small{(\url{#1})}}]
1171     \fi
1172     #3
1173     \end{fulllineitems}
1174     }
1175     % \seepep{number}{title}{why it's interesting}
1176     \newcommand{\py@seepep}[3]{%
1177     \par%
1178     \begin{fulllineitems}
1179     \item[\pep{#1}, ``\emph{#2}'']
1180     #3
1181     \end{fulllineitems}
1182     }
1183     % \seerfc{number}{title}{why it's interesting}
1184     \newcommand{\py@seerfc}[3]{%
1185     \par%
1186     \begin{fulllineitems}
1187     \item[\rfc{#1}, ``\emph{#2}'']
1188     #3
1189     \end{fulllineitems}
1190     }
1191     % \seeurl{url}{why it's interesting}
1192     \newcommand{\py@seeurl}[2]{%
1193     \par%
1194     \begin{fulllineitems}
1195     \item[\url{#1}]
1196     #2
1197     \end{fulllineitems}
1198     }
1199    
1200     \newenvironment{seealso*}{
1201     \par
1202     \def\seetext##1{\par{##1}}
1203     \let\seemodule=\py@seemodule
1204     \let\seepep=\py@seepep
1205     \let\seerfc=\py@seerfc
1206     \let\seetitle=\py@seetitle
1207     \let\seeurl=\py@seeurl
1208     }{\par}
1209     \newenvironment{seealso}{
1210     \par
1211     \strong{See Also:}
1212     \par
1213     \def\seetext##1{\par{##1}}
1214     \let\seemodule=\py@seemodule
1215     \let\seepep=\py@seepep
1216     \let\seerfc=\py@seerfc
1217     \let\seetitle=\py@seetitle
1218     \let\seeurl=\py@seeurl
1219     }{\par}
1220    
1221     % Allow the Python release number to be specified independently of the
1222     % \date{}. This allows the date to reflect the document's date and
1223     % release to specify the Python release that is documented.
1224     %
1225     \newcommand{\py@release}{}
1226     \newcommand{\version}{}
1227     \newcommand{\shortversion}{}
1228     \newcommand{\releaseinfo}{}
1229     \newcommand{\releasename}{Release}
1230     \newcommand{\release}[1]{%
1231     \renewcommand{\py@release}{\releasename\space\version}%
1232     \renewcommand{\version}{#1}}
1233     \newcommand{\setshortversion}[1]{%
1234     \renewcommand{\shortversion}{#1}}
1235     \newcommand{\setreleaseinfo}[1]{%
1236     \renewcommand{\releaseinfo}{#1}}
1237    
1238     % Allow specification of the author's address separately from the
1239     % author's name. This can be used to format them differently, which
1240     % is a good thing.
1241     %
1242     \newcommand{\py@authoraddress}{}
1243     \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
1244     \let\developersaddress=\authoraddress
1245     \let\developer=\author
1246     \let\developers=\author
1247    
1248     % This sets up the fancy chapter headings that make the documents look
1249     % at least a little better than the usual LaTeX output.
1250     %
1251     \@ifundefined{ChTitleVar}{}{
1252     \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
1253     \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
1254     \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
1255     % This creates chapter heads without the leading \vspace*{}:
1256     \def\@makechapterhead#1{%
1257     {\parindent \z@ \raggedright \normalfont
1258     \ifnum \c@secnumdepth >\m@ne
1259     \DOCH
1260     \fi
1261     \interlinepenalty\@M
1262     \DOTI{#1}
1263     }
1264     }
1265     }
1266    
1267    
1268     % Definition lists; requested by AMK for HOWTO documents. Probably useful
1269     % elsewhere as well, so keep in in the general style support.
1270     %
1271     \newenvironment{definitions}{%
1272     \begin{description}%
1273     \def\term##1{\item[##1]\mbox{}\\*[0mm]}
1274     }{%
1275     \end{description}%
1276     }
1277    
1278     % Tell TeX about pathological hyphenation cases:
1279     \hyphenation{Base-HTTP-Re-quest-Hand-ler}

  ViewVC Help
Powered by ViewVC 1.1.26