Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 6cb7149

Browse files
freddrakefreddrake
committed
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.
1 parent 235e6b1 commit 6cb7149

1 file changed

Lines changed: 137 additions & 57 deletions

File tree

‎Doc/texinputs/python.sty‎

Lines changed: 137 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99
% for PDF output, use maximal compression & a lot of other stuff
1010
% (test for PDF recommended by Tanmoy Bhattacharya <[email protected]>)
1111
%
12+
\newif\if@doing@page@targets
13+
\@doing@page@targetsfalse
14+
1215
\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
1316
\let\LinkColor=\relax
1417
\let\NormalColor=\relax
@@ -51,11 +54,9 @@
5154
\unvbox \@begindvibox
5255
\@hyperfixhead
5356
}
54-
\def\hyperpageanchor{\pdfdest name{page.\thepage}}
55-
\let\HYPERPAGEANCHOR\hyperpageanchor
5657
\def\@hyperfixhead{%
5758
\let\H@old@thehead\@thehead
58-
\gdef\@foo{\pdfdest name{page.\thepage} fit}%
59+
\gdef\@foo{\if@doing@page@targets\pdfdest name{page.\thepage} fit\fi}%
5960
\expandafter\ifx\expandafter\@empty\H@old@thehead
6061
\def\H@old@thehead{\hfil}\fi
6162
\def\@thehead{\@foo\relax\H@old@thehead}%
@@ -175,8 +176,16 @@
175176
\endgroup%
176177
}
177178

178-
% Augment the sectioning commands used to get our own font family in place:
179-
\renewcommand{\section}{\@startsection {section}{1}{\z@}%
179+
\newcommand{\reset@python}{
180+
\global\let\@thisclass=\@undefined
181+
\global\let\@thismodule=\@undefined
182+
}
183+
\reset@python
184+
185+
% Augment the sectioning commands used to get our own font family in place,
186+
% and reset some internal data items:
187+
\renewcommand{\section}{\reset@python%
188+
\@startsection {section}{1}{\z@}%
180189
{-3.5ex \@plus -1ex \@minus -.2ex}%
181190
{2.3ex \@plus.2ex}%
182191
{\reset@font\Large\HeaderFamily}}
@@ -278,10 +287,6 @@
278287
\addcontentsline{toc}{chapter}{\indexname}
279288
}
280289

