%

% python.sty for the Python docummentation [works only with Latex2e]

%

\NeedsTeXFormat{LaTeX2e}[1995/12/01]

\ProvidesPackage{python}

[1998/01/11 LaTeX package (Python markup)]

\RequirePackage{longtable}

% Uncomment these two lines to ignore the paper size and make the page

% size more like a typical published manual.

%\renewcommand{\paperheight}{9in}

%\renewcommand{\paperwidth}{8.5in} % typical squarish manual

%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python''

% These packages can be used to add marginal annotations which indicate

% index entries and labels; useful for reviewing this messy documentation!

%

%\RequirePackage{showkeys}

%\RequirePackage{showidx}

% for PDF output, use maximal compression & a lot of other stuff

% (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)

%

\newif\ifpy@doing@page@targets

\py@doing@page@targetsfalse

\newif\ifpdf\pdffalse

\ifx\pdfoutput\undefined\else\ifcase\pdfoutput

\else

\pdftrue

\input{pdfcolor}

\let\py@LinkColor=\NavyBlue

\let\py@NormalColor=\Black

\pdfcompresslevel=9

\pdfpagewidth=\paperwidth % page width of PDF output

\pdfpageheight=\paperheight % page height of PDF output

%

% Pad the number with '0' to 3 digits wide so no page name is a prefix

% of any other.

%

\newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1}

\newcommand{\py@pageno}{\py@targetno\thepage}

%

% This definition allows the entries in the page-view of the ToC to be

% active links. Some work, some don't.

%

\let\py@OldContentsline=\contentsline

%

% Backward compatibility hack: pdfTeX 0.13 defined \pdfannotlink,

% but it changed to \pdfstartlink in 0.14. This let's us use either

% version and still get useful behavior.

%

\@ifundefined{pdfstartlink}{

\let\pdfstartlink=\pdfannotlink

}{}

%

% Macro that takes two args: the name to link to and the content of

% the link. This takes care of the PDF magic, getting the colors

% the same for each link, and avoids having lots of garbage all over

% this style file.

