Doc/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{classdesc*}{name}
 627 \newenvironment{classdesc*}[1]{
 628   % Using \renewcommand doesn't work for this, for unknown reasons:
 629   \global\def\py@thisclass{#1}
 630   \begin{fulllineitems}
 631     \item[\strong{class }\code{\bfcode{#1}}%
 632       \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]
 633 }{\end{fulllineitems}}
 634
 635 % \begin{excclassdesc}{name}{constructor args}
 636 % but indexes as an exception
 637 \newenvironment{excclassdesc}[2]{
 638   % Using \renewcommand doesn't work for this, for unknown reasons:
 639   \global\def\py@thisclass{#1}
 640   \begin{fulllineitems}
 641     \item[\strong{exception }\code{\bfcode{#1}(\py@varvars{#2})}%
 642       \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
 643 }{\end{fulllineitems}}
 644
 645 % There is no corresponding {excclassdesc*} environment.  To describe
 646 % a class exception without parameters, use the {excdesc} environment.
 647
 648
 649 \let\py@classbadkey=\@undefined
 650
 651 % object method ----------------------------------------------------------
 652 % \begin{methoddesc}[classname]{methodname}{args}
 653 \newcommand{\methodline}[3][\@undefined]{
 654   \methodlineni{#2}{#3}
 655   \ifx#1\@undefined
 656     \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}
 657   \else
 658     \index{#2@{\py@idxcode{#2()}} (#1 method)}
 659   \fi
 660 }
 661 \newenvironment{methoddesc}[3][\@undefined]{
 662   \begin{fulllineitems}
 663     \ifx#1\@undefined
 664       \methodline{#2}{#3}
 665     \else
 666       \def\py@thisclass{#1}
 667       \methodline{#2}{#3}
 668     \fi
 669 }{\end{fulllineitems}}
 670
 671 % similar to {methoddesc}, but doesn't add to the index
 672 % (never actually uses the optional argument)
 673 \newcommand{\methodlineni}[3][\py@classbadkey]{%
 674   \item[\code{\bfcode{#2}(\py@varvars{#3})}]}
 675 \newenvironment{methoddescni}[3][\py@classbadkey]{
 676   \begin{fulllineitems}
 677     \methodlineni{#2}{#3}
 678 }{\end{fulllineitems}}
 679
 680 % object data attribute --------------------------------------------------
 681 % \begin{memberdesc}[classname]{membername}
 682 \newcommand{\memberline}[2][\py@classbadkey]{%
 683   \ifx#1\@undefined
 684     \memberlineni{#2}
 685     \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}
 686   \else
 687     \memberlineni{#2}
 688     \index{#2@{\py@idxcode{#2}} (#1 attribute)}
 689   \fi
 690 }
 691 \newenvironment{memberdesc}[2][\py@classbadkey]{
 692   \begin{fulllineitems}
 693     \ifx#1\@undefined
 694       \memberline{#2}
 695     \else
 696       \def\py@thisclass{#1}
 697       \memberline{#2}
 698     \fi
 699 }{\end{fulllineitems}}
 700
 701 % similar to {memberdesc}, but doesn't add to the index
 702 % (never actually uses the optional argument)
 703 \newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}
 704 \newenvironment{memberdescni}[2][\py@classbadkey]{
 705   \begin{fulllineitems}
 706     \memberlineni{#2}
 707 }{\end{fulllineitems}}
 708
 709 % For exceptions: --------------------------------------------------------
 710 % \begin{excdesc}{name}
 711 %  -- for constructor information, use excclassdesc instead
 712 \newenvironment{excdesc}[1]{
 713   \begin{fulllineitems}
 714     \item[\strong{exception }\bfcode{#1}%
 715           \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
 716 }{\end{fulllineitems}}
 717
 718 % Module data or constants: ----------------------------------------------
 719 % \begin{datadesc}{name}
 720 \newcommand{\dataline}[1]{%
 721   \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}
 722 \newenvironment{datadesc}[1]{
 723   \begin{fulllineitems}
 724     \dataline{#1}
 725 }{\end{fulllineitems}}
 726
 727 % similar to {datadesc}, but doesn't add to the index
 728 \newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
 729 \newenvironment{datadescni}[1]{
 730   \begin{fulllineitems}
 731     \datalineni{#1}
 732 }{\end{fulllineitems}}
 733
 734 % bytecode instruction ---------------------------------------------------
 735 % \begin{opcodedesc}{name}{var}
 736 % -- {var} may be {}
 737 \newenvironment{opcodedesc}[2]{
 738   \begin{fulllineitems}
 739     \item[\bfcode{#1}\quad\var{#2}]
 740 }{\end{fulllineitems}}
 741
 742
 743 \newcommand{\nodename}[1]{\label{#1}}
 744
 745 % For these commands, use \command{} to get the typography right, not
 746 % {\command}.  This works better with the texinfo translation.
 747 \newcommand{\ABC}{{\sc abc}}
 748 \newcommand{\UNIX}{{\sc Unix}}
 749 \newcommand{\POSIX}{POSIX}
 750 \newcommand{\ASCII}{{\sc ascii}}
 751 \newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
 752 \newcommand{\C}{C}
 753 \newcommand{\EOF}{{\sc eof}}
 754 \newcommand{\NULL}{\constant{NULL}}
 755 \newcommand{\infinity}{\ensuremath{\infty}}
 756 \newcommand{\plusminus}{\ensuremath{\pm}}
 757 \newcommand{\menuselection}[1]{{\def\sub{ \ensuremath{>} }#1}}
 758
 759 % Also for consistency: spell Python "Python", not "python"!
 760
 761 % code is the most difficult one...
 762 \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`\%}%
 763 \texttt{#1}}}
 764
 765 \newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
 766 \newcommand{\kbd}[1]{\code{#1}}
 767 \newcommand{\samp}[1]{`\code{#1}'}
 768 % This weird definition of \var{} allows it to always appear in roman
 769 % italics, and won't get funky in code fragments when we play around
 770 % with fonts.  This also works directly in math mode.
 771 \newcommand{\var}[1]{%
 772   \ifmmode%
 773     \hbox{\normalsize\textrm{\textit{#1\/}}}%
 774   \else%
 775     \normalsize\textrm{\textit{#1\/}}%
 776   \fi%
 777 }
 778 \renewcommand{\emph}[1]{{\em #1}}
 779 \newcommand{\dfn}[1]{\emph{#1}}
 780 \newcommand{\strong}[1]{{\bf #1}}
 781 % let's experiment with a new font:
 782 \newcommand{\file}[1]{`{\small\textsf{#1}}'}
 783 \newcommand{\filenq}[1]{{\small\textsf{#1}}}
 784
 785 % Use this def/redef approach for \url{} since hyperref defined this already,
 786 % but only if we actually used hyperref:
 787 \@ifundefined{pdfannotlink}{
 788   \newcommand{\py@url}[1]{\mbox{\small\textsf{#1}}}
 789 }{
 790   \newcommand{\py@url}[1]{{%
 791     \pdfannotlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
 792     \py@LinkColor%                              color of the link text
 793     \mbox{\small\textsf{#1}}%
 794     \py@NormalColor%                    Turn it back off; these are declarative
 795     \pdfendlink}%                       and don't appear bound to the current
 796   }%                                    formatting "box".
 797 }
 798 \let\url=\py@url
 799 \newcommand{\email}[1]{{\small\textsf{#1}}}
 800 \newcommand{\newsgroup}[1]{{\small\textsf{#1}}}
 801
 802 \newcommand{\py@varvars}[1]{{%
 803   {\let\unspecified=\py@unspecified%
 804    \let\moreargs=\py@moreargs%
 805    \var{#1}}}}
 806
 807 % I'd really like to get rid of this!
 808 \newif\iftexi\texifalse
 809
 810 % This is used to get l2h to put the copyright and abstract on
 811 % a separate HTML page.
 812 \newif\ifhtml\htmlfalse
 813
 814
 815 % These should be used for all references to identifiers which are
 816 % used to refer to instances of specific language constructs.  See the
 817 % names for specific semantic assignments.
 818 %
 819 % For now, don't do anything really fancy with them; just use them as
 820 % logical markup.  This might change in the future.
 821 %
 822 \newcommand{\module}[1]{\texttt{#1}}
 823 \newcommand{\keyword}[1]{\texttt{#1}}
 824 \newcommand{\exception}[1]{\texttt{#1}}
 825 \newcommand{\class}[1]{\texttt{#1}}
 826 \newcommand{\function}[1]{\texttt{#1}}
 827 \newcommand{\member}[1]{\texttt{#1}}
 828 \newcommand{\method}[1]{\texttt{#1}}
 829
 830 \newcommand{\pytype}[1]{#1}             % built-in Python type
 831
 832 \newcommand{\cfunction}[1]{\texttt{#1}}
 833 \newcommand{\ctype}[1]{\texttt{#1}}     % C struct or typedef name
 834 \newcommand{\cdata}[1]{\texttt{#1}}     % C variable, typically global
 835
 836 \newcommand{\mimetype}[1]{{\small\textsf{#1}}}
 837 % The \! is a "negative thin space" in math mode.
 838 \newcommand{\regexp}[1]{%
 839   {\tiny$^{^\lceil}\!\!$%
 840    {\normalsize\code{#1}}%
 841    $\!\rfloor\!$%
 842   }}
 843 \newcommand{\envvar}[1]{%
 844   #1%
 845   \index{#1@{#1}}%
 846   \index{environment variables!{#1}}%
 847 }
 848 \newcommand{\makevar}[1]{#1}            % variable in a Makefile
 849 \newcommand{\character}[1]{\samp{#1}}
 850
 851 % constants defined in Python modules or C headers, not language constants:
 852 \newcommand{\constant}[1]{\code{#1}}    % manifest constant, not syntactic
 853
 854 \newcommand{\manpage}[2]{{\emph{#1}(#2)}}
 855 \newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}
 856 \newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
 857 \newcommand{\program}[1]{\strong{#1}}
 858 \newcommand{\programopt}[1]{\strong{#1}}
 859 % Note that \longprogramopt provides the '--'!
 860 \newcommand{\longprogramopt}[1]{\strong{-{}-#1}}
 861 % \ulink{link text}{URL}
 862 \newcommand{\ulink}[2]{#1}
 863
 864 % cited titles:  \citetitle{Title of Work}
 865 %       online:  \citetitle[url-to-resource]{Title of Work}
 866 \newcommand{\citetitle}[2][URL]{\emph{#2}}
 867
 868
 869 \newenvironment{productionlist}[1][\py@badkey]{
 870   \def\optional##1{{\Large[}##1{\Large]}}
 871   \def\production##1##2{\code{##1}&::=&\code{##2}\\}
 872   \def\orgroup##1{{\def\or{\textbar\ }##1}}
 873   \def\token##1{##1}
 874   \begin{center}
 875     \begin{tabular}{lcl}
 876 }{%
 877     \end{tabular}
 878   \end{center}
 879 }
 880
 881 % Deprecation stuff.
 882 % Should be extended to allow an index / list of deprecated stuff.  But
 883 % there's a lot of stuff that needs to be done to make that automatable.
 884 %
 885 % First parameter is the release number that deprecates the feature, the
 886 % second is the action the should be taken by users of the feature.
 887 %
 888 % Example:
 889 %  \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
 890 %
 891 \newcommand{\deprecated}[2]{%
 892   \strong{Deprecated since release #1.}  #2\par}
 893
 894 % New stuff.
 895 % This should be used to mark things which have been added to the
 896 % development tree but that aren't in the release, but are documented.
 897 % This allows release of documentation that already includes updated
 898 % descriptions.  Place at end of descriptor environment.
 899 %
 900 % Example:
 901 %  \versionadded{1.5.2}
 902 %  \versionchanged[short explanation]{2.0}
 903 %
 904 \newcommand{\versionadded}[2][\py@badkey]{%
 905   \ifx#1\@undefined%
 906     {  New in version #2.  }%
 907   \else%
 908     {  New in version #2:\ #1.  }%
 909   \fi%
 910 }
 911 \newcommand{\versionchanged}[2][\py@badkey]{%
 912   \ifx#1\@undefined%
 913     {  Changed in version #2.  }%
 914   \else%
 915     {  Changed in version #2:\ #1.  }%
 916   \fi%
 917 }
 918
 919
 920 % Tables.
 921 %
 922 \newenvironment{tableii}[4]{%
 923   \begin{center}%
 924     \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
 925     \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline%
 926 }{%
 927     \end{tabular}%
 928   \end{center}%
 929 }
 930
 931 \newenvironment{longtableii}[4]{%
 932   \begin{center}%
 933     \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
 934     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead%
 935 }{%
 936     \end{longtable}%
 937   \end{center}%
 938 }
 939
 940 \newenvironment{tableiii}[5]{%
 941   \begin{center}%
 942     \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
 943     \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
 944       \hline%
 945 }{%
 946     \end{tabular}%
 947   \end{center}%
 948 }
 949
 950 \newenvironment{longtableiii}[5]{%
 951   \begin{center}%
 952     \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
 953     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
 954       \hline\endhead%
 955 }{%
 956     \end{longtable}%
 957   \end{center}%
 958 }
 959
 960 \newenvironment{tableiv}[6]{%
 961   \begin{center}%
 962     \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
 963     \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\%
 964       \hline%
 965 }{%
 966     \end{tabular}%
 967   \end{center}%
 968 }
 969
 970 \newenvironment{longtableiv}[6]{%
 971   \begin{center}%
 972     \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
 973     \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}%
 974       \\%
 975       \hline\endhead%
 976 }{%
 977     \end{longtable}%
 978   \end{center}%
 979 }
 980
 981 % Cross-referencing (AMK, new impl. FLD)
 982 % Sample usage:
 983 %  \begin{seealso}
 984 %    \seemodule{rand}{Uniform random number generator.}; % Module xref
 985 %    \seetext{\emph{Encyclopedia Britannica}}.           % Ref to a book
 986 %
 987 %    % A funky case: module name contains '_'; have to supply an optional key
 988 %    \seemodule[copyreg]{copy_reg}{Interface constructor registration for
 989 %                                  \module{pickle}.}
 990 %  \end{seealso}
 991 %
 992 % Note that the last parameter for \seemodule and \seetext should be complete
 993 % sentences and be terminated with the proper punctuation.
 994
 995 \@ifundefined{pdfannotlink}{%
 996   \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
 997     \par%
 998     \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
 999     \begin{fulllineitems}
1000       \item[Module \module{#2} (section \ref{module-\py@modulekey}):]
1001       #3
1002     \end{fulllineitems}
1003   }
1004 }{\newcommand{\py@seemodule}[3][\py@modulebadkey]{%
1005     \par%
1006     \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
1007     \begin{fulllineitems}
1008       \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}}
1009             (section \ref{module-\py@modulekey}):]
1010       #3
1011     \end{fulllineitems}
1012   }
1013 }
1014 % \seetitle[url]{title}{why it's interesting}
1015 \newcommand{\py@seetitle}[3][\py@modulebadkey]{%
1016   \par
1017   \begin{fulllineitems}
1018     \item[\citetitle{#2}]
1019     \ifx\py@modulebadkey#1\else
1020       \item[{\small{(\url{#1})}}]
1021     \fi
1022     #3
1023   \end{fulllineitems}
1024 }
1025 % \seepep{number}{title}{why it's interesting}
1026 \newcommand{\py@seepep}[3]{%
1027   \par%
1028   \begin{fulllineitems}
1029     \item[\pep{#1}, ``\emph{#2}'']
1030     #3
1031   \end{fulllineitems}
1032 }
1033 % \seerfc{number}{title}{why it's interesting}
1034 \newcommand{\py@seerfc}[3]{%
1035   \par%
1036   \begin{fulllineitems}
1037     \item[\rfc{#1}, ``\emph{#2}'']
1038     #3
1039   \end{fulllineitems}
1040 }
1041 % \seeurl{url}{why it's interesting}
1042 \newcommand{\py@seeurl}[2]{%
1043   \par%
1044   \begin{fulllineitems}
1045     \item[\url{#1}]
1046     #2
1047   \end{fulllineitems}
1048 }
1049 \newenvironment{seealso}[0]{
1050   \par
1051   \strong{See Also:}\par
1052   \def\seetext##1{\par{##1}}
1053   \let\seemodule=\py@seemodule
1054   \let\seepep=\py@seepep
1055   \let\seerfc=\py@seerfc
1056   \let\seetitle=\py@seetitle
1057   \let\seeurl=\py@seeurl
1058 }{\par}
1059
1060
1061 % Allow the Python release number to be specified independently of the
1062 % \date{}.  This allows the date to reflect the document's date and
1063 % release to specify the Python release that is documented.
1064 %
1065 \newcommand{\py@release}{}
1066 \newcommand{\version}{}
1067 \newcommand{\shortversion}{}
1068 \newcommand{\releaseinfo}{}
1069 \newcommand{\releasename}{Release}
1070 \newcommand{\release}[1]{%
1071   \renewcommand{\py@release}{\releasename\space\version}%
1072   \renewcommand{\version}{#1}}
1073 \newcommand{\setshortversion}[1]{%
1074   \renewcommand{\shortversion}{#1}}
1075 \newcommand{\setreleaseinfo}[1]{%
1076   \renewcommand{\releaseinfo}{#1}}
1077
1078 % Allow specification of the author's address separately from the
1079 % author's name.  This can be used to format them differently, which
1080 % is a good thing.
1081 %
1082 \newcommand{\py@authoraddress}{}
1083 \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
1084 \let\developersaddress=\authoraddress
1085 \let\developer=\author
1086 \let\developers=\author
1087
1088 % This sets up the fancy chapter headings that make the documents look
1089 % at least a little better than the usual LaTeX output.
1090 %
1091 \@ifundefined{ChTitleVar}{}{
1092   \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
1093   \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
1094   \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
1095   % This creates chapter heads without the leading \vspace*{}:
1096   \def\@makechapterhead#1{%
1097     {\parindent \z@ \raggedright \normalfont
1098       \ifnum \c@secnumdepth >\m@ne
1099         \DOCH
1100       \fi
1101       \interlinepenalty\@M
1102       \DOTI{#1}
1103     }
1104   }
1105 }
1106
1107
1108 % Definition lists; requested by AMK for HOWTO documents.  Probably useful
1109 % elsewhere as well, so keep in in the general style support.
1110 %
1111 \newenvironment{definitions}{%
1112   \begin{description}%
1113   \def\term##1{\item[##1]\mbox{}\\*[0mm]}
1114 }{%
1115   \end{description}%
1116 }
1117
1118 % Tell TeX about pathological hyphenation cases:
1119 \hyphenation{Base-HTTP-Re-quest-Hand-ler}