281-
% these should dump an error or warning to the transcript
282-
\newcommand{\@thismodule}{$<<$ ERROR - NO CURRENT MODULE $>>$}
283-
\newcommand{\@thisclass}{$<<$ ERROR - NO CURRENT CLASS $>>$}
284-
285290
\newcommand{\makemodindex}{
286291
\newwrite\modindexfile
287292
\openout\modindexfile=mod\jobname.idx
@@ -290,8 +295,8 @@
290295

291296
% Add the defining entry for a module
292297
\newcommand{\@modindex}[2]{%
293-
\renewcommand{\@thismodule}{#1}
294-
\setindexsubitem{(in module \@thismodule)}%
298+
\global\def\@thismodule{#1}
299+
\setindexsubitem{(in module #1)}%
295300
\index{#1@{\idxcode{#1}} (#2module)|textbf}%
296301
\if@UseModuleIndex%
297302
\write\modindexfile{\protect\indexentry{#1@{\tt #1}}{\thepage}}%
@@ -327,73 +332,149 @@
327332
\let\makelabel=\itemnewline}
328333
}{\end{list}}
329334

335+
% \optional is mostly for use in the arguments parameters to the various
336+
% {*desc} environments defined below, but may be used elsewhere. Known to
337+
% be used in the debugger chapter.
338+
\newcommand{\optional}[1]{%
339+
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
330340

331-
% cfuncdesc should be called as
341+
% C functions ------------------------------------------------------------
332342
% \begin{cfuncdesc}{type}{name}{arglist}
333-
% ... description ...
334-
% \end{cfuncdesc}
335-
\newenvironment{cfuncdesc}[3]{%
336-
\begin{fulllineitems}%
337-
\item[\code{#1 \bfcode{#2}(\varvars{#3})}]%
338-
\index{#2@{\idxcode{#2()}}}%
343+
\newenvironment{cfuncdesc}[3]{
344+
\begin{fulllineitems}
345+
\item[\code{#1 \bfcode{#2}(\varvars{#3})}\index{#2@{\idxcode{#2()}}}]
339346
}{\end{fulllineitems}}
340347

341-
\newenvironment{cvardesc}[2]{%
342-
\begin{fulllineitems}%
343-
\item[\code{#1 \bfcode{#2}}]%
344-
\index{#2@{\idxcode{#2}}}%
348+
% C variables ------------------------------------------------------------
349+
% \begin{cvardesc}{type}{name}
350+
\newenvironment{cvardesc}[2]{
351+
\begin{fulllineitems}
352+
\item[\code{#1 \bfcode{#2}}\index{#2@{\idxcode{#2}}}]
345353
}{\end{fulllineitems}}
346354

347-
\newenvironment{ctypedesc}[1]{%
348-
\begin{fulllineitems}%
349-
\item[\bfcode{#1}]\ttindex{#1}
355+
% C data types -----------------------------------------------------------
356+
% \begin{ctypedesc}{typedef name}
357+
\newenvironment{ctypedesc}[1]{
358+
\begin{fulllineitems}
359+
\item[\bfcode{#1}\ttindex{#1}]
350360
}{\end{fulllineitems}}
351361

362+
% simple functions (not methods) -----------------------------------------
363+
% \begin{funcdesc}{name}{args}
352364
\newcommand{\funcline}[2]{\funclineni{#1}{#2}\ttindex{#1()}}
353-
\newenvironment{funcdesc}[2]{%
354-
\begin{fulllineitems}%
355-
\funcline{#1}{#2}%
365+
\newenvironment{funcdesc}[2]{
366+
\begin{fulllineitems}
367+
\funcline{#1}{#2}
356368
}{\end{fulllineitems}}
357369

358-
\newcommand{\optional}[1]{%
359-
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
360-
361370
% similar to {funcdesc}, but doesn't add to the index
362371
\newcommand{\funclineni}[2]{\item[\code{\bfcode{#1}(\varvars{#2})}]}
363-
\newenvironment{funcdescni}[2]{%
364-
\begin{fulllineitems}%
365-
\funclineni{#1}{#2}%
372+
\newenvironment{funcdescni}[2]{
373+
\begin{fulllineitems}
374+
\funclineni{#1}{#2}
375+
}{\end{fulllineitems}}
376+
377+
% classes ----------------------------------------------------------------
378+
% \begin{classdesc}{name}{constructor args}
379+
\newenvironment{classdesc}[2]{
380+
\global\def\@thisclass{#1}
381+
\begin{fulllineitems}
382+
\item[\code{\bfcode{#1}(\varvars{#2})}%
383+
\withsubitem{(class in \@thismodule)}{\ttindex{#1}}]
384+
\def\baseclasses##1{}
366385
}{\end{fulllineitems}}
367386

368-
\newenvironment{classdesc}[2]{%
369-
\renewcommand{\@thisclass}{#1}%
370-
\begin{fulllineitems}%
371-
\item[\code{\bfcode{#1}(\varvars{#2})}]%
372-
\withsubitem{(class in \@thismodule)}{\ttindex{#1}}%
373-
\def\baseclasses##1{}%
387+
388+
\newcommand{\@classbadkey}{--bad current class--}
389+
\let\@classbadkey=\@undefined
390+
391+
% object method ----------------------------------------------------------
392+
% \begin{methoddesc}[classname]{methodname}{args}
393+
\newcommand{\methodline}[3][\@classbadkey]{
394+
\methodlineni{#2}{#3}
395+
\ifx#1\@undefined
396+
\withsubitem{(\@thisclass\ method)}{\ttindex{#2()}}
397+
\else
398+
\withsubitem{(#1 method)}{\ttindex{#2()}}
399+
\fi
400+
}
401+
\newenvironment{methoddesc}[3][\@classbadkey]{
402+
\begin{fulllineitems}
403+
\ifx#1\@undefined
404+
\methodline{#2}{#3}
405+
\else
406+
\def\@thisclass{#1}
407+
\methodline[#1]{#2}{#3}
408+
\fi
374409
}{\end{fulllineitems}}
375410

376-
\newenvironment{excdesc}[1]{%
377-
\begin{fulllineitems}%
378-
\item[\bfcode{#1}]\ttindex{#1}%
411+
% similar to {methoddesc}, but doesn't add to the index
412+
% (never actually uses the optional argument)
413+
\newcommand{\methodlineni}[3][\@classbadkey]{%
414+
\item[\code{\bfcode{#2}(\varvars{#3})}]}
415+
\newenvironment{methoddescni}[3][\@classbadkey]{
416+
\begin{fulllineitems}
417+
\methodlineni{#2}{#3}
418+
}{\end{fulllineitems}}
419+
420+
% object data attribute --------------------------------------------------
421+
% \begin{memberdesc}[classname]{membername}
422+
\newcommand{\memberline}[2][\@classbadkey]{%
423+
\ifx#1\@undefined
424+
\memberlineni{#2}
425+
\withsubitem{(\@thisclass\ attribute)}{\ttindex{#2()}}
426+
\else
427+
\memberlineni{#2}
428+
\withsubitem{(#1 attribute)}{\ttindex{#2()}}
429+
\fi
430+
}
431+
\newenvironment{memberdesc}[2][\@classbadkey]{
432+
\begin{fulllineitems}
433+
\ifx#1\@undefined
434+
\memberline{#2}
435+
\else
436+
\def\@thisclass{#1}
437+
\memberline[#1]{#2}
438+
\fi
379439
}{\end{fulllineitems}}
380440

441+
% similar to {memberdesc}, but doesn't add to the index
442+
% (never actually uses the optional argument)
443+
\newcommand{\memberlineni}[2][\@classbadkey]{\item[\bfcode{#2}]}
444+
\newenvironment{memberdescni}[2][\@classbadkey]{
445+
\begin{fulllineitems}
446+
\memberlineni{#2}
447+
}{\end{fulllineitems}}
448+
449+
% For exceptions: --------------------------------------------------------
450+
% \begin{excdesc}{name}
451+
% -- need support for constructor; maybe use optional parameter?
452+
\newenvironment{excdesc}[1]{
453+
\begin{fulllineitems}
454+
\item[\bfcode{#1}\ttindex{#1}]
455+
}{\end{fulllineitems}}
456+
457+
% Module data or constants: ----------------------------------------------
458+
% \begin{datadesc}{name}
381459
\newcommand{\dataline}[1]{\datalineni{#1}\ttindex{#1}}
382-
\newenvironment{datadesc}[1]{%
383-
\begin{fulllineitems}%
384-
\dataline{#1}%
460+
\newenvironment{datadesc}[1]{
461+
\begin{fulllineitems}
462+
\dataline{#1}
385463
}{\end{fulllineitems}}
386464

387465
% similar to {datadesc}, but doesn't add to the index
388-
\newcommand{\datalineni}[1]{\item[\bfcode{#1}]}
389-
\newenvironment{datadescni}[1]{%
390-
\begin{fulllineitems}%
391-
\datalineni{#1}%
466+
\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
467+
\newenvironment{datadescni}[1]{
468+
\begin{fulllineitems}
469+
\datalineni{#1}
392470
}{\end{fulllineitems}}
393471

394-
\newenvironment{opcodedesc}[2]{%
395-
\begin{fulllineitems}%
396-
\item[\bfcode{#1}\quad\var{#2}]%
472+
% bytecode instruction ---------------------------------------------------
473+
% \begin{opcodedesc}{name}{var}
474+
% -- {var} may be {}
475+
\newenvironment{opcodedesc}[2]{
476+
\begin{fulllineitems}
477+
\item[\bfcode{#1}\quad\var{#2}]
397478
}{\end{fulllineitems}}
398479

399480

@@ -432,13 +513,13 @@
432513

433514
% Use this def/redef approach for \url{} since hyperref defined this already,
434515
% but only if we actually used hyperref:
435-
\@ifundefined{pdfannotlink}{%
436-
\newcommand{\pythonurl}[1]{\mbox{\small\textsf{#1}}}%
516+
\@ifundefined{pdfannotlink}{
517+
\newcommand{\pythonurl}[1]{\mbox{\small\textsf{#1}}}
437518
}{
438519
\newcommand{\pythonurl}[1]{{%
439520
\pdfannotlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
440521
\LinkColor% color of the link text
441-
\mbox{\small\textsf{#1}}%
522+
{\small\textsf{#1}}%
442523
\NormalColor% Turn it back off; these are declarative
443524
\pdfendlink}% and don't appear bound to the current
444525
}% formatting "box".
@@ -544,7 +625,6 @@
544625
%
545626
% \end{seealso}
546627

547-
\newif\if@keyedmodule\@keyedmodulefalse
548628
\newcommand{\@modulebadkey}{{--just-some-junk--}}
549629

550630
\@ifundefined{pdfannotlink}{%

0 commit comments

Comments
 (0)