Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 1 | % |
Fred Drake | 6663b22 | 1998-03-06 22:33:06 +0000 | [diff] [blame] | 2 | % python.sty for the Python docummentation [works only with with Latex2e] |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 3 | % |
| 4 | |
| 5 | \NeedsTeXFormat{LaTeX2e}[1995/12/01] |
| 6 | \ProvidesPackage{python} |
Fred Drake | c0b2e45 | 1998-03-25 14:53:43 +0000 | [diff] [blame] | 7 | [1998/01/11 LaTeX package (Python markup)] |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 8 | |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 9 | % Uncomment these two lines to ignore the paper size and make the page |
| 10 | % size more like a typical published manual. |
| 11 | %\renewcommand{\paperheight}{9in} |
| 12 | %\renewcommand{\paperwidth}{8.5in} % typical squarish manual |
| 13 | %\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' |
| 14 | |
Fred Drake | 454a4fb | 1998-04-01 22:20:14 +0000 | [diff] [blame] | 15 | % These packages can be used to add marginal annotations which indicate |
| 16 | % index entries and labels; useful for reviewing this messy documentation! |
| 17 | % |
| 18 | %\RequirePackage{showkeys} |
| 19 | %\RequirePackage{showidx} |
| 20 | |
Fred Drake | c0b2e45 | 1998-03-25 14:53:43 +0000 | [diff] [blame] | 21 | % for PDF output, use maximal compression & a lot of other stuff |
| 22 | % (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>) |
| 23 | % |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 24 | \newif\ifpy@doing@page@targets |
| 25 | \py@doing@page@targetsfalse |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 26 | |
Fred Drake | c0b2e45 | 1998-03-25 14:53:43 +0000 | [diff] [blame] | 27 | \ifx\pdfoutput\undefined\else\ifcase\pdfoutput |
Fred Drake | c0b2e45 | 1998-03-25 14:53:43 +0000 | [diff] [blame] | 28 | \else |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 29 | \input{pdfcolor} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 30 | \let\py@LinkColor=\NavyBlue |
| 31 | \let\py@NormalColor=\Black |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 32 | \pdfcompresslevel=9 |
Fred Drake | ba1700c | 1998-05-11 20:42:54 +0000 | [diff] [blame] | 33 | \pdfpagewidth=\paperwidth % page width of PDF output |
| 34 | \pdfpageheight=\paperheight % page height of PDF output |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 35 | % |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 36 | % Pad the number with '0' to 3 digits wide so no page name is a prefix |
| 37 | % of any other. |
| 38 | % |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 39 | \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1} |
| 40 | \newcommand{\py@pageno}{\py@targetno\thepage} |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 41 | % |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 42 | % This definition allows the entries in the page-view of the ToC to be |
| 43 | % active links. Some work, some don't. |
| 44 | % |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 45 | \let\py@OldContentsline=\contentsline |
Fred Drake | aa2aea0 | 1999-01-27 17:37:36 +0000 | [diff] [blame] | 46 | % |
| 47 | % Macro that takes two args: the name to link to and the content of |
| 48 | % the link. This takes care of the PDF magic, getting the colors |
| 49 | % the same for each link, and avoids having lots of garbage all over |
| 50 | % this style file. |
| 51 | \newcommand{\py@linkToName}[2]{% |
| 52 | \pdfannotlink attr{/Border [0 0 0]} goto name{#1}% |
| 53 | \py@LinkColor#2\py@NormalColor% |
| 54 | \pdfendlink% |
| 55 | } |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 56 | % Compute the padded page number separately since we end up with a pair of |
| 57 | % \relax tokens; this gets the right string computed and works. |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 58 | \renewcommand{\contentsline}[3]{% |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 59 | \def\my@pageno{\py@targetno{#3}}% |
Fred Drake | aa2aea0 | 1999-01-27 17:37:36 +0000 | [diff] [blame] | 60 | \py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 61 | } |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 62 | \AtEndDocument{ |
Fred Drake | c0b2e45 | 1998-03-25 14:53:43 +0000 | [diff] [blame] | 63 | \InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{} |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 64 | } |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 65 | \newcommand{\py@target}[1]{% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 66 | \ifpy@doing@page@targets% |
Fred Drake | 9b8afde | 1999-03-24 14:16:17 +0000 | [diff] [blame] | 67 | {\pdfdest name{#1} xyz}% |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 68 | \fi% |
| 69 | } |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 70 | \let\py@OldLabel=\label |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 71 | \renewcommand{\label}[1]{% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 72 | \py@OldLabel{#1}% |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 73 | \py@target{label-#1}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 74 | } |
Fred Drake | ba1700c | 1998-05-11 20:42:54 +0000 | [diff] [blame] | 75 | % This stuff adds a page# destination to every PDF page, where # is three |
| 76 | % digits wide, padded with leading zeros. This doesn't really help with |
| 77 | % the frontmatter, but does fine with the body. |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 78 | % |
| 79 | % This is *heavily* based on the hyperref package. |
| 80 | % |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 81 | \def\@begindvi{% |
| 82 | \unvbox \@begindvibox |
| 83 | \@hyperfixhead |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 84 | } |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 85 | \def\@hyperfixhead{% |
| 86 | \let\H@old@thehead\@thehead |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 87 | \global\def\@foo{\py@target{page\py@pageno}}% |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 88 | \expandafter\ifx\expandafter\@empty\H@old@thehead |
| 89 | \def\H@old@thehead{\hfil}\fi |
| 90 | \def\@thehead{\@foo\relax\H@old@thehead}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 91 | } |
Fred Drake | c0b2e45 | 1998-03-25 14:53:43 +0000 | [diff] [blame] | 92 | \fi\fi |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 93 | |
| 94 | % Increase printable page size (copied from fullpage.sty) |
| 95 | \topmargin 0pt |
| 96 | \advance \topmargin by -\headheight |
| 97 | \advance \topmargin by -\headsep |
| 98 | |
| 99 | % attempt to work a little better for A4 users |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 100 | \textheight \paperheight |
| 101 | \advance\textheight by -2in |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 102 | |
| 103 | \oddsidemargin 0pt |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 104 | \evensidemargin 0pt |
| 105 | %\evensidemargin -.25in % for ``manual size'' documents |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 106 | \marginparwidth 0.5in |
| 107 | |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 108 | \textwidth \paperwidth |
| 109 | \advance\textwidth by -2in |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 110 | |
| 111 | |
| 112 | % Style parameters and macros used by most documents here |
| 113 | \raggedbottom |
| 114 | \sloppy |
| 115 | \parindent = 0mm |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 116 | \parskip = 2mm |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 117 | \hbadness = 5000 % don't print trivial gripes |
| 118 | |
| 119 | \pagestyle{empty} % start this way; change for |
| 120 | \pagenumbering{roman} % ToC & chapters |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 121 | |
| 122 | % Use this to set the font family for headers and other decor: |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 123 | \newcommand{\py@HeaderFamily}{\sffamily} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 124 | |
| 125 | % Redefine the 'normal' header/footer style when using "fancyhdr" package: |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 126 | \@ifundefined{fancyhf}{}{ |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 127 | % Use \pagestyle{normal} as the primary pagestyle for text. |
| 128 | \fancypagestyle{normal}{ |
| 129 | \fancyhf{} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 130 | \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
| 131 | \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} |
| 132 | \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 133 | \renewcommand{\headrulewidth}{0pt} |
| 134 | \renewcommand{\footrulewidth}{0.4pt} |
| 135 | } |
| 136 | % Update the plain style so we get the page number & footer line, |
| 137 | % but not a chapter or section title. This is to keep the first |
| 138 | % page of a chapter and the blank page between chapters `clean.' |
| 139 | \fancypagestyle{plain}{ |
| 140 | \fancyhf{} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 141 | \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 142 | \renewcommand{\headrulewidth}{0pt} |
| 143 | \renewcommand{\footrulewidth}{0.4pt} |
| 144 | } |
| 145 | % Redefine \cleardoublepage so that the blank page between chapters |
| 146 | % gets the plain style and not the fancy style. This is described |
| 147 | % in the documentation for the fancyhdr package by Piet von Oostrum. |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 148 | \@ifundefined{chapter}{}{ |
Fred Drake | 28f1391 | 1998-03-04 21:47:59 +0000 | [diff] [blame] | 149 | \renewcommand{\cleardoublepage}{ |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 150 | \clearpage\if@openright \ifodd\c@page\else |
Fred Drake | 28f1391 | 1998-03-04 21:47:59 +0000 | [diff] [blame] | 151 | \hbox{} |
| 152 | \thispagestyle{plain} |
| 153 | \newpage |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 154 | \if@twocolumn\hbox{}\newpage\fi\fi\fi |
Fred Drake | 28f1391 | 1998-03-04 21:47:59 +0000 | [diff] [blame] | 155 | } |
| 156 | } |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 157 | } |
| 158 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 159 | % This sets up the {verbatim} environment to be indented and a minipage, |
| 160 | % and to have all the other mostly nice properties that we want for |
| 161 | % code samples. |
| 162 | |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 163 | \let\py@OldVerbatim=\verbatim |
| 164 | \let\py@OldEndVerbatim=\endverbatim |
| 165 | \RequirePackage{verbatim} |
| 166 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 167 | % Variable used by begin code command |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 168 | \newlength{\py@codewidth} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 169 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 170 | \renewcommand{\verbatim}{% |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 171 | \setlength{\parindent}{1cm}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 172 | % Calculate the text width for the minipage: |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 173 | \setlength{\py@codewidth}{\linewidth}% |
| 174 | \addtolength{\py@codewidth}{-\parindent}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 175 | % |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 176 | \par\indent% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 177 | \begin{minipage}[t]{\py@codewidth}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 178 | \small% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 179 | \py@OldVerbatim% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 180 | } |
| 181 | \renewcommand{\endverbatim}{% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 182 | \py@OldEndVerbatim% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 183 | \end{minipage}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 184 | } |
| 185 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 186 | |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 187 | \newcommand{\py@modulebadkey}{{--just-some-junk--}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 188 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 189 | |
| 190 | %% Lots of index-entry generation support. |
| 191 | |
| 192 | % Command to wrap around stuff that refers to function / module / |
| 193 | % attribute names in the index. Default behavior: like \code{}. To |
| 194 | % just keep the index entries in the roman font, uncomment the second |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 195 | % definition; it matches O'Reilly style more. |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 196 | % |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 197 | \newcommand{\py@idxcode}[1]{\texttt{#1}} |
| 198 | %\renewcommand{\py@idxcode}[1]{#1} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 199 | |
| 200 | % Command to generate two index entries (using subentries) |
| 201 | \newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}} |
| 202 | |
| 203 | % And three entries (using only one level of subentries) |
| 204 | \newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}} |
| 205 | |
| 206 | % And four (again, using only one level of subentries) |
| 207 | \newcommand{\indexiv}[4]{ |
| 208 | \index{#1!#2 #3 #4} |
| 209 | \index{#2!#3 #4, #1} |
| 210 | \index{#3!#4, #1 #2} |
| 211 | \index{#4!#1 #2 #3} |
| 212 | } |
| 213 | |
| 214 | % Command to generate a reference to a function, statement, keyword, |
| 215 | % operator. |
Fred Drake | 0cabff9 | 1998-05-06 19:36:01 +0000 | [diff] [blame] | 216 | \newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 217 | \newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}} |
| 218 | \newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}} |
| 219 | \newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 220 | \newcommand{\obindex}[1]{\indexii{object}{#1}} |
Fred Drake | 2351c80 | 1998-04-02 18:48:32 +0000 | [diff] [blame] | 221 | \newcommand{\bifuncindex}[1]{\withsubitem{(built-in function)}{\ttindex{#1()}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 222 | |
| 223 | % Add an index entry for a module |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 224 | \newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}} |
| 225 | \newcommand{\refmodindex}[1]{\py@refmodule{#1}{}} |
| 226 | \newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }} |
| 227 | \newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }} |
| 228 | \newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 229 | |
Fred Drake | da94374 | 1999-01-13 17:09:06 +0000 | [diff] [blame] | 230 | % Refer to a module's documentation using a hyperlink of the module's |
| 231 | % name, at least if we're building PDF: |
| 232 | \@ifundefined{pdfannotlink}{% |
| 233 | \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}} |
Fred Drake | aa2aea0 | 1999-01-27 17:37:36 +0000 | [diff] [blame] | 234 | }{% |
| 235 | \newcommand{\refmodule}[2][\py@modulebadkey]{% |
Fred Drake | da94374 | 1999-01-13 17:09:06 +0000 | [diff] [blame] | 236 | \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
Fred Drake | aa2aea0 | 1999-01-27 17:37:36 +0000 | [diff] [blame] | 237 | \py@linkToName{label-module-\py@modulekey}{\module{#2}}% |
Fred Drake | da94374 | 1999-01-13 17:09:06 +0000 | [diff] [blame] | 238 | } |
| 239 | } |
| 240 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 241 | % support for the module index |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 242 | \newif\ifpy@UseModuleIndex |
| 243 | \py@UseModuleIndexfalse |
Fred Drake | b390daf | 1998-03-09 16:35:36 +0000 | [diff] [blame] | 244 | |
Fred Drake | b390daf | 1998-03-09 16:35:36 +0000 | [diff] [blame] | 245 | \newcommand{\makemodindex}{ |
| 246 | \newwrite\modindexfile |
| 247 | \openout\modindexfile=mod\jobname.idx |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 248 | \py@UseModuleIndextrue |
Fred Drake | b390daf | 1998-03-09 16:35:36 +0000 | [diff] [blame] | 249 | } |
| 250 | |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 251 | % Add the defining entry for a module |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 252 | \newcommand{\py@modindex}[2]{% |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 253 | \renewcommand{\py@thismodule}{#1} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 254 | \setindexsubitem{(in module #1)}% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 255 | \index{#1@{\py@idxcode{#1}} (#2module)|textbf}% |
| 256 | \ifpy@UseModuleIndex% |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 257 | \@ifundefined{py@modplat@\py@thismodulekey}{ |
| 258 | \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}% |
| 259 | }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} % |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 260 | \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}% |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 261 | } |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 262 | \fi% |
| 263 | } |
| 264 | |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 265 | % *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! *** |
| 266 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 267 | % built-in & Python modules in the main distribution |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 268 | \newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }% |
| 269 | \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
| 270 | \newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }% |
| 271 | \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 272 | |
| 273 | % Python & extension modules outside the main distribution |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 274 | \newcommand{\modindex}[1]{\py@modindex{#1}{}% |
| 275 | \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
| 276 | \newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }% |
| 277 | \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 278 | |
| 279 | % Additional string for an index entry |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 280 | \newif\ifpy@usingsubitem\py@usingsubitemfalse |
| 281 | \newcommand{\py@indexsubitem}{} |
| 282 | \newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}% |
| 283 | \py@usingsubitemtrue} |
| 284 | \newcommand{\ttindex}[1]{% |
| 285 | \ifpy@usingsubitem |
| 286 | \index{#1@{\py@idxcode{#1}}\py@indexsubitem}% |
| 287 | \else% |
| 288 | \index{#1@{\py@idxcode{#1}}}% |
| 289 | \fi% |
| 290 | } |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 291 | \newcommand{\withsubitem}[2]{% |
| 292 | \begingroup% |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 293 | \ifpy@usingsubitem% |
| 294 | \def\index@subitem{#1}#2% |
| 295 | \else% |
| 296 | \def\index@subitem{#1}#2% |
| 297 | \py@usingsubitemfalse% |
| 298 | \fi |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 299 | \endgroup% |
| 300 | } |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 301 | |
Fred Drake | 5371497 | 1998-04-02 22:33:16 +0000 | [diff] [blame] | 302 | |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 303 | % Module synopsis processing ----------------------------------------------- |
| 304 | % |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 305 | \newcommand{\py@thisclass}{} |
| 306 | \newcommand{\py@thismodule}{} |
| 307 | \newcommand{\py@thismodulekey}{} |
| 308 | \newcommand{\py@thismoduletype}{} |
| 309 | |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 310 | \newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }} |
| 311 | \newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }} |
| 312 | \newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }} |
| 313 | \newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}} |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 314 | |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 315 | \newif\ifpy@HaveModSynopsis \py@HaveModSynopsisfalse |
| 316 | \newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse |
| 317 | \newif\ifpy@HaveModPlatform \py@HaveModPlatformfalse |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 318 | |
| 319 | % \declaremodule[key]{type}{name} |
| 320 | \newcommand{\declaremodule}[3][\py@modulebadkey]{ |
| 321 | \py@openModSynopsisFile |
| 322 | \renewcommand{\py@thismoduletype}{#2} |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 323 | \ifx\py@modulebadkey#1 |
| 324 | \renewcommand{\py@thismodulekey}{#3} |
| 325 | \else |
| 326 | \renewcommand{\py@thismodulekey}{#1} |
| 327 | \fi |
Fred Drake | 5bc8d99 | 1999-05-17 14:47:10 +0000 | [diff] [blame] | 328 | \@ifundefined{py@#2IndexModule}{% |
| 329 | \typeout{*** MACRO declaremodule called with unknown module type: `#2'} |
Fred Drake | 6682302 | 1999-05-17 14:57:26 +0000 | [diff] [blame] | 330 | \py@IndexModule{#3}% |
Fred Drake | 5bc8d99 | 1999-05-17 14:47:10 +0000 | [diff] [blame] | 331 | }{% |
| 332 | \csname py@#2IndexModule\endcsname{#3}% |
| 333 | } |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 334 | \label{module-\py@thismodulekey} |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 335 | } |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 336 | \newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse |
| 337 | \newcommand{\py@ModPlatformFilename}{\jobname.pla} |
| 338 | \newcommand{\platform}[1]{ |
| 339 | \ifpy@ModPlatformFileIsOpen\else |
| 340 | \newwrite\py@ModPlatformFile |
| 341 | \openout\py@ModPlatformFile=\py@ModPlatformFilename |
| 342 | \py@ModPlatformFileIsOpentrue |
| 343 | \fi |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 344 | } |
| 345 | \InputIfFileExists{\jobname.pla}{}{} |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 346 | \newcommand{\py@platformof}[2][\py@modulebadkey]{% |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 347 | \ifx\py@modulebadkey#1 \def\py@key{#2}% |
| 348 | \else \def\py@key{#1}% |
| 349 | \fi% |
| 350 | \csname py@modplat@\py@key\endcsname% |
| 351 | } |
| 352 | \newcommand{\ignorePlatformAnnotation}[1]{} |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 353 | |
Fred Drake | b75c615 | 1998-08-10 18:41:43 +0000 | [diff] [blame] | 354 | % \moduleauthor{name}{email} |
| 355 | \newcommand{\moduleauthor}[2]{} |
| 356 | |
| 357 | % \sectionauthor{name}{email} |
| 358 | \newcommand{\sectionauthor}[2]{} |
| 359 | |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 360 | |
| 361 | \newcommand{\py@defsynopsis}{Module has no synopsis.} |
| 362 | \newcommand{\py@modulesynopsis}{\py@defsynopsis} |
| 363 | \newcommand{\modulesynopsis}[1]{ |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 364 | \py@HaveModSynopsistrue |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 365 | \renewcommand{\py@modulesynopsis}{#1} |
| 366 | } |
| 367 | |
| 368 | % define the file |
| 369 | \newwrite\py@ModSynopsisFile |
| 370 | |
| 371 | % hacked from \addtocontents from latex.ltx: |
| 372 | \long\def\py@writeModSynopsisFile#1{% |
| 373 | \protected@write\py@ModSynopsisFile% |
| 374 | {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}% |
| 375 | {\string#1}% |
| 376 | } |
| 377 | \newcommand{\py@closeModSynopsisFile}{ |
| 378 | \ifpy@ModSynopsisFileIsOpen |
| 379 | \closeout\py@ModSynopsisFile |
| 380 | \py@ModSynopsisFileIsOpenfalse |
| 381 | \fi |
| 382 | } |
| 383 | \newcommand{\py@openModSynopsisFile}{ |
| 384 | \ifpy@ModSynopsisFileIsOpen\else |
| 385 | \openout\py@ModSynopsisFile=\py@ModSynopsisFilename |
| 386 | \py@ModSynopsisFileIsOpentrue |
| 387 | \fi |
| 388 | } |
| 389 | |
| 390 | \newcommand{\py@ProcessModSynopsis}{ |
| 391 | \ifpy@HaveModSynopsis |
| 392 | \py@writeModSynopsisFile{\modulesynopsis% |
| 393 | {\py@thismodulekey}{\py@thismodule}% |
| 394 | {\py@thismoduletype}{\py@modulesynopsis}}% |
| 395 | \py@HaveModSynopsisfalse |
| 396 | \fi |
| 397 | \renewcommand{\py@modulesynopsis}{\py@defsynopsis} |
| 398 | } |
| 399 | \AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile} |
| 400 | |
Fred Drake | 0c275fa | 1999-03-02 16:17:44 +0000 | [diff] [blame] | 401 | |
| 402 | \long\def\py@writeModPlatformFile#1{% |
| 403 | \protected@write\py@ModPlatformFile% |
| 404 | {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}% |
| 405 | {\string#1}% |
| 406 | } |
| 407 | |
| 408 | |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 409 | \newcommand{\localmoduletable}{ |
| 410 | \IfFileExists{\py@ModSynopsisFilename}{ |
| 411 | \begin{synopsistable} |
| 412 | \input{\py@ModSynopsisFilename} |
| 413 | \end{synopsistable} |
| 414 | }{} |
| 415 | } |
| 416 | |
| 417 | \@ifundefined{pdfoutput}{ |
| 418 | \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\} |
| 419 | }{ |
Fred Drake | aa2aea0 | 1999-01-27 17:37:36 +0000 | [diff] [blame] | 420 | \newcommand{\py@ModSynopsisSummary}[4]{% |
| 421 | \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\ |
| 422 | } |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 423 | } |
| 424 | \newenvironment{synopsistable}{ |
| 425 | % key, name, type, synopsis |
| 426 | \let\modulesynopsis=\py@ModSynopsisSummary |
| 427 | \begin{tabular}{ll} |
| 428 | }{ |
| 429 | \end{tabular} |
| 430 | } |
| 431 | % |
| 432 | % -------------------------------------------------------------------------- |
| 433 | |
| 434 | |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 435 | \newcommand{\py@reset}{ |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 436 | \py@usingsubitemfalse |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 437 | \py@ProcessModSynopsis |
| 438 | \renewcommand{\py@thisclass}{} |
| 439 | \renewcommand{\py@thismodule}{} |
| 440 | \renewcommand{\py@thismodulekey}{} |
| 441 | \renewcommand{\py@thismoduletype}{} |
| 442 | } |
| 443 | |
| 444 | % Augment the sectioning commands used to get our own font family in place, |
| 445 | % and reset some internal data items: |
| 446 | \renewcommand{\section}{\py@reset% |
| 447 | \@startsection{section}{1}{\z@}% |
| 448 | {-3.5ex \@plus -1ex \@minus -.2ex}% |
| 449 | {2.3ex \@plus.2ex}% |
| 450 | {\reset@font\Large\py@HeaderFamily}} |
| 451 | \renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}% |
| 452 | {-3.25ex\@plus -1ex \@minus -.2ex}% |
| 453 | {1.5ex \@plus .2ex}% |
| 454 | {\reset@font\large\py@HeaderFamily}} |
| 455 | \renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}% |
| 456 | {-3.25ex\@plus -1ex \@minus -.2ex}% |
| 457 | {1.5ex \@plus .2ex}% |
| 458 | {\reset@font\normalsize\py@HeaderFamily}} |
| 459 | \renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}% |
| 460 | {3.25ex \@plus1ex \@minus.2ex}% |
| 461 | {-1em}% |
| 462 | {\reset@font\normalsize\py@HeaderFamily}} |
| 463 | \renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}% |
| 464 | {3.25ex \@plus1ex \@minus .2ex}% |
| 465 | {-1em}% |
| 466 | {\reset@font\normalsize\py@HeaderFamily}} |
| 467 | |
| 468 | |
Fred Drake | 5420f33 | 1998-07-23 21:41:02 +0000 | [diff] [blame] | 469 | % This gets the underscores closer to the right width; the only change |
| 470 | % from standard LaTeX is the width specified. |
| 471 | |
| 472 | \DeclareTextCommandDefault{\textunderscore}{% |
| 473 | \leavevmode \kern.06em\vbox{\hrule\@width.55em}} |
| 474 | |
Fred Drake | a488f30 | 1998-07-23 17:50:45 +0000 | [diff] [blame] | 475 | % Underscore hack (only act like subscript operator if in math mode) |
| 476 | % |
| 477 | % The following is due to Mark Wooding (the old version didn't work with |
| 478 | % Latex 2e. |
| 479 | |
| 480 | \DeclareRobustCommand\hackscore{% |
| 481 | \ifmmode_\else\textunderscore\fi% |
| 482 | } |
| 483 | \begingroup |
| 484 | \catcode`\_\active |
| 485 | \def\next{% |
| 486 | \AtBeginDocument{\catcode`\_\active\def_{\hackscore{}}}% |
| 487 | } |
| 488 | \expandafter\endgroup\next |
| 489 | |
| 490 | |
Fred Drake | 5371497 | 1998-04-02 22:33:16 +0000 | [diff] [blame] | 491 | % Now for a lot of semantically-loaded environments that do a ton of magical |
| 492 | % things to get the right formatting and index entries for the stuff in |
| 493 | % Python modules and C API. |
| 494 | |
| 495 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 496 | % {fulllineitems} is used in one place in libregex.tex, but is really for |
| 497 | % internal use in this file. |
| 498 | % |
Fred Drake | f9acc59 | 1998-09-09 15:27:43 +0000 | [diff] [blame] | 499 | \newcommand{\py@itemnewline}[1]{% |
| 500 | \@tempdima\linewidth% |
| 501 | \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% |
| 502 | } |
| 503 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 504 | \newenvironment{fulllineitems}{ |
| 505 | \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt |
| 506 | \rightmargin 0pt \topsep -\parskip \partopsep \parskip |
| 507 | \itemsep -\parsep |
Fred Drake | f9acc59 | 1998-09-09 15:27:43 +0000 | [diff] [blame] | 508 | \let\makelabel=\py@itemnewline} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 509 | }{\end{list}} |
| 510 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 511 | % \optional is mostly for use in the arguments parameters to the various |
| 512 | % {*desc} environments defined below, but may be used elsewhere. Known to |
| 513 | % be used in the debugger chapter. |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 514 | % |
| 515 | % Typical usage: |
| 516 | % |
| 517 | % \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}} |
| 518 | % ^^^ ^^^ |
| 519 | % No space here No space here |
| 520 | % |
| 521 | % When a function has multiple optional parameters, \optional should be |
| 522 | % nested, not chained. This is right: |
| 523 | % |
| 524 | % \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}} |
| 525 | % |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 526 | \let\py@badkey=\@undefined |
| 527 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 528 | \newcommand{\optional}[1]{% |
| 529 | {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} |
| 530 | |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 531 | % This can be used when a function or method accepts an varying number |
| 532 | % of arguments, such as by using the *args syntax in the parameter list. |
| 533 | \newcommand{\py@moreargs}{...} |
| 534 | |
| 535 | % This can be used when you don't want to document the parameters to a |
| 536 | % function or method, but simply state that it's an alias for |
| 537 | % something else. |
| 538 | \newcommand{\py@unspecified}{...} |
| 539 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 540 | % C functions ------------------------------------------------------------ |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 541 | % \begin{cfuncdesc}[refcount]{type}{name}{arglist} |
| 542 | % Note that the [refcount] slot should only be filled in by |
| 543 | % tools/anno-api.py; it pulls the value from the refcounts database. |
| 544 | \newenvironment{cfuncdesc}[4][\py@badkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 545 | \begin{fulllineitems} |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 546 | \item[\code{#2 \bfcode{#3}(\py@varvars{#4})}\index{#3@{\py@idxcode{#3()}}}] |
| 547 | \ifx#1\@undefined\else% |
Fred Drake | 0a863da | 2000-04-10 18:21:38 +0000 | [diff] [blame] | 548 | \emph{Return value: \textbf{#1}.}\\ |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 549 | \fi |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 550 | }{\end{fulllineitems}} |
| 551 | |
| 552 | % C variables ------------------------------------------------------------ |
| 553 | % \begin{cvardesc}{type}{name} |
| 554 | \newenvironment{cvardesc}[2]{ |
| 555 | \begin{fulllineitems} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 556 | \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}] |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 557 | }{\end{fulllineitems}} |
| 558 | |
| 559 | % C data types ----------------------------------------------------------- |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 560 | % \begin{ctypedesc}[index name]{typedef name} |
| 561 | \newenvironment{ctypedesc}[2][\py@badkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 562 | \begin{fulllineitems} |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 563 | \item[\bfcode{#2}% |
| 564 | \ifx#1\@undefined% |
| 565 | \withsubitem{(C type)}{\ttindex{#2}}% |
| 566 | \else% |
| 567 | \withsubitem{(C type)}{\ttindex{#1}}% |
| 568 | \fi] |
| 569 | }{\end{fulllineitems}} |
| 570 | |
| 571 | % Funky macros ----------------------------------------------------------- |
| 572 | % \begin{csimplemacro}{name} |
| 573 | % -- "simple" because it has no args; NOT for constant definitions! |
| 574 | \newenvironment{csimplemacrodesc}[1]{ |
| 575 | \begin{fulllineitems} |
| 576 | \item[\bfcode{#1}\withsubitem{(macro)}{\ttindex{#1}}] |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 577 | }{\end{fulllineitems}} |
| 578 | |
| 579 | % simple functions (not methods) ----------------------------------------- |
| 580 | % \begin{funcdesc}{name}{args} |
| 581 | \newcommand{\funcline}[2]{\funclineni{#1}{#2}\ttindex{#1()}} |
| 582 | \newenvironment{funcdesc}[2]{ |
| 583 | \begin{fulllineitems} |
| 584 | \funcline{#1}{#2} |
| 585 | }{\end{fulllineitems}} |
| 586 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 587 | % similar to {funcdesc}, but doesn't add to the index |
Fred Drake | 300775d | 1998-04-17 02:17:00 +0000 | [diff] [blame] | 588 | \newcommand{\funclineni}[2]{\item[\code{\bfcode{#1}(\py@varvars{#2})}]} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 589 | \newenvironment{funcdescni}[2]{ |
| 590 | \begin{fulllineitems} |
| 591 | \funclineni{#1}{#2} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 592 | }{\end{fulllineitems}} |
| 593 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 594 | % classes ---------------------------------------------------------------- |
| 595 | % \begin{classdesc}{name}{constructor args} |
| 596 | \newenvironment{classdesc}[2]{ |
Fred Drake | 1cbd196 | 1998-11-25 17:13:28 +0000 | [diff] [blame] | 597 | % Using \renewcommand doesn't work for this, for unknown reasons: |
| 598 | \global\def\py@thisclass{#1} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 599 | \begin{fulllineitems} |
Fred Drake | 300775d | 1998-04-17 02:17:00 +0000 | [diff] [blame] | 600 | \item[\code{\bfcode{#1}(\py@varvars{#2})}% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 601 | \withsubitem{(class in \py@thismodule)}{\ttindex{#1}}] |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 602 | }{\end{fulllineitems}} |
| 603 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 604 | |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 605 | \let\py@classbadkey=\@undefined |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 606 | |
| 607 | % object method ---------------------------------------------------------- |
| 608 | % \begin{methoddesc}[classname]{methodname}{args} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 609 | \newcommand{\methodline}[3][\py@classbadkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 610 | \methodlineni{#2}{#3} |
| 611 | \ifx#1\@undefined |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 612 | \withsubitem{(\py@thisclass\ method)}{\ttindex{#2()}} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 613 | \else |
| 614 | \withsubitem{(#1 method)}{\ttindex{#2()}} |
| 615 | \fi |
| 616 | } |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 617 | \newenvironment{methoddesc}[3][\py@classbadkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 618 | \begin{fulllineitems} |
| 619 | \ifx#1\@undefined |
| 620 | \methodline{#2}{#3} |
| 621 | \else |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 622 | \def\py@thisclass{#1} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 623 | \methodline[#1]{#2}{#3} |
| 624 | \fi |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 625 | }{\end{fulllineitems}} |
| 626 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 627 | % similar to {methoddesc}, but doesn't add to the index |
| 628 | % (never actually uses the optional argument) |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 629 | \newcommand{\methodlineni}[3][\py@classbadkey]{% |
Fred Drake | 300775d | 1998-04-17 02:17:00 +0000 | [diff] [blame] | 630 | \item[\code{\bfcode{#2}(\py@varvars{#3})}]} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 631 | \newenvironment{methoddescni}[3][\py@classbadkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 632 | \begin{fulllineitems} |
| 633 | \methodlineni{#2}{#3} |
| 634 | }{\end{fulllineitems}} |
| 635 | |
| 636 | % object data attribute -------------------------------------------------- |
| 637 | % \begin{memberdesc}[classname]{membername} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 638 | \newcommand{\memberline}[2][\py@classbadkey]{% |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 639 | \ifx#1\@undefined |
| 640 | \memberlineni{#2} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 641 | \withsubitem{(\py@thisclass\ attribute)}{\ttindex{#2}} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 642 | \else |
| 643 | \memberlineni{#2} |
Fred Drake | 41565f6 | 1998-04-07 19:32:40 +0000 | [diff] [blame] | 644 | \withsubitem{(#1 attribute)}{\ttindex{#2}} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 645 | \fi |
| 646 | } |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 647 | \newenvironment{memberdesc}[2][\py@classbadkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 648 | \begin{fulllineitems} |
| 649 | \ifx#1\@undefined |
| 650 | \memberline{#2} |
| 651 | \else |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 652 | \def\py@thisclass{#1} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 653 | \memberline[#1]{#2} |
| 654 | \fi |
| 655 | }{\end{fulllineitems}} |
| 656 | |
| 657 | % similar to {memberdesc}, but doesn't add to the index |
| 658 | % (never actually uses the optional argument) |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 659 | \newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]} |
| 660 | \newenvironment{memberdescni}[2][\py@classbadkey]{ |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 661 | \begin{fulllineitems} |
| 662 | \memberlineni{#2} |
| 663 | }{\end{fulllineitems}} |
| 664 | |
| 665 | % For exceptions: -------------------------------------------------------- |
| 666 | % \begin{excdesc}{name} |
| 667 | % -- need support for constructor; maybe use optional parameter? |
| 668 | \newenvironment{excdesc}[1]{ |
| 669 | \begin{fulllineitems} |
| 670 | \item[\bfcode{#1}\ttindex{#1}] |
| 671 | }{\end{fulllineitems}} |
| 672 | |
| 673 | % Module data or constants: ---------------------------------------------- |
| 674 | % \begin{datadesc}{name} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 675 | \newcommand{\dataline}[1]{\datalineni{#1}\ttindex{#1}} |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 676 | \newenvironment{datadesc}[1]{ |
| 677 | \begin{fulllineitems} |
| 678 | \dataline{#1} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 679 | }{\end{fulllineitems}} |
| 680 | |
| 681 | % similar to {datadesc}, but doesn't add to the index |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 682 | \newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak} |
| 683 | \newenvironment{datadescni}[1]{ |
| 684 | \begin{fulllineitems} |
| 685 | \datalineni{#1} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 686 | }{\end{fulllineitems}} |
| 687 | |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 688 | % bytecode instruction --------------------------------------------------- |
| 689 | % \begin{opcodedesc}{name}{var} |
| 690 | % -- {var} may be {} |
| 691 | \newenvironment{opcodedesc}[2]{ |
| 692 | \begin{fulllineitems} |
| 693 | \item[\bfcode{#1}\quad\var{#2}] |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 694 | }{\end{fulllineitems}} |
| 695 | |
| 696 | |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 697 | \newcommand{\nodename}[1]{\label{#1}} |
Fred Drake | 5573031 | 1998-03-25 15:41:23 +0000 | [diff] [blame] | 698 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 699 | % For these commands, use \command{} to get the typography right, not |
| 700 | % {\command}. This works better with the texinfo translation. |
| 701 | \newcommand{\ABC}{{\sc abc}} |
| 702 | \newcommand{\UNIX}{{\sc Unix}} |
| 703 | \newcommand{\POSIX}{POSIX} |
| 704 | \newcommand{\ASCII}{{\sc ascii}} |
| 705 | \newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}} |
| 706 | \newcommand{\C}{C} |
| 707 | \newcommand{\EOF}{{\sc eof}} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 708 | \newcommand{\NULL}{\constant{NULL}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 709 | |
Fred Drake | 5371497 | 1998-04-02 22:33:16 +0000 | [diff] [blame] | 710 | % Also for consistency: spell Python "Python", not "python"! |
| 711 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 712 | % code is the most difficult one... |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 713 | \newcommand{\code}[1]{{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 714 | \texttt{#1}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 715 | |
| 716 | \newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font |
Fred Drake | 8e54abe | 1998-07-01 14:49:25 +0000 | [diff] [blame] | 717 | \newcommand{\kbd}[1]{\code{#1}} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 718 | \newcommand{\samp}[1]{`\code{#1}'} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 719 | % This weird definition of \var{} allows it to always appear in roman |
| 720 | % italics, and won't get funky in code fragments when we play around |
Fred Drake | fa1cceb | 1998-11-30 14:42:59 +0000 | [diff] [blame] | 721 | % with fonts. This also works directly in math mode. |
| 722 | \newcommand{\var}[1]{% |
| 723 | \ifmmode% |
| 724 | \hbox{\normalsize\textrm{\textit{#1\/}}}% |
| 725 | \else% |
| 726 | \normalsize\textrm{\textit{#1\/}}% |
| 727 | \fi% |
| 728 | } |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 729 | \renewcommand{\emph}[1]{{\em #1}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 730 | \newcommand{\dfn}[1]{\emph{#1}} |
| 731 | \newcommand{\strong}[1]{{\bf #1}} |
| 732 | % let's experiment with a new font: |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 733 | \newcommand{\file}[1]{`{\small\textsf{#1}}'} |
Fred Drake | 0a0fd59 | 1999-04-28 14:59:44 +0000 | [diff] [blame] | 734 | \newcommand{\filenq}[1]{{\small\textsf{#1}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 735 | |
| 736 | % Use this def/redef approach for \url{} since hyperref defined this already, |
| 737 | % but only if we actually used hyperref: |
Fred Drake | 6cb7149 | 1998-03-27 05:22:53 +0000 | [diff] [blame] | 738 | \@ifundefined{pdfannotlink}{ |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 739 | \newcommand{\py@url}[1]{\mbox{\small\textsf{#1}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 740 | }{ |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 741 | \newcommand{\py@url}[1]{{% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 742 | \pdfannotlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 743 | \py@LinkColor% color of the link text |
| 744 | \mbox{\small\textsf{#1}}% |
| 745 | \py@NormalColor% Turn it back off; these are declarative |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 746 | \pdfendlink}% and don't appear bound to the current |
| 747 | }% formatting "box". |
| 748 | } |
Fred Drake | a2c2a83 | 1998-04-15 17:50:01 +0000 | [diff] [blame] | 749 | \let\url=\py@url |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 750 | \newcommand{\email}[1]{{\small\textsf{#1}}} |
Fred Drake | 454a4fb | 1998-04-01 22:20:14 +0000 | [diff] [blame] | 751 | \newcommand{\newsgroup}[1]{{\small\textsf{#1}}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 752 | |
Fred Drake | ba82878 | 2000-04-03 04:19:14 +0000 | [diff] [blame] | 753 | %\newcommand{\py@varvars}[1]{{\def\,{\/{\char`\,}}\var{#1}}} |
| 754 | \newcommand{\py@varvars}[1]{% |
| 755 | {\let\unspecified=\py@unspecified% |
| 756 | \let\moreargs=\py@moreargs% |
| 757 | \def\,{\/{\char`\,}}\var{#1}}} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 758 | % let's see if this breaks anything now; we may be able to simplify... |
| 759 | \renewcommand{\py@varvars}[1]{\var{#1}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 760 | |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 761 | % I'd really like to get rid of this! |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 762 | \newif\iftexi\texifalse |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 763 | |
Fred Drake | 1e4973b | 1998-07-28 21:52:17 +0000 | [diff] [blame] | 764 | % This is used to get l2h to put the copyright and abstract on |
| 765 | % a separate HTML page. |
| 766 | \newif\ifhtml\htmlfalse |
| 767 | |
| 768 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 769 | % These should be used for all references to identifiers which are |
| 770 | % used to refer to instances of specific language constructs. See the |
| 771 | % names for specific semantic assignments. |
| 772 | % |
| 773 | % For now, don't do anything really fancy with them; just use them as |
| 774 | % logical markup. This might change in the future. |
| 775 | % |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 776 | \newcommand{\module}[1]{\texttt{#1}} |
| 777 | \newcommand{\keyword}[1]{\texttt{#1}} |
| 778 | \newcommand{\exception}[1]{\texttt{#1}} |
| 779 | \newcommand{\class}[1]{\texttt{#1}} |
| 780 | \newcommand{\function}[1]{\texttt{#1}} |
| 781 | \newcommand{\member}[1]{\texttt{#1}} |
| 782 | \newcommand{\method}[1]{\texttt{#1}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 783 | |
Fred Drake | 5371497 | 1998-04-02 22:33:16 +0000 | [diff] [blame] | 784 | \newcommand{\pytype}[1]{#1} % built-in Python type |
| 785 | |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 786 | \newcommand{\cfunction}[1]{\texttt{#1}} |
| 787 | \newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name |
| 788 | \newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 789 | |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 790 | \newcommand{\mimetype}[1]{{\small\textsf{#1}}} |
Fred Drake | 94fac13 | 1998-03-12 19:37:03 +0000 | [diff] [blame] | 791 | % The \! is a "negative thin space" in math mode. |
| 792 | \newcommand{\regexp}[1]{% |
| 793 | {\tiny$^{^\lceil}\!\!$% |
| 794 | {\normalsize\code{#1}}% |
Fred Drake | 47cfd03 | 1998-04-03 21:22:31 +0000 | [diff] [blame] | 795 | $\!\rfloor\!$% |
Fred Drake | 94fac13 | 1998-03-12 19:37:03 +0000 | [diff] [blame] | 796 | }} |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 797 | \newcommand{\envvar}[1]{% |
Fred Drake | 94fac13 | 1998-03-12 19:37:03 +0000 | [diff] [blame] | 798 | \$#1% $ <-- bow to font-lock 3 times! |
| 799 | \index{#1@{\$#1}}% $ |
| 800 | \index{environment variables!{\$#1}}% $ |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 801 | } |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 802 | \newcommand{\makevar}[1]{#1} % variable in a Makefile |
| 803 | \newcommand{\character}[1]{\samp{#1}} |
Fred Drake | 0ee9f72 | 1998-03-12 06:41:40 +0000 | [diff] [blame] | 804 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 805 | % constants defined in Python modules or C headers, not language constants: |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 806 | \newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 807 | |
| 808 | \newcommand{\manpage}[2]{{\emph{#1}(#2)}} |
| 809 | \newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}} |
| 810 | \newcommand{\program}[1]{\strong{#1}} |
Fred Drake | 7b8195a | 1999-11-09 17:02:11 +0000 | [diff] [blame] | 811 | \newcommand{\programopt}[1]{\strong{#1}} |
Fred Drake | 4936249 | 2000-04-11 18:47:59 +0000 | [diff] [blame] | 812 | % Note that \longprogramopt provides the '--'! |
| 813 | \newcommand{\longprogramopt}[1]{\strong{-{}-#1}} |
Fred Drake | 7b8195a | 1999-11-09 17:02:11 +0000 | [diff] [blame] | 814 | |
| 815 | % cited titles: \citetitle{Title of Work} |
| 816 | % online: \citetitle[url-to-resource]{Title of Work} |
| 817 | \newcommand{\citetitle}[2][URL]{\emph{#1}} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 818 | |
| 819 | |
| 820 | % Deprecation stuff. |
| 821 | % Should be extended to allow an index / list of deprecated stuff. But |
| 822 | % there's a lot of stuff that needs to be done to make that automatable. |
| 823 | % |
| 824 | % First parameter is the release number that deprecates the feature, the |
| 825 | % second is the action the should be taken by users of the feature. |
| 826 | % |
| 827 | % Example: |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 828 | % \deprecated{1.5.1}{Use \method{frobnicate()} instead.} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 829 | % |
| 830 | \newcommand{\deprecated}[2]{% |
| 831 | \strong{Deprecated since release #1.} #2\par} |
| 832 | |
Fred Drake | af958c7 | 1998-07-27 20:32:33 +0000 | [diff] [blame] | 833 | % New stuff. |
| 834 | % This should be used to mark things which have been added to the |
| 835 | % development tree but that aren't in the release, but are documented. |
| 836 | % This allows release of documentation that already includes updated |
Fred Drake | 2116d98 | 1999-02-02 18:02:48 +0000 | [diff] [blame] | 837 | % descriptions. Place at end of descriptor environment. |
Fred Drake | af958c7 | 1998-07-27 20:32:33 +0000 | [diff] [blame] | 838 | % |
| 839 | % Example: |
| 840 | % \versionadded{1.5.2} |
Fred Drake | a6e8339 | 2000-05-02 17:28:36 +0000 | [diff] [blame^] | 841 | % \versionchanged[short explanation]{1.6} |
Fred Drake | af958c7 | 1998-07-27 20:32:33 +0000 | [diff] [blame] | 842 | % |
| 843 | \newcommand{\versionadded}[1]{% |
Fred Drake | 2116d98 | 1999-02-02 18:02:48 +0000 | [diff] [blame] | 844 | { New in version #1. }} |
Fred Drake | a6e8339 | 2000-05-02 17:28:36 +0000 | [diff] [blame^] | 845 | \newcommand{\versionchanged}[2][\py@badkey]{% |
| 846 | \ifx#1\@undefined% |
| 847 | { Changed in version #2. }% |
| 848 | \else% |
| 849 | { Changed in version #2:\ #1. }% |
| 850 | \fi% |
| 851 | } |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 852 | |
Fred Drake | af958c7 | 1998-07-27 20:32:33 +0000 | [diff] [blame] | 853 | |
| 854 | % Tables. |
| 855 | % |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 856 | \newenvironment{tableii}[4]{% |
| 857 | \begin{center}% |
| 858 | \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}% |
Fred Drake | ee60191 | 1998-04-11 20:53:03 +0000 | [diff] [blame] | 859 | \begin{tabular}{#1}\strong{#3}&\strong{#4} \\ \hline% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 860 | }{% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 861 | \end{tabular}% |
| 862 | \end{center}% |
| 863 | } |
| 864 | |
| 865 | \newenvironment{tableiii}[5]{% |
| 866 | \begin{center}% |
| 867 | \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}% |
Fred Drake | ee60191 | 1998-04-11 20:53:03 +0000 | [diff] [blame] | 868 | \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\ \hline% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 869 | }{% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 870 | \end{tabular}% |
| 871 | \end{center}% |
| 872 | } |
| 873 | |
Fred Drake | 30e5265 | 1998-07-24 22:11:29 +0000 | [diff] [blame] | 874 | \newenvironment{tableiv}[6]{% |
| 875 | \begin{center}% |
| 876 | \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}% |
| 877 | \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\% |
| 878 | \hline% |
| 879 | }{% |
| 880 | \end{tabular}% |
| 881 | \end{center}% |
| 882 | } |
| 883 | |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 884 | % Cross-referencing (AMK, new impl. FLD) |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 885 | % Sample usage: |
| 886 | % \begin{seealso} |
Fred Drake | 84bd6f3 | 1999-05-11 15:42:51 +0000 | [diff] [blame] | 887 | % \seemodule{rand}{Uniform random number generator.}; % Module xref |
| 888 | % \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 889 | % |
| 890 | % % A funky case: module name contains '_'; have to supply an optional key |
Fred Drake | 84bd6f3 | 1999-05-11 15:42:51 +0000 | [diff] [blame] | 891 | % \seemodule[copyreg]{copy_reg}{Interface constructor registration for |
| 892 | % \module{pickle}.} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 893 | % \end{seealso} |
Fred Drake | 84bd6f3 | 1999-05-11 15:42:51 +0000 | [diff] [blame] | 894 | % |
| 895 | % Note that the last parameter for \seemodule and \seetext should be complete |
| 896 | % sentences and be terminated with the proper punctuation. |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 897 | |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 898 | \@ifundefined{pdfannotlink}{% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 899 | \newcommand{\py@seemodule}[3][\py@modulebadkey]{% |
Fred Drake | da94374 | 1999-01-13 17:09:06 +0000 | [diff] [blame] | 900 | \par% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 901 | \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
Fred Drake | 84bd6f3 | 1999-05-11 15:42:51 +0000 | [diff] [blame] | 902 | \begin{fulllineitems} |
| 903 | \item[Module \module{#2} (section \ref{module-\py@modulekey}):] |
| 904 | #3 |
| 905 | \end{fulllineitems} |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 906 | } |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 907 | }{\newcommand{\py@seemodule}[3][\py@modulebadkey]{% |
Fred Drake | da94374 | 1999-01-13 17:09:06 +0000 | [diff] [blame] | 908 | \par% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 909 | \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
Fred Drake | 84bd6f3 | 1999-05-11 15:42:51 +0000 | [diff] [blame] | 910 | \begin{fulllineitems} |
| 911 | \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}} |
| 912 | (section \ref{module-\py@modulekey}):] |
| 913 | #3 |
| 914 | \end{fulllineitems} |
Fred Drake | ebcb658 | 1998-03-06 21:25:17 +0000 | [diff] [blame] | 915 | } |
| 916 | } |
Fred Drake | 64b72b6 | 2000-04-26 18:13:58 +0000 | [diff] [blame] | 917 | % \seerfc{number}{title}{why it's interesting} |
| 918 | \newcommand{\py@seerfc}[3]{% |
| 919 | \par% |
| 920 | \begin{fulllineitems} |
| 921 | \item[\rfc{#1}, ``\emph{#2}''] |
| 922 | #3 |
| 923 | \end{fulllineitems} |
| 924 | } |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 925 | \newenvironment{seealso}[0]{ |
Fred Drake | 9466b9a | 1999-03-18 16:18:27 +0000 | [diff] [blame] | 926 | \par |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 927 | \strong{See Also:}\par |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 928 | \def\seetext##1{\par{##1}} |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 929 | \let\seemodule=\py@seemodule |
Fred Drake | 64b72b6 | 2000-04-26 18:13:58 +0000 | [diff] [blame] | 930 | \let\seerfc=\py@seerfc |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 931 | }{\par} |
| 932 | |
| 933 | |
Fred Drake | af958c7 | 1998-07-27 20:32:33 +0000 | [diff] [blame] | 934 | % Allow the Python release number to be specified independently of the |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 935 | % \date{}. This allows the date to reflect the document's date and |
| 936 | % release to specify the Python release that is documented. |
| 937 | % |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 938 | \newcommand{\py@release}{} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 939 | \newcommand{\version}{} |
| 940 | \newcommand{\releasename}{Release} |
| 941 | \newcommand{\release}[1]{% |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 942 | \renewcommand{\py@release}{\releasename\space\version}% |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 943 | \renewcommand{\version}{#1}} |
| 944 | |
| 945 | % Allow specification of the author's address separately from the |
| 946 | % author's name. This can be used to format them differently, which |
| 947 | % is a good thing. |
| 948 | % |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 949 | \newcommand{\py@authoraddress}{} |
| 950 | \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}} |
Fred Drake | 6df93ef | 1998-05-14 20:56:31 +0000 | [diff] [blame] | 951 | \let\developersaddress=\authoraddress |
| 952 | \let\developer=\author |
| 953 | \let\developers=\author |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 954 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 955 | % This sets up the fancy chapter headings that make the documents look |
| 956 | % at least a little better than the usual LaTeX output. |
| 957 | % |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 958 | \@ifundefined{ChTitleVar}{}{ |
Fred Drake | 24340ea | 1998-04-28 18:30:34 +0000 | [diff] [blame] | 959 | \ChNameVar{\raggedleft\normalsize\py@HeaderFamily} |
| 960 | \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} |
| 961 | \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily} |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 962 | % This creates chapter heads without the leading \vspace*{}: |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 963 | \def\@makechapterhead#1{% |
| 964 | {\parindent \z@ \raggedright \normalfont |
| 965 | \ifnum \c@secnumdepth >\m@ne |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 966 | \DOCH |
| 967 | \fi |
Fred Drake | 1c8d0e0 | 1998-03-07 05:29:15 +0000 | [diff] [blame] | 968 | \interlinepenalty\@M |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 969 | \DOTI{#1} |
| 970 | } |
| 971 | } |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 972 | } |
| 973 | |
Fred Drake | 3bf7865 | 1998-05-20 17:42:17 +0000 | [diff] [blame] | 974 | |
| 975 | % Definition lists; requested by AMK for HOWTO documents. Probably useful |
| 976 | % elsewhere as well, so keep in in the general style support. |
| 977 | % |
| 978 | \newenvironment{definitions}{% |
| 979 | \begin{description}% |
Fred Drake | f9acc59 | 1998-09-09 15:27:43 +0000 | [diff] [blame] | 980 | \def\term##1{\item[##1]\mbox{}\\*[0mm]} |
Fred Drake | 3bf7865 | 1998-05-20 17:42:17 +0000 | [diff] [blame] | 981 | }{% |
| 982 | \end{description}% |
| 983 | } |
| 984 | |
Fred Drake | 6659c30 | 1998-03-03 22:02:19 +0000 | [diff] [blame] | 985 | % Tell TeX about pathological hyphenation cases: |
| 986 | \hyphenation{Base-HTTP-Re-quest-Hand-ler} |