summaryrefslogtreecommitdiffstats
path: root/Doc/texinputs/python.sty
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>1998-07-23 17:50:45 (GMT)
committerFred Drake <fdrake@acm.org>1998-07-23 17:50:45 (GMT)
commita488f30627b899dc86693f145bff704d0751f256 (patch)
tree2906b3818cd10d9f4aebdb533e86e4766193b96d /Doc/texinputs/python.sty
parent2fcadb2ffbac7c933066beaad278aeaf307b5cf5 (diff)
downloadcpython-a488f30627b899dc86693f145bff704d0751f256.zip
cpython-a488f30627b899dc86693f145bff704d0751f256.tar.gz
cpython-a488f30627b899dc86693f145bff704d0751f256.tar.bz2
Lots of new stuff for "module synopsis support." Public interface consists
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.
Diffstat (limited to 'Doc/texinputs/python.sty')
-rw-r--r--Doc/texinputs/python.sty202
1 files changed, 151 insertions, 51 deletions
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
index e5e2d4f..41db7ef 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -30,8 +30,8 @@
% Pad the number with '0' to 3 digits wide so no page name is a prefix
% of any other.
%
- \def\py@targetno#1{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1}
- \def\py@pageno{\py@targetno\thepage}
+ \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.
@@ -184,51 +184,8 @@
\endgroup%
}
-\newcommand{\reset@python}{
- \global\let\py@thisclass=\@undefined
- \global\let\py@thismodule=\@undefined
-}
-\reset@python
-
-% Augment the sectioning commands used to get our own font family in place,
-% and reset some internal data items:
-\renewcommand{\section}{\reset@python%
- \@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
+\newcommand{\py@modulebadkey}{{--just-some-junk--}}
%% Lots of index-entry generation support.
@@ -236,7 +193,7 @@
% 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 to use instead; it matches O'Reilly style more.
+% definition; it matches O'Reilly style more.
%
\newcommand{\py@idxcode}[1]{\texttt{#1}}
%\renewcommand{\py@idxcode}[1]{#1}
@@ -283,7 +240,7 @@
% Add the defining entry for a module
\newcommand{\py@modindex}[2]{%
- \global\def\py@thismodule{#1}
+ \renewcommand{\py@thismodule}{#1}
\setindexsubitem{(in module #1)}%
\index{#1@{\py@idxcode{#1}} (#2module)|textbf}%
\ifpy@UseModuleIndex%
@@ -311,6 +268,151 @@
}
+% 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.
@@ -383,7 +485,7 @@
% classes ----------------------------------------------------------------
% \begin{classdesc}{name}{constructor args}
\newenvironment{classdesc}[2]{
- \global\def\py@thisclass{#1}
+ \renewcommand{\py@thisclass}{#1}
\begin{fulllineitems}
\item[\code{\bfcode{#1}(\py@varvars{#2})}%
\withsubitem{(class in \py@thismodule)}{\ttindex{#1}}]
@@ -644,8 +746,6 @@
%
% \end{seealso}
-\newcommand{\py@modulebadkey}{{--just-some-junk--}}
-
\@ifundefined{pdfannotlink}{%
\newcommand{\py@seemodule}[3][\py@modulebadkey]{%
\ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%