mirror of
https://github.com/python/cpython.git
synced 2025-07-23 03:05:38 +00:00
a488f30627
of three macros, one which replaces some of the current conventions used in the module sections: \declaremodule: Requires two parameters: module type (standard, builtin, extension), and the module name. An optional parameter should be given as the basis for the module's "key" used for linking to or referencing the section. The "key" should only be given if the module's name contains underscores, and should be the name with the underscore's stripped. This should be the first thing after the \section used to introduce the module. \modulesynopsis: Requires a single parameter: a short, one-liner description of the module that can be used as part of the chapter introduction. This should probably be placed just after the \declaremodule, but may be placed anywhere in the same section. \localmoduletable: No parameters. If a .syn file exists for the current chapter (or for the entire document in howto docs), a synopsistable is created with the contents loaded from the .syn file. Some re-organization due to module synopsis support. Some \def's changed to \newcommand's.
825 lines
26 KiB
TeX
825 lines
26 KiB
TeX
%
|
|
% python.sty for the Python docummentation [works only with with Latex2e]
|
|
%
|
|
|
|
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
|
|
\ProvidesPackage{python}
|
|
[1998/01/11 LaTeX package (Python markup)]
|
|
|
|
% 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
|
|
|
|
\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
|
|
\else
|
|
\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
|
|
% 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}{%
|
|
\pdfannotlink attr{/Border [0 0 0]} goto name{page\my@pageno}%
|
|
\py@LinkColor#2\py@NormalColor%
|
|
\pdfendlink%
|
|
}{#3}%
|
|
}
|
|
\AtEndDocument{
|
|
\InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{}
|
|
}
|
|
\newcommand{\py@target}[1]{%
|
|
\ifpy@doing@page@targets%
|
|
{\pdfdest name{#1} fit}%
|
|
\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
|
|
\@ifundefined{paperheight}{
|
|
\textheight 9in
|
|
}{
|
|
\textheight \paperheight
|
|
\advance\textheight by -2in
|
|
}
|
|
|
|
\oddsidemargin 0pt
|
|
\evensidemargin \oddsidemargin
|
|
\marginparwidth 0.5in
|
|
|
|
\@ifundefined{paperwidth}{
|
|
\textwidth 6.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
|
|
\setcounter{secnumdepth}{1}
|
|
|
|
% Use this to set the font family for headers and other decor:
|
|
\newcommand{\py@HeaderFamily}{\sffamily}
|
|
|
|
% 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.
|
|
|
|
% Variable used by begin code command
|
|
\newlength{\py@codewidth}
|
|
|
|
\newcommand{\py@examplevspace}{2mm}
|
|
\newcommand{\py@exampleindent}{1cm}
|
|
|
|
\let\py@OldVerbatim=\verbatim
|
|
\let\py@OldEndVerbatim=\endverbatim
|
|
\renewcommand{\verbatim}{%
|
|
\begingroup%
|
|
\setlength{\parindent}\py@exampleindent%
|
|
% Calculate the text width for the minipage:
|
|
\setlength{\py@codewidth}{\linewidth}%
|
|
\addtolength{\py@codewidth}{-\parindent}%
|
|
%
|
|
\par%
|
|
\vspace\py@examplevspace%
|
|
\indent%
|
|
\begin{minipage}[t]{\py@codewidth}%
|
|
\small%
|
|
\py@OldVerbatim%
|
|
}
|
|
\renewcommand{\endverbatim}{%
|
|
\py@OldEndVerbatim%
|
|
\end{minipage}%
|
|
\endgroup%
|
|
}
|
|
|
|
|
|
\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]{\withsubitem{(built-in function)}{\ttindex{#1()}}}
|
|
|
|
% 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 }}
|
|
|
|
% 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%
|
|
\write\modindexfile{\protect\indexentry{#1@{\tt #1}}{\thepage}}%
|
|
\fi%
|
|
}
|
|
|
|
% built-in & Python modules in the main distribution
|
|
\newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }}
|
|
\newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }}
|
|
|
|
% Python & extension modules outside the main distribution
|
|
\newcommand{\modindex}[1]{\py@modindex{#1}{}}
|
|
\newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }}
|
|
|
|
% Additional string for an index entry
|
|
\newcommand{\index@subitem}{}
|
|
\newcommand{\setindexsubitem}[1]{\renewcommand{\index@subitem}{#1}}
|
|
\newcommand{\ttindex}[1]{\index{#1@{\py@idxcode{#1}} \index@subitem}}
|
|
|
|
\newcommand{\withsubitem}[2]{%
|
|
\begingroup%
|
|
\def\index@subitem{#1}#2%
|
|
\endgroup%
|
|
}
|
|
|
|
|
|
% Module synopsis processing -----------------------------------------------
|
|
%
|
|
\newcommand{\py@standardIndexModule}[1]{\stmodindex{#1}}
|
|
\newcommand{\py@builtinIndexModule}[1]{\bimodindex{#1}}
|
|
\newcommand{\py@extensionIndexModule}[1]{\exmodindex{#1}}
|
|
\newcommand{\py@IndexModule}[1]{\modindex{#1}}
|
|
|
|
\newif\ifpy@HaveModSynopsis\py@HaveModSynopsisfalse
|
|
\newif\ifpy@ModSynopsisFileIsOpen\py@ModSynopsisFileIsOpenfalse
|
|
|
|
% \declaremodule[key]{type}{name}
|
|
\newcommand{\declaremodule}[3][\py@modulebadkey]{
|
|
\py@openModSynopsisFile
|
|
\renewcommand{\py@thismoduletype}{#2}
|
|
\csname py@#2IndexModule\endcsname{#3}
|
|
\ifx\py@modulebadkey#1
|
|
\renewcommand{\py@thismodulekey}{#3}
|
|
\else
|
|
\renewcommand{\py@thismodulekey}{#1}
|
|
\fi
|
|
\label{module-\py@thismodulekey}
|
|
\py@HaveModSynopsistrue
|
|
}
|
|
|
|
|
|
\newcommand{\py@defsynopsis}{Module has no synopsis.}
|
|
\newcommand{\py@modulesynopsis}{\py@defsynopsis}
|
|
\newcommand{\modulesynopsis}[1]{
|
|
\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}
|
|
|
|
\newcommand{\localmoduletable}{
|
|
\IfFileExists{\py@ModSynopsisFilename}{
|
|
\begin{synopsistable}
|
|
\input{\py@ModSynopsisFilename}
|
|
\end{synopsistable}
|
|
}{}
|
|
}
|
|
|
|
\@ifundefined{pdfoutput}{
|
|
\newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}
|
|
}{
|
|
\newcommand{\py@ModSynopsisSummary}[4]{
|
|
{\pdfannotlink attr{/Border [0 0 0]} goto name{label-module-#1}
|
|
\py@LinkColor \bfcode{#2} \py@NormalColor
|
|
\pdfendlink}& #4\\}
|
|
}
|
|
\newenvironment{synopsistable}{
|
|
% key, name, type, synopsis
|
|
\let\modulesynopsis=\py@ModSynopsisSummary
|
|
\begin{tabular}{ll}
|
|
}{
|
|
\end{tabular}
|
|
}
|
|
%
|
|
% --------------------------------------------------------------------------
|
|
|
|
|
|
\newcommand{\py@thisclass}{}
|
|
\newcommand{\py@thismodule}{}
|
|
\newcommand{\py@thismodulekey}{}
|
|
\newcommand{\py@thismoduletype}{}
|
|
|
|
\newcommand{\py@reset}{
|
|
\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}}
|
|
|
|
|
|
% 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.
|
|
%
|
|
\newenvironment{fulllineitems}{
|
|
\begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
|
|
\rightmargin 0pt \topsep -\parskip \partopsep \parskip
|
|
\itemsep -\parsep
|
|
\let\makelabel=\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}}}
|
|
%
|
|
\newcommand{\optional}[1]{%
|
|
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
|
|
|
|
% C functions ------------------------------------------------------------
|
|
% \begin{cfuncdesc}{type}{name}{arglist}
|
|
\newenvironment{cfuncdesc}[3]{
|
|
\begin{fulllineitems}
|
|
\item[\code{#1 \bfcode{#2}(\py@varvars{#3})}\index{#2@{\py@idxcode{#2()}}}]
|
|
}{\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}{typedef name}
|
|
\newenvironment{ctypedesc}[1]{
|
|
\begin{fulllineitems}
|
|
\item[\bfcode{#1}\ttindex{#1}]
|
|
}{\end{fulllineitems}}
|
|
|
|
% simple functions (not methods) -----------------------------------------
|
|
% \begin{funcdesc}{name}{args}
|
|
\newcommand{\funcline}[2]{\funclineni{#1}{#2}\ttindex{#1()}}
|
|
\newenvironment{funcdesc}[2]{
|
|
\begin{fulllineitems}
|
|
\funcline{#1}{#2}
|
|
}{\end{fulllineitems}}
|
|
|
|
% similar to {funcdesc}, but doesn't add to the index
|
|
\newcommand{\funclineni}[2]{\item[\code{\bfcode{#1}(\py@varvars{#2})}]}
|
|
\newenvironment{funcdescni}[2]{
|
|
\begin{fulllineitems}
|
|
\funclineni{#1}{#2}
|
|
}{\end{fulllineitems}}
|
|
|
|
% classes ----------------------------------------------------------------
|
|
% \begin{classdesc}{name}{constructor args}
|
|
\newenvironment{classdesc}[2]{
|
|
\renewcommand{\py@thisclass}{#1}
|
|
\begin{fulllineitems}
|
|
\item[\code{\bfcode{#1}(\py@varvars{#2})}%
|
|
\withsubitem{(class in \py@thismodule)}{\ttindex{#1}}]
|
|
}{\end{fulllineitems}}
|
|
|
|
|
|
\let\py@classbadkey=\@undefined
|
|
|
|
% object method ----------------------------------------------------------
|
|
% \begin{methoddesc}[classname]{methodname}{args}
|
|
\newcommand{\methodline}[3][\py@classbadkey]{
|
|
\methodlineni{#2}{#3}
|
|
\ifx#1\@undefined
|
|
\withsubitem{(\py@thisclass\ method)}{\ttindex{#2()}}
|
|
\else
|
|
\withsubitem{(#1 method)}{\ttindex{#2()}}
|
|
\fi
|
|
}
|
|
\newenvironment{methoddesc}[3][\py@classbadkey]{
|
|
\begin{fulllineitems}
|
|
\ifx#1\@undefined
|
|
\methodline{#2}{#3}
|
|
\else
|
|
\def\py@thisclass{#1}
|
|
\methodline[#1]{#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]{%
|
|
\item[\code{\bfcode{#2}(\py@varvars{#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}
|
|
\withsubitem{(\py@thisclass\ attribute)}{\ttindex{#2}}
|
|
\else
|
|
\memberlineni{#2}
|
|
\withsubitem{(#1 attribute)}{\ttindex{#2}}
|
|
\fi
|
|
}
|
|
\newenvironment{memberdesc}[2][\py@classbadkey]{
|
|
\begin{fulllineitems}
|
|
\ifx#1\@undefined
|
|
\memberline{#2}
|
|
\else
|
|
\def\py@thisclass{#1}
|
|
\memberline[#1]{#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}
|
|
% -- need support for constructor; maybe use optional parameter?
|
|
\newenvironment{excdesc}[1]{
|
|
\begin{fulllineitems}
|
|
\item[\bfcode{#1}\ttindex{#1}]
|
|
}{\end{fulllineitems}}
|
|
|
|
% Module data or constants: ----------------------------------------------
|
|
% \begin{datadesc}{name}
|
|
\newcommand{\dataline}[1]{\datalineni{#1}\ttindex{#1}}
|
|
\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}}
|
|
|
|
% Also for consistency: spell Python "Python", not "python"!
|
|
|
|
% code is the most difficult one...
|
|
\newcommand{\code}[1]{{\@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{\kbd}[1]{\code{#1}}
|
|
\newcommand{\samp}[1]{`\code{#1}'}
|
|
% This weird definition of \var{} allows it to always appear in roman
|
|
% italics, and won't get funky in code fragments when we play around
|
|
% with fonts.
|
|
\newcommand{\var}[1]{\normalsize\textrm{\textit{#1\/}}}
|
|
\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]{`{\small\textsf{#1}}'}
|
|
|
|
% Use this def/redef approach for \url{} since hyperref defined this already,
|
|
% but only if we actually used hyperref:
|
|
\@ifundefined{pdfannotlink}{
|
|
\newcommand{\py@url}[1]{\mbox{\small\textsf{#1}}}
|
|
}{
|
|
\newcommand{\py@url}[1]{{%
|
|
\pdfannotlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
|
|
\py@LinkColor% color of the link text
|
|
\mbox{\small\textsf{#1}}%
|
|
\py@NormalColor% Turn it back off; these are declarative
|
|
\pdfendlink}% and don't appear bound to the current
|
|
}% formatting "box".
|
|
}
|
|
\let\url=\py@url
|
|
\newcommand{\email}[1]{{\small\textsf{#1}}}
|
|
\newcommand{\newsgroup}[1]{{\small\textsf{#1}}}
|
|
|
|
\newcommand{\py@varvars}[1]{{\def\,{\/{\char`\,}}\var{#1}}}
|
|
% let's see if this breaks anything now; we may be able to simplify...
|
|
\renewcommand{\py@varvars}[1]{\var{#1}}
|
|
|
|
% I'd really like to get rid of this!
|
|
\newif\iftexi\texifalse
|
|
|
|
% 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{\mimetype}[1]{{\small\textsf{#1}}}
|
|
% The \! is a "negative thin space" in math mode.
|
|
\newcommand{\regexp}[1]{%
|
|
{\tiny$^{^\lceil}\!\!$%
|
|
{\normalsize\code{#1}}%
|
|
$\!\rfloor\!$%
|
|
}}
|
|
\newcommand{\envvar}[1]{%
|
|
\$#1% $ <-- bow to font-lock 3 times!
|
|
\index{#1@{\$#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{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
|
|
\newcommand{\program}[1]{\strong{#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}
|
|
|
|
|
|
\newenvironment{tableii}[4]{%
|
|
\begin{center}%
|
|
\def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
|
|
\begin{tabular}{#1}\strong{#3}&\strong{#4} \\ \hline%
|
|
}{%
|
|
\end{tabular}%
|
|
\end{center}%
|
|
}
|
|
|
|
\newenvironment{tableiii}[5]{%
|
|
\begin{center}%
|
|
\def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
|
|
\begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\ \hline%
|
|
}{%
|
|
\end{tabular}%
|
|
\end{center}%
|
|
}
|
|
|
|
\newcommand{\itemnewline}[1]{%
|
|
\@tempdima\linewidth%
|
|
\advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
|
|
}
|
|
|
|
% Define \itembreak: force the text after an item to start on a new line
|
|
\newcommand{\itembreak}{%
|
|
\mbox{}%
|
|
\\*[0mm]%
|
|
}
|
|
|
|
% Define \itemjoin: some negative vspace to join two items together
|
|
\newcommand{\itemjoin}{%
|
|
\mbox{}%
|
|
\vspace{-\itemsep}%
|
|
\vspace{-\parsep}%
|
|
}
|
|
|
|
% Cross-referencing (AMK, new impl. FLD)
|
|
% Sample usage:
|
|
% \begin{seealso}
|
|
% \seemodule{rand}{Uniform random number generator}; % Module xref
|
|
% \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book
|
|
%
|
|
% % A funky case: module name contains '_'; have to supply an optional key
|
|
% \seemodule[copyreg]{copy_reg}{pickle interface constructor registration}
|
|
%
|
|
% \end{seealso}
|
|
|
|
\@ifundefined{pdfannotlink}{%
|
|
\newcommand{\py@seemodule}[3][\py@modulebadkey]{%
|
|
\ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
|
|
\ref{module-\py@modulekey}:\quad %
|
|
Module \module{#2}%
|
|
\quad (#3)%
|
|
}
|
|
}{\newcommand{\py@seemodule}[3][\py@modulebadkey]{%
|
|
\ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
|
|
\ref{module-\py@modulekey}:\quad %
|
|
{\pdfannotlink attr{/Border [0 0 0]} goto name{label-module-\py@modulekey}%
|
|
\py@LinkColor Module \module{#2} \py@NormalColor%
|
|
\pdfendlink%
|
|
}%
|
|
\quad (#3)%
|
|
}
|
|
}
|
|
\newenvironment{seealso}[0]{
|
|
\strong{See Also:}\par
|
|
\def\seetext##1{\par{##1}}
|
|
\let\seemodule=\py@seemodule
|
|
}{\par}
|
|
|
|
|
|
% Allow the release number to be specified independently of the
|
|
% \date{}. This allows the date to reflect the document's date and
|
|
% release to specify the Python release that is documented.
|
|
%
|
|
\newcommand{\py@release}{}
|
|
\newcommand{\version}{}
|
|
\newcommand{\releasename}{Release}
|
|
\newcommand{\release}[1]{%
|
|
\renewcommand{\py@release}{\releasename\space\version}%
|
|
\renewcommand{\version}{#1}}
|
|
|
|
% Allow specification of the author's address separately from the
|
|
% author's name. This can be used to format them differently, which
|
|
% is a good thing.
|
|
%
|
|
\newcommand{\py@authoraddress}{}
|
|
\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
|
|
\let\developersaddress=\authoraddress
|
|
\let\developer=\author
|
|
\let\developers=\author
|
|
|
|
% This sets up the fancy chapter headings that make the documents look
|
|
% at least a little better than the usual LaTeX output.
|
|
%
|
|
\@ifundefined{ChTitleVar}{}{
|
|
\ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
|
|
\ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
|
|
\ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
|
|
% This creates chapter heads without the leading \vspace*{}:
|
|
\def\@makechapterhead#1{%
|
|
{\parindent \z@ \raggedright \normalfont
|
|
\ifnum \c@secnumdepth >\m@ne
|
|
\DOCH
|
|
\fi
|
|
\interlinepenalty\@M
|
|
\DOTI{#1}
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
% Definition lists; requested by AMK for HOWTO documents. Probably useful
|
|
% elsewhere as well, so keep in in the general style support.
|
|
%
|
|
\newenvironment{definitions}{%
|
|
\begin{description}%
|
|
\def\term##1{\item[##1]\itembreak}
|
|
}{%
|
|
\end{description}%
|
|
}
|
|
|
|
% Tell TeX about pathological hyphenation cases:
|
|
\hyphenation{Base-HTTP-Re-quest-Hand-ler}
|