doc/tools/texinputs/python.sty

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