From fb5e54d497928b13927cde425c243c150d18c674 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Thu, 19 Feb 1998 06:23:06 +0000
Subject: Mostly LaTeX style cleanup.
Use \newenvironment{envname} instead of \newcommand{\foo} &
\newcommand{\endfoo} (or \let\endfoo=...!) wherever reasonable.
Where {*desc} environment helper functions are not needed outside a
single environment definition, inline them.
Ensure that \seemodule{} and \seetext{} are only available within the
{seealso} environment.
Added "()" to the index entries for {funcdesc} and {cfuncdesc} environments.
Added {classdesc} environment which looks like the {funcdesc} environment
but doesn't add the parens in the index entry.
---
Doc/myformat.sty | 270 ++++++++++++++++++++++++++++++++-----------------------
1 file changed, 159 insertions(+), 111 deletions(-)
diff --git a/Doc/myformat.sty b/Doc/myformat.sty
index 1e4ef09..ba564c8 100644
--- a/Doc/myformat.sty
+++ b/Doc/myformat.sty
@@ -1,5 +1,5 @@
%
-% myformat.sty for the Python doc [updated to work with Latex2e]
+% myformat.sty for the Python doc [works only with with Latex2e]
%
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
@@ -22,8 +22,13 @@
% font, which makes for smaller PostScript and a font that more people
% like.
%
-\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual....}
+% The "fncychap" package is used to get the nice chapter headers. The
+% .sty file is distributed with Python, so you should not need to disable
+% it.
+%
+\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
\RequirePackage{times}\typeout{Using times fonts instead of Computer Modern.}
+\RequirePackage[Bjarne]{fncychap}\typeout{Using nice chapter headings.}
% for PDF output, use maximal compression, revise \label{} to support named
@@ -53,36 +58,42 @@
% Style parameters and macros used by most documents here
\raggedbottom
\sloppy
-\parindent = 0mm
-\parskip = 2mm
+\parindent = 0mm
+\parskip = 2mm
+\hbadness = 5000 % don't print trivial gripes
-% uncomment the following line if you have the fancyhdr package available:
-\pagestyle{empty} % start this way; change for
-\pagenumbering{roman} % ToC & chapters
+\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{\HeaderFamily}{\sffamily}
+
% Redefine the 'normal' header/footer style when using "fancyhdr" package:
\@ifundefined{fancyhf}{}{
- \fancypagestyle{normal}{%
- \fancyhf{}%
- \fancyfoot[LE,RO]{{\HeaderFamily\thepage}}%
- \fancyfoot[LO]{{\HeaderFamily\nouppercase{\rightmark}}}%
- \fancyfoot[RE]{{\HeaderFamily\nouppercase{\leftmark}}}%
- \renewcommand{\headrulewidth}{0pt}%
- \renewcommand{\footrulewidth}{0.4pt}%
+ % Use \pagestyle{normal} as the primary pagestyle for text.
+ \fancypagestyle{normal}{
+ \fancyhf{}
+ \fancyfoot[LE,RO]{{\HeaderFamily\thepage}}
+ \fancyfoot[LO]{{\HeaderFamily\nouppercase{\rightmark}}}
+ \fancyfoot[RE]{{\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]{{\HeaderFamily\thepage}}%
- \renewcommand{\headrulewidth}{0pt}%
- \renewcommand{\footrulewidth}{0.4pt}%
+ \fancypagestyle{plain}{
+ \fancyhf{}
+ \fancyfoot[LE,RO]{{\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.
- \renewcommand{\cleardoublepage}{\clearpage\if@twoside \ifodd\c@page\else
+ % gets the plain style and not the fancy style. This is described
+ % in the documentation for the fancyhdr package by Piet von Oostrum.
+ \renewcommand{\cleardoublepage}{
+ \clearpage\if@twoside \ifodd\c@page\else
\hbox{}
\thispagestyle{plain}
\newpage
@@ -127,9 +138,7 @@
\renewcommand{\verbatim}{\b@code\OldVerbatim}
\renewcommand{\endverbatim}{\OldEndVerbatim\e@code}
-% Augment the sectioning commands used to get our own font family in
-% place:
-\newcommand{\HeaderFamily}{\sffamily}
+% Augment the sectioning commands used to get our own font family in place:
\renewcommand{\section}{\@startsection {section}{1}{\z@}%
{-3.5ex \@plus -1ex \@minus -.2ex}%
{2.3ex \@plus.2ex}%
@@ -208,7 +217,7 @@
\newcommand{\opindex}[1]{\indexii{operator}{#1@{\idxcode{#1}}}}
\newcommand{\exindex}[1]{\indexii{exception}{#1@{\idxcode{#1}}}}
\newcommand{\obindex}[1]{\indexii{object}{#1}}
-\newcommand{\bifuncindex}[1]{\index{#1@{\idxcode{#1}} (built-in function)}}
+\newcommand{\bifuncindex}[1]{\index{#1@{\idxcode{#1()}} (built-in function)}}
% Add an index entry for a module
\newcommand{\refmodule}[2]{\index{#1@{\idxcode{#1}} (#2module)}}
@@ -235,60 +244,80 @@
% from user-level, fulllineitems should be called as an environment
-\def\fulllineitems{\list{}{\labelwidth \leftmargin \labelsep 0pt
-\rightmargin 0pt \topsep -\parskip \partopsep \parskip
-\itemsep -\parsep
-\let\makelabel\itemnewline}}
-\let\endfulllineitems\endlist
+\newenvironment{fulllineitems}{
+ \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
+ \rightmargin 0pt \topsep -\parskip \partopsep \parskip
+ \itemsep -\parsep
+ \let\makelabel=\itemnewline}
+}{\end{list}}
% cfuncdesc should be called as
% \begin{cfuncdesc}{type}{name}{arglist}
% ... description ...
% \end{cfuncdesc}
-\newcommand{\cfuncline}[3]{\item[\code{#1 \bfcode{#2}(\varvars{#3})}]\ttindex{#2}}
-\newcommand{\cfuncdesc}[3]{\fulllineitems\cfuncline{#1}{#2}{#3}}
-\let\endcfuncdesc\endfulllineitems
-
-\newcommand{\cvarline}[2]{\item[\code{#1 \bfcode{#2}}]\ttindex{#2}}
-\newcommand{\cvardesc}[2]{\fulllineitems\cvarline{#1}{#2}}
-\let\endcvardesc\endfulllineitems
-
-\newcommand{\ctypeline}[1]{\item[\bfcode{#1}]\ttindex{#1}}
-\newcommand{\ctypedesc}[1]{\fulllineitems\ctypeline{#1}}
-\let\endctypedesc\endfulllineitems
-
-% funcdesc should be called as an \begin{funcdesc} ... \end{funcdesc}
-\newcommand{\funcline}[2]{\funclineni{#1}{#2}\ttindex{#1}}
-\newcommand{\funcdesc}[2]{\fulllineitems\funcline{#1}{#2}}
-\let\endfuncdesc\endfulllineitems
-\newcommand{\optional}[1]{{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
+\newenvironment{cfuncdesc}[3]{%
+ \begin{fulllineitems}%
+ \item[\code{#1 \bfcode{#2}(\varvars{#3})}]%
+ \index{#2@{\idxcode{#2()}}}%
+}{\end{fulllineitems}}
+
+\newenvironment{cvardesc}[2]{%
+ \begin{fulllineitems}%
+ \item[\code{#1 \bfcode{#2}}]%
+ \index{#2@{\idxcode{#2}}}%
+}{\end{fulllineitems}}
+
+\newenvironment{ctypedesc}[1]{%
+ \begin{fulllineitems}%
+ \item[\bfcode{#1}]\ttindex{#1}
+}{\end{fulllineitems}}
+
+\newcommand{\funcline}[2]{\funclineni{#1}{#2}\ttindex{#1()}}
+\newenvironment{funcdesc}[2]{%
+ \begin{fulllineitems}%
+ \funcline{#1}{#2}%
+}{\end{fulllineitems}}
+
+\newcommand{\optional}[1]{%
+ {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
% similar to {funcdesc}, but doesn't add to the index
\newcommand{\funclineni}[2]{\item[\code{\bfcode{#1}(\varvars{#2})}]}
-\newcommand{\funcdescni}[2]{\fulllineitems\funclineni{#1}{#2}}
-\let\endfuncdescni\endfulllineitems
-
-% same for excdesc
-\newcommand{\excline}[1]{\item[\bfcode{#1}]\ttindex{#1}}
-\newcommand{\excdesc}[1]{\fulllineitems\excline{#1}}
-\let\endexcdesc\endfulllineitems
+\newenvironment{funcdescni}[2]{%
+ \begin{fulllineitems}%
+ \funclineni{#1}{#2}%
+}{\end{fulllineitems}}
+
+\newenvironment{classdesc}[2]{%
+ \begin{fulllineitems}%
+ \item[\code{\bfcode{#1}(\varvars{#2})}]%
+ \ttindex{#1}%
+ \def\baseclasses##1{}%
+}{\end{fulllineitems}}
+
+\newenvironment{excdesc}[1]{%
+ \begin{fulllineitems}%
+ \item[\bfcode{#1}]\ttindex{#1}%
+}{\end{fulllineitems}}
-% same for datadesc
\newcommand{\dataline}[1]{\datalineni{#1}\ttindex{#1}}
-\newcommand{\datadesc}[1]{\fulllineitems\dataline{#1}}
-\let\enddatadesc\endfulllineitems
+\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}]}
-\newcommand{\datadescni}[1]{\fulllineitems\datalineni{#1}}
-\let\enddatadescni\endfulllineitems
+\newenvironment{datadescni}[1]{%
+ \begin{fulllineitems}%
+ \datalineni{#1}%
+}{\end{fulllineitems}}
-
-% opcodedesc should be called as an \begin{opcodedesc} ... \end{opcodedesc}
-\newcommand{\opcodeline}[2]{\item[\bfcode{#1}\quad\var{#2}]}
-\newcommand{\opcodedesc}[2]{\fulllineitems\opcodeline{#1}{#2}}
-\let\endopcodedesc\endfulllineitems
+\newenvironment{opcodedesc}[2]{%
+ \begin{fulllineitems}%
+ \item[\bfcode{#1}\quad\var{#2}]%
+}{\end{fulllineitems}}
\let\nodename=\label
@@ -308,7 +337,7 @@
\newcommand{\code}[1]{{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}%
\mbox{\codefont{#1}}}}
-\newcommand{\bfcode}[1]{\code{\bfseries#1}} %bold-faced code font
+\newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
\newcommand{\kbd}[1]{\mbox{\tt #1}}
\newcommand{\key}[1]{\mbox{\tt #1}}
\newcommand{\samp}[1]{\mbox{`\code{#1}'}}
@@ -316,8 +345,8 @@
% italics, and won't get funky in code fragments when we play around
% with fonts.
\newcommand{\var}[1]{\mbox{\normalsize\textrm{\textit{#1\/}}}}
-\newcommand{\dfn}[1]{{\em #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]{\mbox{`\small\textsf{#1}'}}
@@ -351,10 +380,14 @@
\let\exception=\code
\let\class=\code
\let\function=\code
-\let\cfunction=\code
+\let\member=\code
\let\method=\code
-% constants defined in Python modules, not language constants:
+\let\cfunction=\code
+\let\ctype=\code
+\let\cdata=\code
+
+% constants defined in Python modules or C headers, not language constants:
\let\constant=\code
\newcommand{\manpage}[2]{{\emph{#1}(#2)}}
@@ -362,14 +395,31 @@
\newcommand{\program}[1]{\strong{#1}}
-\newenvironment{tableii}[4]{\begin{center}\def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}\begin{tabular}{#1}\hline#3\\
-\hline}{\hline\end{tabular}\end{center}}
+\newenvironment{tableii}[4]{%
+ \begin{center}%
+ \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+ \begin{tabular}{#1}\hline#3\\ \hline%
+}{%
+ \hline%
+ \end{tabular}%
+ \end{center}%
+}
-\newenvironment{tableiii}[5]{\begin{center}\def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}\begin{tabular}{#1}\hline#3\\
-\hline}{\hline\end{tabular}\end{center}}
+\newenvironment{tableiii}[5]{%
+ \begin{center}%
+ \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+ \begin{tabular}{#1}\hline#3\\%
+ \hline%
+}{%
+ \hline%
+ \end{tabular}%
+ \end{center}%
+}
-\newcommand{\itemnewline}[1]{\@tempdima\linewidth
-\advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}}
+\newcommand{\itemnewline}[1]{%
+ \@tempdima\linewidth%
+ \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
+}
\newcommand{\sectcode}[1]{{\sectcodefont{#1}}}
@@ -380,24 +430,23 @@
% \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book
% \end{seealso}
-\newenvironment{seealso}[0]{\strong{See Also:}\par}{\par}
-\newcommand{\seemodule}[2]{\ref{module-#1}:%
- \quad Module \module{#1}\quad(#2)}
-\newcommand{\seebimodule}[2]{\ref{module-#1}:%
- \quad Built-in Module \module{#1}\quad(#2)}
-\newcommand{\seestmodule}[2]{\ref{module-#1}:%
- \quad Standard Module \module{#1}\quad(#2)}
-\newcommand{\seetext}[1]{\par{#1}}
+\newenvironment{seealso}[0]{
+ \strong{See Also:}\par
+ % These should only be defined within the {seealso} environment:
+ \def\seemodule##1##2{\ref{module-##1}:\quad Module \module{##1}\quad (##2)}
+ \def\seetext##1{\par{##1}}
+}{\par}
+
% Fix the theindex environment to add an entry to the Table of
% Contents; this is much nicer than just having to jump to the end of
% the book and flip around, especially with multiple indexes.
%
\let\OldTheindex=\theindex
-\renewcommand{\theindex}{%
- \cleardoublepage%
- \OldTheindex%
- \addcontentsline{toc}{chapter}{\indexname}%
+\renewcommand{\theindex}{
+ \cleardoublepage
+ \OldTheindex
+ \addcontentsline{toc}{chapter}{\indexname}
}
% Use a similar trick to catch the end of the {abstract} environment,
@@ -461,29 +510,30 @@
% Change the title page to look a bit better, and fit in with the
% fncychap ``Bjarne'' style a bit better.
%
-\renewcommand{\maketitle}{\begin{titlepage}%
- \let\footnotesize\small
- \let\footnoterule\relax
- \@ifundefined{ChTitleVar}{}{%
- \mghrulefill{\RW}}%
- \@ifundefined{pdfinfo}{}{
- \pdfinfo
- author {\@author}
- title {\@title}
- }
- \begin{flushright}%
- {\rm\Huge\HeaderFamily \@title \par}%
- {\em\LARGE\HeaderFamily \@release \par}
- \vfill
- {\LARGE\HeaderFamily \@author \par}
- \vfill\vfill
- {\large
- \@date \par
- \vskip 3em
- \@authoraddress \par
- }%
- \end{flushright}%\par
- \@thanks
+\renewcommand{\maketitle}{%
+ \begin{titlepage}%
+ \let\footnotesize\small
+ \let\footnoterule\relax
+ \@ifundefined{ChTitleVar}{}{%
+ \mghrulefill{\RW}}%
+ \@ifundefined{pdfinfo}{}{
+ \pdfinfo
+ author {\@author}
+ title {\@title}
+ }
+ \begin{flushright}%
+ {\rm\Huge\HeaderFamily \@title \par}%
+ {\em\LARGE\HeaderFamily \@release \par}
+ \vfill
+ {\LARGE\HeaderFamily \@author \par}
+ \vfill\vfill
+ {\large
+ \@date \par
+ \vskip 3em
+ \@authoraddress \par
+ }%
+ \end{flushright}%\par
+ \@thanks
\end{titlepage}%
\setcounter{footnote}{0}%
\let\thanks\relax\let\maketitle\relax
@@ -502,7 +552,6 @@
% modules'' at the top of module-documentation chapters. But it might
% require a completely new environment, perhaps based on {list}.
-% Leave the rest as-is:
\newif\if@minitocprinted
\newcommand{\suppressminitoc}{\@minitocprintedtrue}
\@ifundefined{minitoc}{
@@ -547,7 +596,6 @@
% This sets up the fancy chapter headings that make the documents look
% at least a little better than the usual LaTeX output.
%
-\RequirePackage[Bjarne]{fncychap}
\@ifundefined{ChTitleVar}{}{
\ChNameVar{\raggedleft\normalsize\HeaderFamily}
\ChNumVar{\raggedleft \bfseries\Large\HeaderFamily}
--
cgit v0.12