2 % python.sty for the Python docummentation [works only with Latex2e]
5 \NeedsTeXFormat{LaTeX2e
}[1995/
12/
01]
6 \ProvidesPackage{python
}
7 [1998/
01/
11 LaTeX package (Python markup)
]
9 \RequirePackage{longtable
}
10 \RequirePackage{underscore
}
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''
18 % These packages can be used to add marginal annotations which indicate
19 % index entries and labels; useful for reviewing this messy documentation!
21 %\RequirePackage{showkeys}
22 %\RequirePackage{showidx}
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
27 \let\py@parindent=
\noindent
29 % for PDF output, use maximal compression & a lot of other stuff
30 % (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)
32 \newif\ifpy@doing@page@targets
33 \py@doing@page@targetsfalse
36 \ifx\pdfoutput\undefined\else\ifcase\pdfoutput
40 \let\py@LinkColor=
\NavyBlue
41 \let\py@NormalColor=
\Black
43 \pdfpagewidth=
\paperwidth % page width of PDF output
44 \pdfpageheight=
\paperheight % page height of PDF output
46 % Pad the number with '0' to 3 digits wide so no page name is a prefix
49 \newcommand{\py@targetno
}[1]{\ifnum#1<
100 0\fi\ifnum#1<
10 0\fi#1}
50 \newcommand{\py@pageno
}{\py@targetno
\thepage}
52 % This definition allows the entries in the page-view of the ToC to be
53 % active links. Some work, some don't.
55 \let\py@OldContentsline=
\contentsline
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.
61 \@ifundefined
{pdfstartlink
}{
62 \let\pdfstartlink=
\pdfannotlink
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%
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
76 \newcommand{\py@linkToName
}[2]{%
77 \py@pdfstartlink attr
{/Border
[0 0 0]} goto name
{#1}%
78 \py@LinkColor
#2\py@NormalColor
%
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}%
89 \InputIfFileExists{\jobname.bkm
}{\pdfcatalog{/PageMode /UseOutlines
}}{}
91 \newcommand{\py@target
}[1]{%
92 \ifpy@doing@page@targets
%
93 {\pdfdest name
{#1} xyz
}%
96 \let\py@OldLabel=
\label
97 \renewcommand{\label}[1]{%
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.
105 % This is *heavily* based on the hyperref package.
108 \unvbox \@begindvibox
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
}%
120 % Increase printable page size (copied from fullpage.sty)
122 \advance \topmargin by -
\headheight
123 \advance \topmargin by -
\headsep
125 % attempt to work a little better for A4 users
126 \textheight \paperheight
127 \advance\textheight by -
2in
131 %\evensidemargin -.25in % for ``manual size'' documents
132 \marginparwidth 0.5in
134 \textwidth \paperwidth
135 \advance\textwidth by -
2in
138 % Style parameters and macros used by most documents here
143 \hbadness =
5000 % don't print trivial gripes
145 \pagestyle{empty
} % start this way; change for
146 \pagenumbering{roman
} % ToC & chapters
148 % Use this to set the font family for headers and other decor:
149 \newcommand{\py@HeaderFamily
}{\sffamily}
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
158 \py@oldmakefntext
{#1}%
161 \def\py@defaultsize
{%
162 \ifpy@infootnote
\footnotesize\else\normalsize\fi%
165 \ifpy@infootnote
\scriptsize\else\small\fi%
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
}{
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
}
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
}{
184 \fancyfoot[LE,RO
]{{\py@HeaderFamily
\thepage}}
185 \renewcommand{\headrulewidth}{0pt
}
186 \renewcommand{\footrulewidth}{0.4pt
}
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
195 \thispagestyle{plain
}
197 \if@twocolumn
\hbox{}\newpage\fi\fi\fi
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
206 \let\py@OldVerbatim=
\verbatim
207 \let\py@OldEndVerbatim=
\endverbatim
208 \RequirePackage{verbatim
}
209 \let\py@OldVerbatimInput=
\verbatiminput
211 % Variable used by begin code command
212 \newlength{\py@codewidth
}
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}%
221 \begin{minipage
}[t
]{\py@codewidth
}%
225 \renewcommand{\endverbatim}{%
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}%
236 \begin{list
}{}{\setlength{\leftmargin}{1cm
}}
238 \py@OldVerbatimInput
{#1}%
243 % This does a similar thing for the {alltt} environment:
244 \RequirePackage{alltt}
245 \let\py@OldAllTT=
\alltt
246 \let\py@OldEndAllTT=
\endalltt
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%
256 \begin{minipage
}[t
]{\py@codewidth
}%
260 \renewcommand{\endalltt}{%
266 \newcommand{\py@modulebadkey
}{{--just-some-junk--
}}
269 %% Lots of index-entry generation support.
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.
276 \newcommand{\py@idxcode
}[1]{\texttt{#1}}
277 %\renewcommand{\py@idxcode}[1]{#1}
279 % Command to generate two index entries (using subentries)
280 \newcommand{\indexii}[2]{\index{#1!
#2}\index{#2!
#1}}
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}}
285 % And four (again, using only one level of subentries)
286 \newcommand{\indexiv}[4]{
293 % Command to generate a reference to a function, statement, keyword,
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)
}}
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
}}
310 % Refer to a module's documentation using a hyperlink of the module's
311 % name, at least if we're building PDF:
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}}%
318 \newcommand{\refmodule}[2][\py@modulebadkey
]{\module{#2}}
321 % support for the module index
322 \newif\ifpy@UseModuleIndex
323 \py@UseModuleIndexfalse
325 \newcommand{\makemodindex}{
326 \newwrite\modindexfile
327 \openout\modindexfile=mod
\jobname.idx
328 \py@UseModuleIndextrue
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}}%
345 % *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***
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!
}}
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!
}}
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]{%
366 \index{#1@
{\py@idxcode
{#1}}\py@indexsubitem
}%
368 \index{#1@
{\py@idxcode
{#1}}}%
371 \newcommand{\withsubitem}[2]{%
373 \def\ttindex#
#1{\index{#
#1@
{\py@idxcode
{#
#1}} #1}}%
379 % Module synopsis processing -----------------------------------------------
381 \newcommand{\py@thisclass
}{}
382 \newcommand{\py@thismodule
}{}
383 \newcommand{\py@thismodulekey
}{}
384 \newcommand{\py@thismoduletype
}{}
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}{}}
391 \newif\ifpy@HaveModSynopsis
\py@HaveModSynopsisfalse
392 \newif\ifpy@ModSynopsisFileIsOpen
\py@ModSynopsisFileIsOpenfalse
393 \newif\ifpy@HaveModPlatform
\py@HaveModPlatformfalse
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}
402 \renewcommand{\py@thismodulekey
}{#1}
404 \@ifundefined
{py@
#2IndexModule
}{%
405 \typeout{*** MACRO declaremodule called with unknown module type: `
#2'
}
408 \csname py@
#2IndexModule
\endcsname{#3}%
410 \label{module-
\py@thismodulekey
}
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
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}%
426 \csname py@modplat@
\py@key
\endcsname%
428 \newcommand{\ignorePlatformAnnotation}[1]{}
430 % \moduleauthor{name}{email}
431 \newcommand{\moduleauthor}[2]{}
433 % \sectionauthor{name}{email}
434 \newcommand{\sectionauthor}[2]{}
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}
445 \newwrite\py@ModSynopsisFile
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
}%
453 \newcommand{\py@closeModSynopsisFile
}{
454 \ifpy@ModSynopsisFileIsOpen
455 \closeout\py@ModSynopsisFile
456 \py@ModSynopsisFileIsOpenfalse
459 \newcommand{\py@openModSynopsisFile
}{
460 \ifpy@ModSynopsisFileIsOpen
\else
461 \openout\py@ModSynopsisFile=
\py@ModSynopsisFilename
462 \py@ModSynopsisFileIsOpentrue
466 \newcommand{\py@ProcessModSynopsis
}{
467 \ifpy@HaveModSynopsis
468 \py@writeModSynopsisFile
{\modulesynopsis%
469 {\py@thismodulekey
}{\py@thismodule
}%
470 {\py@thismoduletype
}{\py@modulesynopsis
}}%
471 \py@HaveModSynopsisfalse
473 \renewcommand{\py@modulesynopsis
}{\py@defsynopsis
}
475 \AtEndDocument{\py@ProcessModSynopsis
\py@closeModSynopsisFile
}
478 \long\def\py@writeModPlatformFile
#1{%
479 \protected@write
\py@ModPlatformFile
%
480 {\let\label\@gobble
\let\index\@gobble
\let\glossary\@gobble
}%
485 \newcommand{\localmoduletable}{
486 \IfFileExists{\py@ModSynopsisFilename
}{
487 \begin{synopsistable
}
488 \input{\py@ModSynopsisFilename
}
494 \newcommand{\py@ModSynopsisSummary
}[4]{%
495 \py@linkToName
{label-module-
#1}{\bfcode{#2}} &
#4\\
498 \newcommand{\py@ModSynopsisSummary
}[4]{\bfcode{#2} &
#4\\
}
500 \newenvironment{synopsistable
}{
501 % key, name, type, synopsis
502 \let\modulesynopsis=
\py@ModSynopsisSummary
508 % --------------------------------------------------------------------------
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
}{}
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
}%
526 {\reset@font
\Large\py@HeaderFamily
}}
527 \renewcommand{\subsection}{\@startsection
{subsection
}{2}{\z@
}%
528 {-
3.25ex\@plus -
1ex \@minus -
.2ex
}%
530 {\reset@font
\large\py@HeaderFamily
}}
531 \renewcommand{\subsubsection}{\@startsection
{subsubsection
}{3}{\z@
}%
532 {-
3.25ex\@plus -
1ex \@minus -
.2ex
}%
534 {\reset@font
\normalsize\py@HeaderFamily
}}
535 \renewcommand{\paragraph}{\@startsection
{paragraph
}{4}{\z@
}%
536 {3.25ex \@plus1ex \@minus
.2ex
}%
538 {\reset@font
\normalsize\py@HeaderFamily
}}
539 \renewcommand{\subparagraph}{\@startsection
{subparagraph
}{5}{\parindent}%
540 {3.25ex \@plus1ex \@minus
.2ex
}%
542 {\reset@font
\normalsize\py@HeaderFamily
}}
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.
550 % {fulllineitems} is used in one place in libregex.tex, but is really for
551 % internal use in this file.
553 \newcommand{\py@itemnewline
}[1]{%
554 \@tempdima
\linewidth%
555 \advance\@tempdima
\leftmargin\makebox[\@tempdima
][l
]{#1}%
558 \newenvironment{fulllineitems
}{
559 \begin{list
}{}{\labelwidth \leftmargin \labelsep 0pt
560 \rightmargin 0pt
\topsep -
\parskip \partopsep \parskip
562 \let\makelabel=
\py@itemnewline
}
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.
571 % \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
573 % No space here No space here
575 % When a function has multiple optional parameters, \optional should be
576 % nested, not chained. This is right:
578 % \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
580 \let\py@badkey=\@undefined
582 \newcommand{\optional}[1]{%
583 {\textnormal{\Large[}}{#1}\hspace{0.5mm
}{\textnormal{\Large]}}}
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
}{...
}
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
592 \newcommand{\py@unspecified
}{...
}
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}]}
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()
}}}
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}.
}\\
618 }{\end{fulllineitems
}}
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
}}
627 % C data types -----------------------------------------------------------
628 % \begin{ctypedesc}[index name]{typedef name}
629 \newenvironment{ctypedesc
}[2][\py@badkey
]{
630 \begin{fulllineitems
}
633 \index{#2@
{\py@idxcode
{#2}} (C type)
}
635 \index{#2@
{\py@idxcode
{#1}} (C type)
}
637 }{\end{fulllineitems
}}
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)
}
645 \newenvironment{cmemberdesc
}[3]{
646 \begin{fulllineitems
}
647 \cmemberline{#1}{#2}{#3}
648 }{\end{fulllineitems
}}
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
}}
658 % simple functions (not methods) -----------------------------------------
659 % \begin{funcdesc}{name}{args}
660 \newcommand{\funcline}[2]{%
662 \index{#1@
{\py@idxcode
{#1()
}} (in module
\py@thismodule)
}}
663 \newenvironment{funcdesc
}[2]{
664 \begin{fulllineitems
}
666 }{\end{fulllineitems
}}
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
}
674 }{\end{fulllineitems
}}
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
}}
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
}}
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
}}
705 % There is no corresponding {excclassdesc*} environment. To describe
706 % a class exception without parameters, use the {excdesc} environment.
709 \let\py@classbadkey=\@undefined
711 % object method ----------------------------------------------------------
712 % \begin{methoddesc}[classname]{methodname}{args}
713 \newcommand{\methodline}[3][\@undefined
]{
714 \methodlineni{#2}{#3}
716 \index{#2@
{\py@idxcode
{#2()
}} (
\py@thisclass\ method)
}
718 \index{#2@
{\py@idxcode
{#2()
}} (
#1 method)
}
721 \newenvironment{methoddesc
}[3][\@undefined
]{
722 \begin{fulllineitems
}
726 \def\py@thisclass
{#1}
729 }{\end{fulllineitems
}}
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
}}
740 % object data attribute --------------------------------------------------
741 % \begin{memberdesc}[classname]{membername}
742 \newcommand{\memberline}[2][\py@classbadkey
]{%
745 \index{#2@
{\py@idxcode
{#2}} (
\py@thisclass\ attribute)
}
748 \index{#2@
{\py@idxcode
{#2}} (
#1 attribute)
}
751 \newenvironment{memberdesc
}[2][\py@classbadkey
]{
752 \begin{fulllineitems
}
756 \def\py@thisclass
{#1}
759 }{\end{fulllineitems
}}
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
}
767 }{\end{fulllineitems
}}
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
}}
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
}
785 }{\end{fulllineitems
}}
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
}
792 }{\end{fulllineitems
}}
794 % bytecode instruction ---------------------------------------------------
795 % \begin{opcodedesc}{name}{var}
797 \newenvironment{opcodedesc
}[2]{
798 \begin{fulllineitems
}
799 \item[\bfcode{#1}\quad\var{#2}]
800 }{\end{fulllineitems
}}
803 \newcommand{\nodename}[1]{\label{#1}}
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
}{++
}}
813 \newcommand{\EOF}{{\sc eof
}}
814 \newcommand{\NULL}{\constant{NULL
}}
815 \newcommand{\infinity}{\ensuremath{\infty}}
816 \newcommand{\plusminus}{\ensuremath{\pm}}
819 \newcommand{\guilabel}[1]{\textsf{#1}}
820 % \menuselection{Start \sub Programs \sub Python}
821 \newcommand{\menuselection}[1]{\guilabel{{\def\sub{ \ensuremath{>
} }#1}}}
823 % Also for consistency: spell Python "Python", not "python"!
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`\%
}%
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]{%
835 \hbox{\py@defaultsize
\textrm{\textit{#1\/
}}}%
837 \py@defaultsize
\textrm{\textit{#1\/
}}%
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}}}
847 % Use this def/redef approach for \url{} since hyperref defined this already,
848 % but only if we actually used hyperref:
850 \newcommand{\url}[1]{{%
852 attr
{ /Border
[0 0 0] }%
861 \py@LinkColor
% color of the link text
863 \py@NormalColor
% Turn it back off; these are declarative
864 \pdfendlink}% and don't appear bound to the current
867 \newcommand{\url}[1]{\mbox{\py@smallsize
\textsf{#1}}}
869 \newcommand{\email}[1]{{\py@smallsize
\textsf{#1}}}
870 \newcommand{\newsgroup}[1]{{\py@smallsize
\textsf{#1}}}
872 \newcommand{\py@varvars
}[1]{{%
873 {\let\unspecified=
\py@unspecified
%
874 \let\moreargs=
\py@moreargs
%
877 % I'd really like to get rid of this!
878 \newif\iftexi\texifalse
880 % This is used to get l2h to put the copyright and abstract on
881 % a separate HTML page.
882 \newif\ifhtml\htmlfalse
885 % These should be used for all references to identifiers which are
886 % used to refer to instances of specific language constructs. See the
887 % names for specific semantic assignments.
889 % For now, don't do anything really fancy with them; just use them as
890 % logical markup. This might change in the future.
892 \newcommand{\module}[1]{\texttt{#1}}
893 \newcommand{\keyword}[1]{\texttt{#1}}
894 \newcommand{\exception}[1]{\texttt{#1}}
895 \newcommand{\class}[1]{\texttt{#1}}
896 \newcommand{\function}[1]{\texttt{#1}}
897 \newcommand{\member}[1]{\texttt{#1}}
898 \newcommand{\method}[1]{\texttt{#1}}
900 \newcommand{\pytype}[1]{#1} % built-in Python type
902 \newcommand{\cfunction}[1]{\texttt{#1}}
903 \newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name
904 \newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global
906 \newcommand{\mailheader}[1]{{\py@smallsize
\textsf{#1:
}}}
907 \newcommand{\mimetype}[1]{{\py@smallsize
\textsf{#1}}}
908 % The \! is a "negative thin space" in math mode.
909 \newcommand{\regexp}[1]{%
910 {\tiny$^
{^
\lceil}\!\!$
%
911 {\py@defaultsize
\code{#1}}%
914 \newcommand{\envvar}[1]{%
917 \index{environment variables!
{#1}}%
919 \newcommand{\makevar}[1]{#1} % variable in a Makefile
920 \newcommand{\character}[1]{\samp{#1}}
922 % constants defined in Python modules or C headers, not language constants:
923 \newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic
925 \newcommand{\manpage}[2]{{\emph{#1}(
#2)
}}
926 \newcommand{\pep}[1]{PEP
#1\index{Python Enhancement Proposals!PEP
#1}}
927 \newcommand{\rfc}[1]{RFC
#1\index{RFC!RFC
#1}}
928 \newcommand{\program}[1]{\strong{#1}}
929 \newcommand{\programopt}[1]{\strong{#1}}
930 % Note that \longprogramopt provides the '--'!
931 \newcommand{\longprogramopt}[1]{\strong{-
{}-
#1}}
933 % \ulink{link text}{URL}
935 \newcommand{\ulink}[2]{{%
936 % For PDF, we *should* only generate a link when the URL is absolute.
938 attr
{ /Border
[0 0 0] }%
947 \py@LinkColor
% color of the link text
949 \py@NormalColor
% Turn it back off; these are declarative
950 \pdfendlink}% and don't appear bound to the current
953 \newcommand{\ulink}[2]{#1}
956 % cited titles: \citetitle{Title of Work}
957 % online: \citetitle[url-to-resource]{Title of Work}
959 \newcommand{\citetitle}[2][\py@modulebadkey
]{%
960 \ifx\py@modulebadkey
#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi%
963 \newcommand{\citetitle}[2][URL
]{\emph{#2}}
968 % This version is being checked in for the historical record; it shows
969 % how I've managed to get some aspects of this to work. It will not
970 % be used in practice, so a subsequent revision will change things
971 % again. This version has problems, but shows how to do something
972 % that proved more tedious than I'd expected, so I don't want to lose
973 % the example completely.
975 \newcommand{\grammartoken}[1]{\texttt{#1}}
976 \newenvironment{productionlist
}[1][\py@badkey
]{
977 \def\optional#
#1{{\Large[}#
#1{\Large]}}
978 \def\production#
#1#
#2{\code{#
#1}&::=&
\code{#
#2}\\
}
979 \def\productioncont#
#1{& &
\code{#
#1}\\
}
981 \let\grammartoken=
\token
989 \newlength{\py@noticelength
}
991 \newcommand{\py@heavybox
}{
992 \setlength{\fboxrule}{2pt
}
993 \setlength{\fboxsep}{7pt
}
994 \setlength{\py@noticelength
}{\linewidth}
995 \addtolength{\py@noticelength
}{-
2\fboxsep}
996 \addtolength{\py@noticelength
}{-
2\fboxrule}
997 \setlength{\shadowsize}{3pt
}
999 \minipage{\py@noticelength
}
1001 \newcommand{\py@endheavybox
}{
1007 % a 'note' is as plain as it gets:
1008 \newcommand{\py@noticelabel@note
}{Note:
}
1009 \newcommand{\py@noticestart@note
}{}
1010 \newcommand{\py@noticeend@note
}{}
1012 % a 'warning' gets more visible distinction:
1013 \newcommand{\py@noticelabel@warning
}{Warning:
}
1014 \newcommand{\py@noticestart@warning
}{\py@heavybox
}
1015 \newcommand{\py@noticeend@warning
}{\py@endheavybox
}
1017 \newenvironment{notice
}[1][note
]{
1018 \def\py@noticetype
{#1}
1019 \csname py@noticestart@
#1\endcsname
1020 \par\strong{\csname py@noticelabel@
#1\endcsname}
1021 }{\csname py@noticeend@
\py@noticetype
\endcsname}
1022 \newcommand{\note}[1]{\strong{\py@noticelabel@note
} #1}
1023 \newcommand{\warning}[1]{\strong{\py@noticelabel@warning
} #1}
1025 % Deprecation stuff.
1026 % Should be extended to allow an index / list of deprecated stuff. But
1027 % there's a lot of stuff that needs to be done to make that automatable.
1029 % First parameter is the release number that deprecates the feature, the
1030 % second is the action the should be taken by users of the feature.
1033 % \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
1035 \newcommand{\deprecated}[2]{%
1036 \strong{Deprecated since release
#1.
} #2\par}
1039 % This should be used to mark things which have been added to the
1040 % development tree but that aren't in the release, but are documented.
1041 % This allows release of documentation that already includes updated
1042 % descriptions. Place at end of descriptor environment.
1045 % \versionadded{1.5.2}
1046 % \versionchanged[short explanation]{2.0}
1048 \newcommand{\versionadded}[2][\py@badkey
]{%
1050 { New in version
#2.
}%
1052 { New in version
#2:\
#1.
}%
1055 \newcommand{\versionchanged}[2][\py@badkey
]{%
1057 { Changed in version
#2.
}%
1059 { Changed in version
#2:\
#1.
}%
1066 \newenvironment{tableii
}[4]{%
1068 \def\lineii#
#1#
#2{\csname#2\endcsname{#
#1}&#
#2\\
}%
1069 \begin{tabular
}{#1}\strong{#3}&
\strong{#4} \\*
\hline%
1075 \newenvironment{longtableii
}[4]{%
1077 \def\lineii#
#1#
#2{\csname#2\endcsname{#
#1}&#
#2\\
}%
1078 \begin{longtable
}[c
]{#1}\strong{#3}&
\strong{#4} \\*
\hline\endhead%
1084 \newenvironment{tableiii
}[5]{%
1086 \def\lineiii#
#1#
#2#
#3{\csname#2\endcsname{#
#1}&#
#2&#
#3\\
}%
1087 \begin{tabular
}{#1}\strong{#3}&
\strong{#4}&
\strong{#5} \\%
1094 \newenvironment{longtableiii
}[5]{%
1096 \def\lineiii#
#1#
#2#
#3{\csname#2\endcsname{#
#1}&#
#2&#
#3\\
}%
1097 \begin{longtable
}[c
]{#1}\strong{#3}&
\strong{#4}&
\strong{#5} \\%
1104 \newenvironment{tableiv
}[6]{%
1106 \def\lineiv#
#1#
#2#
#3#
#4{\csname#2\endcsname{#
#1}&#
#2&#
#3&#
#4\\
}%
1107 \begin{tabular
}{#1}\strong{#3}&
\strong{#4}&
\strong{#5}&
\strong{#6} \\%
1114 \newenvironment{longtableiv
}[6]{%
1116 \def\lineiv#
#1#
#2#
#3#
#4{\csname#2\endcsname{#
#1}&#
#2&#
#3&#
#4\\
}%
1117 \begin{longtable
}[c
]{#1}\strong{#3}&
\strong{#4}&
\strong{#5}&
\strong{#6}%
1125 \newenvironment{tablev
}[7]{%
1127 \def\linev#
#1#
#2#
#3#
#4#
#5{\csname#2\endcsname{#
#1}&#
#2&#
#3&#
#4&#
#5\\
}%
1128 \begin{tabular
}{#1}\strong{#3}&
\strong{#4}&
\strong{#5}&
\strong{#6}&
\strong{#7} \\%
1135 \newenvironment{longtablev
}[7]{%
1137 \def\linev#
#1#
#2#
#3#
#4#
#5{\csname#2\endcsname{#
#1}&#
#2&#
#3&#
#4&#
#5\\
}%
1138 \begin{longtable
}[c
]{#1}\strong{#3}&
\strong{#4}&
\strong{#5}&
\strong{#6}&
\strong{#7}%
1146 % XXX Don't think we can use this yet, though it cleans up some
1147 % tedious markup. There's no equivalent for the HTML transform yet,
1148 % and that needs to exist. I don't know how to write it.
1150 % This should really have something that makes it easier to bind a
1151 % table's ``Notes'' column and an associated tablenotes environment,
1152 % and generates the right magic for getting the numbers right in the
1155 % So this is quite incomplete.
1157 \newcounter{py@tablenotescounter
}
1158 \newenvironment{tablenotes
}{%
1161 \setcounter{py@tablenotescounter
}{0}
1162 \begin{list
}{(
\arabic{py@tablenotescounter
})
}%
1163 {\usecounter{py@tablenotescounter
}}
1167 % Cross-referencing (AMK, new impl. FLD)
1170 % \seemodule{rand}{Uniform random number generator.}; % Module xref
1171 % \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book
1173 % % A funky case: module name contains '_'; have to supply an optional key
1174 % \seemodule[copyreg]{copy_reg}{Interface constructor registration for
1178 % Note that the last parameter for \seemodule and \seetext should be complete
1179 % sentences and be terminated with the proper punctuation.
1182 \newcommand{\py@seemodule
}[3][\py@modulebadkey
]{%
1184 \ifx\py@modulebadkey
#1\def\py@modulekey
{#2}\else\def\py@modulekey
{#1}\fi%
1185 \begin{fulllineitems
}
1186 \item[\py@linkToName
{label-module-
\py@modulekey
}{Module
\module{#2}}
1187 (section
\ref{module-
\py@modulekey
}):
]
1192 \newcommand{\py@seemodule
}[3][\py@modulebadkey
]{%
1194 \ifx\py@modulebadkey
#1\def\py@modulekey
{#2}\else\def\py@modulekey
{#1}\fi%
1195 \begin{fulllineitems
}
1196 \item[Module
\module{#2} (section
\ref{module-
\py@modulekey
}):
]
1202 % \seelink{url}{link text}{why it's interesting}
1203 \newcommand{\py@seelink
}[3]{%
1205 \begin{fulllineitems
}
1206 \item[\ulink{#2}{#1}]
1210 % \seetitle[url]{title}{why it's interesting}
1211 \newcommand{\py@seetitle
}[3][\py@modulebadkey
]{%
1213 \begin{fulllineitems
}
1214 \item[\citetitle{#2}]
1215 \ifx\py@modulebadkey
#1\else
1216 \item[{\small{(
\url{#1})
}}]
1221 % \seepep{number}{title}{why it's interesting}
1222 \newcommand{\py@seepep
}[3]{%
1224 \begin{fulllineitems
}
1225 \item[\pep{#1}, ``
\emph{#2}''
]
1229 % \seerfc{number}{title}{why it's interesting}
1230 \newcommand{\py@seerfc
}[3]{%
1232 \begin{fulllineitems
}
1233 \item[\rfc{#1}, ``
\emph{#2}''
]
1237 % \seeurl{url}{why it's interesting}
1238 \newcommand{\py@seeurl
}[2]{%
1240 \begin{fulllineitems
}
1246 \newenvironment{seealso*
}{
1248 \def\seetext#
#1{\par{#
#1}}
1249 \let\seemodule=
\py@seemodule
1250 \let\seepep=
\py@seepep
1251 \let\seerfc=
\py@seerfc
1252 \let\seetitle=
\py@seetitle
1253 \let\seeurl=
\py@seeurl
1254 \let\seelink=
\py@seelink
1256 \newenvironment{seealso
}{
1260 \def\seetext#
#1{\par{#
#1}}
1261 \let\seemodule=
\py@seemodule
1262 \let\seepep=
\py@seepep
1263 \let\seerfc=
\py@seerfc
1264 \let\seetitle=
\py@seetitle
1265 \let\seeurl=
\py@seeurl
1266 \let\seelink=
\py@seelink
1269 % Allow the Python release number to be specified independently of the
1270 % \date{}. This allows the date to reflect the document's date and
1271 % release to specify the Python release that is documented.
1273 \newcommand{\py@release
}{}
1274 \newcommand{\version}{}
1275 \newcommand{\shortversion}{}
1276 \newcommand{\releaseinfo}{}
1277 \newcommand{\releasename}{Release
}
1278 \newcommand{\release}[1]{%
1279 \renewcommand{\py@release
}{\releasename\space\version}%
1280 \renewcommand{\version}{#1}}
1281 \newcommand{\setshortversion}[1]{%
1282 \renewcommand{\shortversion}{#1}}
1283 \newcommand{\setreleaseinfo}[1]{%
1284 \renewcommand{\releaseinfo}{#1}}
1286 % Allow specification of the author's address separately from the
1287 % author's name. This can be used to format them differently, which
1290 \newcommand{\py@authoraddress
}{}
1291 \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress
}{#1}}
1292 \let\developersaddress=
\authoraddress
1293 \let\developer=
\author
1294 \let\developers=
\author
1296 % This sets up the fancy chapter headings that make the documents look
1297 % at least a little better than the usual LaTeX output.
1299 \@ifundefined
{ChTitleVar
}{}{
1300 \ChNameVar{\raggedleft\normalsize\py@HeaderFamily
}
1301 \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily
}
1302 \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily
}
1303 % This creates chapter heads without the leading \vspace*{}:
1304 \def\@makechapterhead
#1{%
1305 {\parindent \z@
\raggedright \normalfont
1306 \ifnum \c@secnumdepth >
\m@ne
1309 \interlinepenalty\@M
1316 % Definition lists; requested by AMK for HOWTO documents. Probably useful
1317 % elsewhere as well, so keep in in the general style support.
1319 \newenvironment{definitions
}{%
1320 \begin{description
}%
1321 \def\term#
#1{\item[#
#1]\mbox{}\\*
[0mm
]}
1326 % Tell TeX about pathological hyphenation cases:
1327 \hyphenation{Base-HTTP-Re-quest-Hand-ler
}