\newcommand{\py@linkToName}[2]{%

\pdfstartlink attr{/Border [0 0 0]} goto name{#1}%

\py@LinkColor#2\py@NormalColor%

\pdfendlink%

}

% Compute the padded page number separately since we end up with a pair of

% \relax tokens; this gets the right string computed and works.

\renewcommand{\contentsline}[3]{%

\def\my@pageno{\py@targetno{#3}}%

\py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}%

}

\AtEndDocument{

\InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{}

}

\newcommand{\py@target}[1]{%

\ifpy@doing@page@targets%

{\pdfdest name{#1} xyz}%

\fi%

}

\let\py@OldLabel=\label

\renewcommand{\label}[1]{%

\py@OldLabel{#1}%

\py@target{label-#1}%

}

% This stuff adds a page# destination to every PDF page, where # is three

% digits wide, padded with leading zeros. This doesn't really help with

% the frontmatter, but does fine with the body.

%

% This is *heavily* based on the hyperref package.

%

\def\@begindvi{%

\unvbox \@begindvibox

\@hyperfixhead

}

\def\@hyperfixhead{%

\let\H@old@thehead\@thehead

\global\def\@foo{\py@target{page\py@pageno}}%

\expandafter\ifx\expandafter\@empty\H@old@thehead

\def\H@old@thehead{\hfil}\fi

\def\@thehead{\@foo\relax\H@old@thehead}%

}

\fi\fi

% Increase printable page size (copied from fullpage.sty)

\topmargin 0pt

\advance \topmargin by -\headheight

\advance \topmargin by -\headsep

% attempt to work a little better for A4 users

\textheight \paperheight

\advance\textheight by -2in

\oddsidemargin 0pt

\evensidemargin 0pt

%\evensidemargin -.25in % for ``manual size'' documents

\marginparwidth 0.5in

\textwidth \paperwidth

\advance\textwidth by -2in

% Style parameters and macros used by most documents here

\raggedbottom

\sloppy

\parindent = 0mm

\parskip = 2mm

\hbadness = 5000 % don't print trivial gripes

\pagestyle{empty} % start this way; change for

\pagenumbering{roman} % ToC & chapters

% Use this to set the font family for headers and other decor:

\newcommand{\py@HeaderFamily}{\sffamily}

% Set up abstract ways to get the normal and smaller font sizes that

% work even in footnote context.

\newif\ifpy@infootnote \py@infootnotefalse

\let\py@oldmakefntext\@makefntext

\def\@makefntext#1{%

\bgroup%

\py@infootnotetrue

\py@oldmakefntext{#1}%

\egroup%

}

\def\py@defaultsize{%

\ifpy@infootnote\footnotesize\else\normalsize\fi%

}

\def\py@smallsize{%

\ifpy@infootnote\scriptsize\else\small\fi%

}

% Redefine the 'normal' header/footer style when using "fancyhdr" package:

\@ifundefined{fancyhf}{}{

% Use \pagestyle{normal} as the primary pagestyle for text.

\fancypagestyle{normal}{

\fancyhf{}

\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}

\fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}

\fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}

\renewcommand{\headrulewidth}{0pt}

\renewcommand{\footrulewidth}{0.4pt}

}

% Update the plain style so we get the page number & footer line,

% but not a chapter or section title. This is to keep the first

% page of a chapter and the blank page between chapters `clean.'

\fancypagestyle{plain}{

\fancyhf{}

\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}

\renewcommand{\headrulewidth}{0pt}

\renewcommand{\footrulewidth}{0.4pt}

}

% Redefine \cleardoublepage so that the blank page between chapters

% gets the plain style and not the fancy style. This is described

% in the documentation for the fancyhdr package by Piet von Oostrum.

\@ifundefined{chapter}{}{

\renewcommand{\cleardoublepage}{

\clearpage\if@openright \ifodd\c@page\else

\hbox{}

\thispagestyle{plain}

\newpage

\if@twocolumn\hbox{}\newpage\fi\fi\fi

}

}

}

% This sets up the {verbatim} environment to be indented and a minipage,

% and to have all the other mostly nice properties that we want for

% code samples.

\let\py@OldVerbatim=\verbatim

\let\py@OldEndVerbatim=\endverbatim

\RequirePackage{verbatim}

\let\py@OldVerbatimInput=\verbatiminput

% Variable used by begin code command

\newlength{\py@codewidth}

\renewcommand{\verbatim}{%

\setlength{\parindent}{1cm}%

% Calculate the text width for the minipage:

\setlength{\py@codewidth}{\linewidth}%

\addtolength{\py@codewidth}{-\parindent}%

%

\par\indent%

\begin{minipage}[t]{\py@codewidth}%

\small%

\py@OldVerbatim%

}

\renewcommand{\endverbatim}{%

\py@OldEndVerbatim%

\end{minipage}%

}

\renewcommand{\verbatiminput}[1]{%

{\setlength{\parindent}{1cm}%

% Calculate the text width for the minipage:

\setlength{\py@codewidth}{\linewidth}%

\addtolength{\py@codewidth}{-\parindent}%

%

\small%

\begin{list}{}{\setlength{\leftmargin}{1cm}}

\item%

\py@OldVerbatimInput{#1}%

\end{list}

}%

}

% This does a similar thing for the {alltt} environment:

\RequirePackage{alltt}

\let\py@OldAllTT=\alltt

\let\py@OldEndAllTT=\endalltt

\renewcommand{\alltt}{%

\setlength{\parindent}{1cm}%

% Calculate the text width for the minipage:

\setlength{\py@codewidth}{\linewidth}%

\addtolength{\py@codewidth}{-\parindent}%

%

\par\indent%

\begin{minipage}[t]{\py@codewidth}%

\small%

\py@OldAllTT%

}

\renewcommand{\endalltt}{%

\py@OldEndAllTT%

\end{minipage}%

}

\newcommand{\py@modulebadkey}{{--just-some-junk--}}

%% Lots of index-entry generation support.

% Command to wrap around stuff that refers to function / module /

% attribute names in the index. Default behavior: like \code{}. To

% just keep the index entries in the roman font, uncomment the second

% definition; it matches O'Reilly style more.

%

\newcommand{\py@idxcode}[1]{\texttt{#1}}

%\renewcommand{\py@idxcode}[1]{#1}

% Command to generate two index entries (using subentries)

\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}

% And three entries (using only one level of subentries)

\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}

% And four (again, using only one level of subentries)

\newcommand{\indexiv}[4]{

\index{#1!#2 #3 #4}

\index{#2!#3 #4, #1}

\index{#3!#4, #1 #2}

\index{#4!#1 #2 #3}

}

% Command to generate a reference to a function, statement, keyword,

% operator.

\newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}}

\newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}}

\newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}}

\newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}}

\newcommand{\obindex}[1]{\indexii{object}{#1}}

\newcommand{\bifuncindex}[1]{%

\index{#1@{\py@idxcode{#1()}} (built-in function)}}

% Add an index entry for a module

\newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}}

\newcommand{\refmodindex}[1]{\py@refmodule{#1}{}}

\newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }}

\newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }}

\newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }}

% Refer to a module's documentation using a hyperlink of the module's

% name, at least if we're building PDF:

\ifpdf

\newcommand{\refmodule}[2][\py@modulebadkey]{%

\ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%

\py@linkToName{label-module-\py@modulekey}{\module{#2}}%

}

\else

\newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}}

\fi

% support for the module index

\newif\ifpy@UseModuleIndex

\py@UseModuleIndexfalse

\newcommand{\makemodindex}{

\newwrite\modindexfile

\openout\modindexfile=mod\jobname.idx

\py@UseModuleIndextrue

}

% Add the defining entry for a module

\newcommand{\py@modindex}[2]{%

\renewcommand{\py@thismodule}{#1}

\setindexsubitem{(in module #1)}%

\index{#1@{\py@idxcode{#1}} (#2module)|textbf}%

\ifpy@UseModuleIndex%

\@ifundefined{py@modplat@\py@thismodulekey}{

\write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}%

}{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} %

\emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}%

}

\fi%

}

% *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***

% built-in & Python modules in the main distribution

\newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }%

\typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}

\newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }%

\typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}

% Python & extension modules outside the main distribution

\newcommand{\modindex}[1]{\py@modindex{#1}{}%

\typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}}

\newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }%

\typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}

% Additional string for an index entry

\newif\ifpy@usingsubitem\py@usingsubitemfalse

\newcommand{\py@indexsubitem}{}

\newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}%

\py@usingsubitemtrue}

\newcommand{\ttindex}[1]{%

\ifpy@usingsubitem

\index{#1@{\py@idxcode{#1}}\py@indexsubitem}%

\else%

\index{#1@{\py@idxcode{#1}}}%

\fi%

}

\newcommand{\withsubitem}[2]{%

\begingroup%

\def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}%

#2%

\endgroup%

}

% Module synopsis processing -----------------------------------------------

%

\newcommand{\py@thisclass}{}

\newcommand{\py@thismodule}{}

\newcommand{\py@thismodulekey}{}

\newcommand{\py@thismoduletype}{}

\newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }}

\newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }}

\newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }}

\newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}}

\newif\ifpy@HaveModSynopsis \py@HaveModSynopsisfalse

\newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse

\newif\ifpy@HaveModPlatform \py@HaveModPlatformfalse

% \declaremodule[key]{type}{name}

\newcommand{\declaremodule}[3][\py@modulebadkey]{

\py@openModSynopsisFile

\renewcommand{\py@thismoduletype}{#2}

\ifx\py@modulebadkey#1

\renewcommand{\py@thismodulekey}{#3}

\else

\renewcommand{\py@thismodulekey}{#1}

\fi

\@ifundefined{py@#2IndexModule}{%

\typeout{*** MACRO declaremodule called with unknown module type: `#2'}

\py@IndexModule{#3}%

}{%

\csname py@#2IndexModule\endcsname{#3}%

}

\label{module-\py@thismodulekey}

}

\newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse

\newcommand{\py@ModPlatformFilename}{\jobname.pla}

\newcommand{\platform}[1]{

\ifpy@ModPlatformFileIsOpen\else

\newwrite\py@ModPlatformFile

\openout\py@ModPlatformFile=\py@ModPlatformFilename

\py@ModPlatformFileIsOpentrue

\fi

}

\InputIfFileExists{\jobname.pla}{}{}

\newcommand{\py@platformof}[2][\py@modulebadkey]{%

\ifx\py@modulebadkey#1 \def\py@key{#2}%

\else \def\py@key{#1}%

\fi%

\csname py@modplat@\py@key\endcsname%

}

\newcommand{\ignorePlatformAnnotation}[1]{}

% \moduleauthor{name}{email}

\newcommand{\moduleauthor}[2]{}

% \sectionauthor{name}{email}

\newcommand{\sectionauthor}[2]{}

\newcommand{\py@defsynopsis}{Module has no synopsis.}

\newcommand{\py@modulesynopsis}{\py@defsynopsis}

\newcommand{\modulesynopsis}[1]{

\py@HaveModSynopsistrue

\renewcommand{\py@modulesynopsis}{#1}

}

% define the file

\newwrite\py@ModSynopsisFile

% hacked from \addtocontents from latex.ltx:

\long\def\py@writeModSynopsisFile#1{%

\protected@write\py@ModSynopsisFile%

{\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%

{\string#1}%

}

\newcommand{\py@closeModSynopsisFile}{

\ifpy@ModSynopsisFileIsOpen

\closeout\py@ModSynopsisFile

\py@ModSynopsisFileIsOpenfalse

\fi

}

\newcommand{\py@openModSynopsisFile}{

\ifpy@ModSynopsisFileIsOpen\else

\openout\py@ModSynopsisFile=\py@ModSynopsisFilename

\py@ModSynopsisFileIsOpentrue

\fi

}

\newcommand{\py@ProcessModSynopsis}{

\ifpy@HaveModSynopsis

\py@writeModSynopsisFile{\modulesynopsis%

{\py@thismodulekey}{\py@thismodule}%

{\py@thismoduletype}{\py@modulesynopsis}}%

\py@HaveModSynopsisfalse

\fi

\renewcommand{\py@modulesynopsis}{\py@defsynopsis}

}

\AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile}

\long\def\py@writeModPlatformFile#1{%

\protected@write\py@ModPlatformFile%

{\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%

{\string#1}%

}

\newcommand{\localmoduletable}{

\IfFileExists{\py@ModSynopsisFilename}{

\begin{synopsistable}

\input{\py@ModSynopsisFilename}

\end{synopsistable}

}{}

}

\ifpdf

\newcommand{\py@ModSynopsisSummary}[4]{%

\py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\

}

\else

\newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}

\fi

\newenvironment{synopsistable}{

% key, name, type, synopsis

\let\modulesynopsis=\py@ModSynopsisSummary

\begin{tabular}{ll}

}{

\end{tabular}

}

%

% --------------------------------------------------------------------------

\newcommand{\py@reset}{

\py@usingsubitemfalse

\py@ProcessModSynopsis

\renewcommand{\py@thisclass}{}

\renewcommand{\py@thismodule}{}

\renewcommand{\py@thismodulekey}{}

\renewcommand{\py@thismoduletype}{}

}

% Augment the sectioning commands used to get our own font family in place,

% and reset some internal data items:

\renewcommand{\section}{\py@reset%

\@startsection{section}{1}{\z@}%

{-3.5ex \@plus -1ex \@minus -.2ex}%

{2.3ex \@plus.2ex}%

{\reset@font\Large\py@HeaderFamily}}

\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%

{-3.25ex\@plus -1ex \@minus -.2ex}%

{1.5ex \@plus .2ex}%

{\reset@font\large\py@HeaderFamily}}

\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}%

{-3.25ex\@plus -1ex \@minus -.2ex}%

{1.5ex \@plus .2ex}%

{\reset@font\normalsize\py@HeaderFamily}}

\renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}%

{3.25ex \@plus1ex \@minus.2ex}%

{-1em}%

{\reset@font\normalsize\py@HeaderFamily}}

\renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}%

{3.25ex \@plus1ex \@minus .2ex}%

{-1em}%

{\reset@font\normalsize\py@HeaderFamily}}

% This gets the underscores closer to the right width; the only change

% from standard LaTeX is the width specified.

\DeclareTextCommandDefault{\textunderscore}{%

\leavevmode \kern.06em\vbox{\hrule\@width.55em}}

% Underscore hack (only act like subscript operator if in math mode)

%

% The following is due to Mark Wooding (the old version didn't work with

% Latex 2e.

\DeclareRobustCommand\hackscore{%

\ifmmode_\else\textunderscore\fi%

}

\begingroup

\catcode`\_\active

\def\next{%

\AtBeginDocument{\catcode`\_\active\def_{\hackscore{}}}%

}

\expandafter\endgroup\next

% Now for a lot of semantically-loaded environments that do a ton of magical

% things to get the right formatting and index entries for the stuff in

% Python modules and C API.

% {fulllineitems} is used in one place in libregex.tex, but is really for

% internal use in this file.

%

\newcommand{\py@itemnewline}[1]{%

\@tempdima\linewidth%

\advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%

}

\newenvironment{fulllineitems}{

\begin{list}{}{\labelwidth \leftmargin \labelsep 0pt

\rightmargin 0pt \topsep -\parskip \partopsep \parskip

\itemsep -\parsep

\let\makelabel=\py@itemnewline}

}{\end{list}}

