Skip to content

C
cpython
Commit db414910 authored by Fred Drake's avatar Fred Drake
Browse files
Options

Add comments about several of the environments. 

Cleaned up some problems that caused minor warnings.

Added environments for object methods and members, with non-indexing variants.
This includes reduced use of the indexsubitem setting, allowing more robust
index generation.

Removed some unused definitions.
parent cabebaa5
Hide whitespace changes
Inline Side-by-side
Showing with 137 additions and 57 deletions
Doc/texinputs/python.sty
View file @ db414910
......@@ -9,6 +9,9 @@
% for PDF output, use maximal compression & a lot of other stuff
% (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)
%
\newif\if@doing@page@targets
\@doing@page@targetsfalse
\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
\let\LinkColor=\relax
\let\NormalColor=\relax
......@@ -51,11 +54,9 @@
\unvbox \@begindvibox
\@hyperfixhead
}
\def\hyperpageanchor{\pdfdest name{page.\thepage}}
\let\HYPERPAGEANCHOR\hyperpageanchor
\def\@hyperfixhead{%
\let\H@old@thehead\@thehead
\gdef\@foo{\pdfdest name{page.\thepage} fit}%
\gdef\@foo{\if@doing@page@targets\pdfdest name{page.\thepage} fit\fi}%
\expandafter\ifx\expandafter\@empty\H@old@thehead
\def\H@old@thehead{\hfil}\fi
\def\@thehead{\@foo\relax\H@old@thehead}%
......@@ -175,8 +176,16 @@
\endgroup%
}
% Augment the sectioning commands used to get our own font family in place:
\renewcommand{\section}{\@startsection {section}{1}{\z@}%
\newcommand{\reset@python}{
\global\let\@thisclass=\@undefined
\global\let\@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\HeaderFamily}}
......@@ -278,10 +287,6 @@
\addcontentsline{toc}{chapter}{\indexname}
}
% these should dump an error or warning to the transcript
\newcommand{\@thismodule}{$<<$ ERROR - NO CURRENT MODULE $>>$}
\newcommand{\@thisclass}{$<<$ ERROR - NO CURRENT CLASS $>>$}
\newcommand{\makemodindex}{
\newwrite\modindexfile
\openout\modindexfile=mod\jobname.idx
......@@ -290,8 +295,8 @@
% Add the defining entry for a module
\newcommand{\@modindex}[2]{%
\renewcommand{\@thismodule}{#1}
\setindexsubitem{(in module \@thismodule)}%
\global\def\@thismodule{#1}
\setindexsubitem{(in module #1)}%
\index{#1@{\idxcode{#1}} (#2module)|textbf}%
\if@UseModuleIndex%
\write\modindexfile{\protect\indexentry{#1@{\tt #1}}{\thepage}}%
......@@ -327,73 +332,149 @@
\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.
\newcommand{\optional}[1]{%
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
% cfuncdesc should be called as
% C functions ------------------------------------------------------------
% \begin{cfuncdesc}{type}{name}{arglist}
% ... description ...
% \end{cfuncdesc}
\newenvironment{cfuncdesc}[3]{%
\begin{fulllineitems}%
\item[\code{#1 \bfcode{#2}(\varvars{#3})}]%
\index{#2@{\idxcode{#2()}}}%
\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}}}%
% C variables ------------------------------------------------------------
% \begin{cvardesc}{type}{name}
\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}
% 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}%
\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})}]}
\newenvironment{funcdescni}[2]{%
\begin{fulllineitems}%
\funclineni{#1}{#2}%
\newenvironment{funcdescni}[2]{
\begin{fulllineitems}
\funclineni{#1}{#2}
}{\end{fulllineitems}}
% classes ----------------------------------------------------------------
% \begin{classdesc}{name}{constructor args}
\newenvironment{classdesc}[2]{
\global\def\@thisclass{#1}
\begin{fulllineitems}
\item[\code{\bfcode{#1}(\varvars{#2})}%
\withsubitem{(class in \@thismodule)}{\ttindex{#1}}]
\def\baseclasses##1{}
}{\end{fulllineitems}}
\newenvironment{classdesc}[2]{%
\renewcommand{\@thisclass}{#1}%
\begin{fulllineitems}%
\item[\code{\bfcode{#1}(\varvars{#2})}]%
\withsubitem{(class in \@thismodule)}{\ttindex{#1}}%
\def\baseclasses##1{}%
\newcommand{\@classbadkey}{--bad current class--}
\let\@classbadkey=\@undefined
% object method ----------------------------------------------------------
% \begin{methoddesc}[classname]{methodname}{args}
\newcommand{\methodline}[3][\@classbadkey]{
\methodlineni{#2}{#3}
\ifx#1\@undefined
\withsubitem{(\@thisclass\ method)}{\ttindex{#2()}}
\else
\withsubitem{(#1 method)}{\ttindex{#2()}}
\fi
}
\newenvironment{methoddesc}[3][\@classbadkey]{
\begin{fulllineitems}
\ifx#1\@undefined
\methodline{#2}{#3}
\else
\def\@thisclass{#1}
\methodline[#1]{#2}{#3}
\fi
}{\end{fulllineitems}}
\newenvironment{excdesc}[1]{%
\begin{fulllineitems}%
\item[\bfcode{#1}]\ttindex{#1}%
% similar to {methoddesc}, but doesn't add to the index
% (never actually uses the optional argument)
\newcommand{\methodlineni}[3][\@classbadkey]{%
\item[\code{\bfcode{#2}(\varvars{#3})}]}
\newenvironment{methoddescni}[3][\@classbadkey]{
\begin{fulllineitems}
\methodlineni{#2}{#3}
}{\end{fulllineitems}}
% object data attribute --------------------------------------------------
% \begin{memberdesc}[classname]{membername}
\newcommand{\memberline}[2][\@classbadkey]{%
\ifx#1\@undefined
\memberlineni{#2}
\withsubitem{(\@thisclass\ attribute)}{\ttindex{#2()}}
\else
\memberlineni{#2}
\withsubitem{(#1 attribute)}{\ttindex{#2()}}
\fi
}
\newenvironment{memberdesc}[2][\@classbadkey]{
\begin{fulllineitems}
\ifx#1\@undefined
\memberline{#2}
\else
\def\@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][\@classbadkey]{\item[\bfcode{#2}]}
\newenvironment{memberdescni}[2][\@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}%
\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}]}
\newenvironment{datadescni}[1]{%
\begin{fulllineitems}%
\datalineni{#1}%
\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
\newenvironment{datadescni}[1]{
\begin{fulllineitems}
\datalineni{#1}
}{\end{fulllineitems}}
\newenvironment{opcodedesc}[2]{%
\begin{fulllineitems}%
\item[\bfcode{#1}\quad\var{#2}]%
% bytecode instruction ---------------------------------------------------
% \begin{opcodedesc}{name}{var}
% -- {var} may be {}
\newenvironment{opcodedesc}[2]{
\begin{fulllineitems}
\item[\bfcode{#1}\quad\var{#2}]
}{\end{fulllineitems}}
......@@ -432,13 +513,13 @@
% Use this def/redef approach for \url{} since hyperref defined this already,
% but only if we actually used hyperref:
\@ifundefined{pdfannotlink}{%
\newcommand{\pythonurl}[1]{\mbox{\small\textsf{#1}}}%
\@ifundefined{pdfannotlink}{
\newcommand{\pythonurl}[1]{\mbox{\small\textsf{#1}}}
}{
\newcommand{\pythonurl}[1]{{%
\pdfannotlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
\LinkColor% color of the link text
\mbox{\small\textsf{#1}}%
{\small\textsf{#1}}%
\NormalColor% Turn it back off; these are declarative
\pdfendlink}% and don't appear bound to the current
}% formatting "box".
......@@ -544,7 +625,6 @@
%
% \end{seealso}
\newif\if@keyedmodule\@keyedmodulefalse
\newcommand{\@modulebadkey}{{--just-some-junk--}}
\@ifundefined{pdfannotlink}{%
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7