% \optional is mostly for use in the arguments parameters to the various

% {*desc} environments defined below, but may be used elsewhere. Known to

% be used in the debugger chapter.

%

% Typical usage:

%

% \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}

% ^^^ ^^^

% No space here No space here

%

% When a function has multiple optional parameters, \optional should be

% nested, not chained. This is right:

%

% \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}

%

\let\py@badkey=\@undefined

\newcommand{\optional}[1]{%

{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}

% This can be used when a function or method accepts an varying number

% of arguments, such as by using the *args syntax in the parameter list.

\newcommand{\py@moreargs}{...}

% This can be used when you don't want to document the parameters to a

% function or method, but simply state that it's an alias for

% something else.

\newcommand{\py@unspecified}{...}

\newlength{\py@argswidth}

\newcommand{\py@sigparams}[1]{%

\parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}}

\newcommand{\py@sigline}[2]{%

\settowidth{\py@argswidth}{#1\code{(}}%

\addtolength{\py@argswidth}{-2\py@argswidth}%

\addtolength{\py@argswidth}{\textwidth}%

\item[#1\code{(}\py@sigparams{#2}]}

% C functions ------------------------------------------------------------

% \begin{cfuncdesc}[refcount]{type}{name}{arglist}

% Note that the [refcount] slot should only be filled in by

% tools/anno-api.py; it pulls the value from the refcounts database.

\newcommand{\cfuncline}[3]{

\py@sigline{\code{#1 \bfcode{#2}}}{#3}%

\index{#2@{\py@idxcode{#2()}}}

}

\newenvironment{cfuncdesc}[4][\py@badkey]{

\begin{fulllineitems}

\cfuncline{#2}{#3}{#4}

\ifx#1\@undefined\else%

\emph{Return value: \textbf{#1}.}\\

\fi

}{\end{fulllineitems}}

% C variables ------------------------------------------------------------

% \begin{cvardesc}{type}{name}

\newenvironment{cvardesc}[2]{

\begin{fulllineitems}

\item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}]

}{\end{fulllineitems}}

% C data types -----------------------------------------------------------

% \begin{ctypedesc}[index name]{typedef name}

\newenvironment{ctypedesc}[2][\py@badkey]{

\begin{fulllineitems}

\item[\bfcode{#2}%

\ifx#1\@undefined%

\index{#2@{\py@idxcode{#2}} (C type)}

\else%

\index{#2@{\py@idxcode{#1}} (C type)}

\fi]

}{\end{fulllineitems}}

% C type fields ----------------------------------------------------------

% \begin{cmemberdesc}{container type}{ctype}{membername}

\newcommand{\cmemberline}[3]{

\item[\code{#2 \bfcode{#3}}]

\index{#3@{\py@idxcode{#3}} (#1 member)}

}

\newenvironment{cmemberdesc}[3]{

\begin{fulllineitems}

\cmemberline{#1}{#2}{#3}

}{\end{fulllineitems}}

% Funky macros -----------------------------------------------------------

% \begin{csimplemacrodesc}{name}

% -- "simple" because it has no args; NOT for constant definitions!

\newenvironment{csimplemacrodesc}[1]{

\begin{fulllineitems}

\item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}]

}{\end{fulllineitems}}

% simple functions (not methods) -----------------------------------------

% \begin{funcdesc}{name}{args}

\newcommand{\funcline}[2]{%

\funclineni{#1}{#2}%

\index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}}

\newenvironment{funcdesc}[2]{

\begin{fulllineitems}

\funcline{#1}{#2}

}{\end{fulllineitems}}

% similar to {funcdesc}, but doesn't add to the index

\newcommand{\funclineni}[2]{%

\py@sigline{\bfcode{#1}}{#2}}

\newenvironment{funcdescni}[2]{

\begin{fulllineitems}

\funclineni{#1}{#2}

}{\end{fulllineitems}}

% classes ----------------------------------------------------------------

% \begin{classdesc}{name}{constructor args}

\newenvironment{classdesc}[2]{

% Using \renewcommand doesn't work for this, for unknown reasons:

\global\def\py@thisclass{#1}

\begin{fulllineitems}

\py@sigline{\strong{class }\bfcode{#1}}{#2}%

\index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}

}{\end{fulllineitems}}

% \begin{classdesc*}{name}

\newenvironment{classdesc*}[1]{

% Using \renewcommand doesn't work for this, for unknown reasons:

\global\def\py@thisclass{#1}

\begin{fulllineitems}

\item[\strong{class }\code{\bfcode{#1}}%

\index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]

}{\end{fulllineitems}}

% \begin{excclassdesc}{name}{constructor args}

% but indexes as an exception

\newenvironment{excclassdesc}[2]{

% Using \renewcommand doesn't work for this, for unknown reasons:

\global\def\py@thisclass{#1}

\begin{fulllineitems}

\py@sigline{\strong{exception }\bfcode{#1}}{#2}%

\index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}

}{\end{fulllineitems}}

% There is no corresponding {excclassdesc*} environment. To describe

% a class exception without parameters, use the {excdesc} environment.

\let\py@classbadkey=\@undefined

% object method ----------------------------------------------------------

% \begin{methoddesc}[classname]{methodname}{args}

\newcommand{\methodline}[3][\@undefined]{

\methodlineni{#2}{#3}

\ifx#1\@undefined

\index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}

\else

\index{#2@{\py@idxcode{#2()}} (#1 method)}

\fi

}

\newenvironment{methoddesc}[3][\@undefined]{

\begin{fulllineitems}

\ifx#1\@undefined

\methodline{#2}{#3}

\else

\def\py@thisclass{#1}

\methodline{#2}{#3}

\fi

}{\end{fulllineitems}}

% similar to {methoddesc}, but doesn't add to the index

% (never actually uses the optional argument)

\newcommand{\methodlineni}[3][\py@classbadkey]{%

\py@sigline{\bfcode{#2}}{#3}}

\newenvironment{methoddescni}[3][\py@classbadkey]{

\begin{fulllineitems}

\methodlineni{#2}{#3}

}{\end{fulllineitems}}

% object data attribute --------------------------------------------------

% \begin{memberdesc}[classname]{membername}

\newcommand{\memberline}[2][\py@classbadkey]{%

\ifx#1\@undefined

\memberlineni{#2}

\index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}

\else

\memberlineni{#2}

\index{#2@{\py@idxcode{#2}} (#1 attribute)}

\fi

}

\newenvironment{memberdesc}[2][\py@classbadkey]{

\begin{fulllineitems}

\ifx#1\@undefined

\memberline{#2}

\else

\def\py@thisclass{#1}

\memberline{#2}

\fi

}{\end{fulllineitems}}

% similar to {memberdesc}, but doesn't add to the index

% (never actually uses the optional argument)

\newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}

\newenvironment{memberdescni}[2][\py@classbadkey]{

\begin{fulllineitems}

\memberlineni{#2}

}{\end{fulllineitems}}

% For exceptions: --------------------------------------------------------

% \begin{excdesc}{name}

% -- for constructor information, use excclassdesc instead

\newenvironment{excdesc}[1]{

\begin{fulllineitems}

\item[\strong{exception }\bfcode{#1}%

\index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]

}{\end{fulllineitems}}

% Module data or constants: ----------------------------------------------

% \begin{datadesc}{name}

\newcommand{\dataline}[1]{%

\datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}

\newenvironment{datadesc}[1]{

\begin{fulllineitems}

\dataline{#1}

}{\end{fulllineitems}}

% similar to {datadesc}, but doesn't add to the index

\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}

\newenvironment{datadescni}[1]{

\begin{fulllineitems}

\datalineni{#1}

}{\end{fulllineitems}}

% bytecode instruction ---------------------------------------------------

% \begin{opcodedesc}{name}{var}

% -- {var} may be {}

\newenvironment{opcodedesc}[2]{

\begin{fulllineitems}

\item[\bfcode{#1}\quad\var{#2}]

}{\end{fulllineitems}}

\newcommand{\nodename}[1]{\label{#1}}

% For these commands, use \command{} to get the typography right, not

% {\command}. This works better with the texinfo translation.

\newcommand{\ABC}{{\sc abc}}

\newcommand{\UNIX}{{\sc Unix}}

\newcommand{\POSIX}{POSIX}

\newcommand{\ASCII}{{\sc ascii}}

\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}

\newcommand{\C}{C}

\newcommand{\EOF}{{\sc eof}}

\newcommand{\NULL}{\constant{NULL}}

\newcommand{\infinity}{\ensuremath{\infty}}

\newcommand{\plusminus}{\ensuremath{\pm}}

% \menuselection{Start \sub Programs \sub Python}

\newcommand{\menuselection}[1]{\textsf{\def\sub{ \ensuremath{>} }#1}}

% Also for consistency: spell Python "Python", not "python"!

% code is the most difficult one...

\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`\%}%

\texttt{#1}}}

\newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font

\newcommand{\csimplemacro}[1]{\code{#1}}

\newcommand{\kbd}[1]{\code{#1}}

\newcommand{\samp}[1]{`\code{#1}'}

\newcommand{\var}[1]{%

\ifmmode%

\hbox{\py@defaultsize\textrm{\textit{#1\/}}}%

\else%

\py@defaultsize\textrm{\textit{#1\/}}%

\fi%

}

\renewcommand{\emph}[1]{{\em #1}}

\newcommand{\dfn}[1]{\emph{#1}}

\newcommand{\strong}[1]{{\bf #1}}

% let's experiment with a new font:

\newcommand{\file}[1]{`\filenq{#1}'}

\newcommand{\filenq}[1]{{\py@smallsize\textsf{#1}}}

% Use this def/redef approach for \url{} since hyperref defined this already,

% but only if we actually used hyperref:

\ifpdf

\newcommand{\url}[1]{{%

\noindent%

\pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%

\py@LinkColor% color of the link text

\py@smallsize\sf #1%

\py@NormalColor% Turn it back off; these are declarative

\pdfendlink}% and don't appear bound to the current

}% formatting "box".

\else

\newcommand{\url}[1]{\mbox{\py@smallsize\textsf{#1}}}

\fi

\newcommand{\email}[1]{{\py@smallsize\textsf{#1}}}

\newcommand{\newsgroup}[1]{{\py@smallsize\textsf{#1}}}

\newcommand{\py@varvars}[1]{{%

{\let\unspecified=\py@unspecified%

\let\moreargs=\py@moreargs%

\var{#1}}}}

% I'd really like to get rid of this!

\newif\iftexi\texifalse

% This is used to get l2h to put the copyright and abstract on

% a separate HTML page.

\newif\ifhtml\htmlfalse

% These should be used for all references to identifiers which are

% used to refer to instances of specific language constructs. See the

% names for specific semantic assignments.

%

% For now, don't do anything really fancy with them; just use them as

% logical markup. This might change in the future.

%

\newcommand{\module}[1]{\texttt{#1}}

\newcommand{\keyword}[1]{\texttt{#1}}

\newcommand{\exception}[1]{\texttt{#1}}

\newcommand{\class}[1]{\texttt{#1}}

\newcommand{\function}[1]{\texttt{#1}}

\newcommand{\member}[1]{\texttt{#1}}

\newcommand{\method}[1]{\texttt{#1}}

\newcommand{\pytype}[1]{#1} % built-in Python type

\newcommand{\cfunction}[1]{\texttt{#1}}

\newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name

\newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global

\newcommand{\mailheader}[1]{{\py@smallsize\textsf{#1:}}}

\newcommand{\mimetype}[1]{{\py@smallsize\textsf{#1}}}

% The \! is a "negative thin space" in math mode.

\newcommand{\regexp}[1]{%

{\tiny$^{^\lceil}\!\!$%

{\py@defaultsize\code{#1}}%

$\!\rfloor\!$%

}}

\newcommand{\envvar}[1]{%

#1%

\index{#1}%

\index{environment variables!{#1}}%

}

\newcommand{\makevar}[1]{#1} % variable in a Makefile

\newcommand{\character}[1]{\samp{#1}}

% constants defined in Python modules or C headers, not language constants:

\newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic

\newcommand{\manpage}[2]{{\emph{#1}(#2)}}

\newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}

\newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}

\newcommand{\program}[1]{\strong{#1}}

\newcommand{\programopt}[1]{\strong{#1}}

% Note that \longprogramopt provides the '--'!

\newcommand{\longprogramopt}[1]{\strong{-{}-#1}}

% \ulink{link text}{URL}

\ifpdf

% The \noindent here is a hack -- we're forcing pdfTeX into

% horizontal mode since \pdfstartlink requires that.

\newcommand{\ulink}[2]{\noindent{%

\pdfstartlink attr{/Border [0 0 0]} user{/S /URI /URI (#2)}%

\py@LinkColor% color of the link text

#1%

\py@NormalColor% Turn it back off; these are declarative

\pdfendlink}% and don't appear bound to the current

}% formatting "box".

\else

\newcommand{\ulink}[2]{#1}

\fi

% cited titles: \citetitle{Title of Work}

% online: \citetitle[url-to-resource]{Title of Work}

\ifpdf

\newcommand{\citetitle}[2][\py@modulebadkey]{%

\ifx\py@modulebadkey#1\emph{#2}\else\ulink{\emph{#2}}{#1}\fi%

}

\else

\newcommand{\citetitle}[2][URL]{\emph{#2}}

\fi

% This version is being checked in for the historical record; it shows

% how I've managed to get some aspects of this to work. It will not

% be used in practice, so a subsequent revision will change things

% again. This version has problems, but shows how to do something

% that proved more tedious than I'd expected, so I don't want to lose

% the example completely.

%

\newcommand{\grammartoken}[1]{\texttt{#1}}

\newenvironment{productionlist}[1][\py@badkey]{

\def\optional##1{{\Large[}##1{\Large]}}

\def\production##1##2{\code{##1}&::=&\code{##2}\\}

\def\productioncont##1{& &\code{##1}\\}

\def\token##1{##1}

\let\grammartoken=\token

\parindent=2em

\indent

\begin{tabular}{lcl}

}{%

\end{tabular}

}

\newcommand{\py@noticelabel@note}{Note:}

\newcommand{\py@noticelabel@warning}{Warning:}

\newenvironment{notice}[1][note]{

\par\strong{\csname py@noticelabel@#1\endcsname}

}{}

\newcommand{\note}[1]{\strong{\py@noticelabel@note} #1}

\newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1}

% Deprecation stuff.

% Should be extended to allow an index / list of deprecated stuff. But

% there's a lot of stuff that needs to be done to make that automatable.

%

% First parameter is the release number that deprecates the feature, the

% second is the action the should be taken by users of the feature.

%

% Example:

% \deprecated{1.5.1}{Use \method{frobnicate()} instead.}

%

\newcommand{\deprecated}[2]{%

\strong{Deprecated since release #1.} #2\par}

% New stuff.

% This should be used to mark things which have been added to the

% development tree but that aren't in the release, but are documented.