Mercurial > cpython-lru_cache-weakref
comparison Doc/texinputs/python.sty @ 8713:ed8f4e2eb11a legacy-trunk
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.
| author | Fred Drake <fdrake@acm.org> |
|---|---|
| date | Thu, 23 Jul 1998 17:50:45 +0000 |
| parents | ce295bfacef3 |
| children | 74ea4dfda82d |
comparison
equal
deleted
inserted
replaced
| 8712:7983d86b48af | 8713:ed8f4e2eb11a |
|---|---|
| 28 \pdfpageheight=\paperheight % page height of PDF output | 28 \pdfpageheight=\paperheight % page height of PDF output |
| 29 % | 29 % |
| 30 % Pad the number with '0' to 3 digits wide so no page name is a prefix | 30 % Pad the number with '0' to 3 digits wide so no page name is a prefix |
| 31 % of any other. | 31 % of any other. |
| 32 % | 32 % |
| 33 \def\py@targetno#1{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1} | 33 \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1} |
| 34 \def\py@pageno{\py@targetno\thepage} | 34 \newcommand{\py@pageno}{\py@targetno\thepage} |
| 35 % | 35 % |
| 36 % This definition allows the entries in the page-view of the ToC to be | 36 % This definition allows the entries in the page-view of the ToC to be |
| 37 % active links. Some work, some don't. | 37 % active links. Some work, some don't. |
| 38 % | 38 % |
| 39 \let\py@OldContentsline=\contentsline | 39 \let\py@OldContentsline=\contentsline |
| 182 \py@OldEndVerbatim% | 182 \py@OldEndVerbatim% |
| 183 \end{minipage}% | 183 \end{minipage}% |
| 184 \endgroup% | 184 \endgroup% |
| 185 } | 185 } |
| 186 | 186 |
| 187 \newcommand{\reset@python}{ | 187 |
| 188 \global\let\py@thisclass=\@undefined | 188 \newcommand{\py@modulebadkey}{{--just-some-junk--}} |
| 189 \global\let\py@thismodule=\@undefined | 189 |
| 190 } | 190 |
| 191 \reset@python | 191 %% Lots of index-entry generation support. |
| 192 | |
| 193 % Command to wrap around stuff that refers to function / module / | |
| 194 % attribute names in the index. Default behavior: like \code{}. To | |
| 195 % just keep the index entries in the roman font, uncomment the second | |
| 196 % definition; it matches O'Reilly style more. | |
| 197 % | |
| 198 \newcommand{\py@idxcode}[1]{\texttt{#1}} | |
| 199 %\renewcommand{\py@idxcode}[1]{#1} | |
| 200 | |
| 201 % Command to generate two index entries (using subentries) | |
| 202 \newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}} | |
| 203 | |
| 204 % And three entries (using only one level of subentries) | |
| 205 \newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}} | |
| 206 | |
| 207 % And four (again, using only one level of subentries) | |
| 208 \newcommand{\indexiv}[4]{ | |
| 209 \index{#1!#2 #3 #4} | |
| 210 \index{#2!#3 #4, #1} | |
| 211 \index{#3!#4, #1 #2} | |
| 212 \index{#4!#1 #2 #3} | |
| 213 } | |
| 214 | |
| 215 % Command to generate a reference to a function, statement, keyword, | |
| 216 % operator. | |
| 217 \newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}} | |
| 218 \newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}} | |
| 219 \newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}} | |
| 220 \newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}} | |
| 221 \newcommand{\obindex}[1]{\indexii{object}{#1}} | |
| 222 \newcommand{\bifuncindex}[1]{\withsubitem{(built-in function)}{\ttindex{#1()}}} | |
| 223 | |
| 224 % Add an index entry for a module | |
| 225 \newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}} | |
| 226 \newcommand{\refmodindex}[1]{\py@refmodule{#1}{}} | |
| 227 \newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }} | |
| 228 \newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }} | |
| 229 \newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }} | |
| 230 | |
| 231 % support for the module index | |
| 232 \newif\ifpy@UseModuleIndex | |
| 233 \py@UseModuleIndexfalse | |
| 234 | |
| 235 \newcommand{\makemodindex}{ | |
| 236 \newwrite\modindexfile | |
| 237 \openout\modindexfile=mod\jobname.idx | |
| 238 \py@UseModuleIndextrue | |
| 239 } | |
| 240 | |
| 241 % Add the defining entry for a module | |
| 242 \newcommand{\py@modindex}[2]{% | |
| 243 \renewcommand{\py@thismodule}{#1} | |
| 244 \setindexsubitem{(in module #1)}% | |
| 245 \index{#1@{\py@idxcode{#1}} (#2module)|textbf}% | |
| 246 \ifpy@UseModuleIndex% | |
| 247 \write\modindexfile{\protect\indexentry{#1@{\tt #1}}{\thepage}}% | |
| 248 \fi% | |
| 249 } | |
| 250 | |
| 251 % built-in & Python modules in the main distribution | |
| 252 \newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }} | |
| 253 \newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }} | |
| 254 | |
| 255 % Python & extension modules outside the main distribution | |
| 256 \newcommand{\modindex}[1]{\py@modindex{#1}{}} | |
| 257 \newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }} | |
| 258 | |
| 259 % Additional string for an index entry | |
| 260 \newcommand{\index@subitem}{} | |
| 261 \newcommand{\setindexsubitem}[1]{\renewcommand{\index@subitem}{#1}} | |
| 262 \newcommand{\ttindex}[1]{\index{#1@{\py@idxcode{#1}} \index@subitem}} | |
| 263 | |
| 264 \newcommand{\withsubitem}[2]{% | |
| 265 \begingroup% | |
| 266 \def\index@subitem{#1}#2% | |
| 267 \endgroup% | |
| 268 } | |
| 269 | |
| 270 | |
| 271 % Module synopsis processing ----------------------------------------------- | |
| 272 % | |
| 273 \newcommand{\py@standardIndexModule}[1]{\stmodindex{#1}} | |
| 274 \newcommand{\py@builtinIndexModule}[1]{\bimodindex{#1}} | |
| 275 \newcommand{\py@extensionIndexModule}[1]{\exmodindex{#1}} | |
| 276 \newcommand{\py@IndexModule}[1]{\modindex{#1}} | |
| 277 | |
| 278 \newif\ifpy@HaveModSynopsis\py@HaveModSynopsisfalse | |
| 279 \newif\ifpy@ModSynopsisFileIsOpen\py@ModSynopsisFileIsOpenfalse | |
| 280 | |
| 281 % \declaremodule[key]{type}{name} | |
| 282 \newcommand{\declaremodule}[3][\py@modulebadkey]{ | |
| 283 \py@openModSynopsisFile | |
| 284 \renewcommand{\py@thismoduletype}{#2} | |
| 285 \csname py@#2IndexModule\endcsname{#3} | |
| 286 \ifx\py@modulebadkey#1 | |
| 287 \renewcommand{\py@thismodulekey}{#3} | |
| 288 \else | |
| 289 \renewcommand{\py@thismodulekey}{#1} | |
| 290 \fi | |
| 291 \label{module-\py@thismodulekey} | |
| 292 \py@HaveModSynopsistrue | |
| 293 } | |
| 294 | |
| 295 | |
| 296 \newcommand{\py@defsynopsis}{Module has no synopsis.} | |
| 297 \newcommand{\py@modulesynopsis}{\py@defsynopsis} | |
| 298 \newcommand{\modulesynopsis}[1]{ | |
| 299 \renewcommand{\py@modulesynopsis}{#1} | |
| 300 } | |
| 301 | |
| 302 % define the file | |
| 303 \newwrite\py@ModSynopsisFile | |
| 304 | |
| 305 % hacked from \addtocontents from latex.ltx: | |
| 306 \long\def\py@writeModSynopsisFile#1{% | |
| 307 \protected@write\py@ModSynopsisFile% | |
| 308 {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}% | |
| 309 {\string#1}% | |
| 310 } | |
| 311 \newcommand{\py@closeModSynopsisFile}{ | |
| 312 \ifpy@ModSynopsisFileIsOpen | |
| 313 \closeout\py@ModSynopsisFile | |
| 314 \py@ModSynopsisFileIsOpenfalse | |
| 315 \fi | |
| 316 } | |
| 317 \newcommand{\py@openModSynopsisFile}{ | |
| 318 \ifpy@ModSynopsisFileIsOpen\else | |
| 319 \openout\py@ModSynopsisFile=\py@ModSynopsisFilename | |
| 320 \py@ModSynopsisFileIsOpentrue | |
| 321 \fi | |
| 322 } | |
| 323 | |
| 324 \newcommand{\py@ProcessModSynopsis}{ | |
| 325 \ifpy@HaveModSynopsis | |
| 326 \py@writeModSynopsisFile{\modulesynopsis% | |
| 327 {\py@thismodulekey}{\py@thismodule}% | |
| 328 {\py@thismoduletype}{\py@modulesynopsis}}% | |
| 329 \py@HaveModSynopsisfalse | |
| 330 \fi | |
| 331 \renewcommand{\py@modulesynopsis}{\py@defsynopsis} | |
| 332 } | |
| 333 \AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile} | |
| 334 | |
| 335 \newcommand{\localmoduletable}{ | |
| 336 \IfFileExists{\py@ModSynopsisFilename}{ | |
| 337 \begin{synopsistable} | |
| 338 \input{\py@ModSynopsisFilename} | |
| 339 \end{synopsistable} | |
| 340 }{} | |
| 341 } | |
| 342 | |
| 343 \@ifundefined{pdfoutput}{ | |
| 344 \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\} | |
| 345 }{ | |
| 346 \newcommand{\py@ModSynopsisSummary}[4]{ | |
| 347 {\pdfannotlink attr{/Border [0 0 0]} goto name{label-module-#1} | |
| 348 \py@LinkColor \bfcode{#2} \py@NormalColor | |
| 349 \pdfendlink}& #4\\} | |
| 350 } | |
| 351 \newenvironment{synopsistable}{ | |
| 352 % key, name, type, synopsis | |
| 353 \let\modulesynopsis=\py@ModSynopsisSummary | |
| 354 \begin{tabular}{ll} | |
| 355 }{ | |
| 356 \end{tabular} | |
| 357 } | |
| 358 % | |
| 359 % -------------------------------------------------------------------------- | |
| 360 | |
| 361 | |
| 362 \newcommand{\py@thisclass}{} | |
| 363 \newcommand{\py@thismodule}{} | |
| 364 \newcommand{\py@thismodulekey}{} | |
| 365 \newcommand{\py@thismoduletype}{} | |
| 366 | |
| 367 \newcommand{\py@reset}{ | |
| 368 \py@ProcessModSynopsis | |
| 369 \renewcommand{\py@thisclass}{} | |
| 370 \renewcommand{\py@thismodule}{} | |
| 371 \renewcommand{\py@thismodulekey}{} | |
| 372 \renewcommand{\py@thismoduletype}{} | |
| 373 } | |
| 192 | 374 |
| 193 % Augment the sectioning commands used to get our own font family in place, | 375 % Augment the sectioning commands used to get our own font family in place, |
| 194 % and reset some internal data items: | 376 % and reset some internal data items: |
| 195 \renewcommand{\section}{\reset@python% | 377 \renewcommand{\section}{\py@reset% |
| 196 \@startsection{section}{1}{\z@}% | 378 \@startsection{section}{1}{\z@}% |
| 197 {-3.5ex \@plus -1ex \@minus -.2ex}% | 379 {-3.5ex \@plus -1ex \@minus -.2ex}% |
| 198 {2.3ex \@plus.2ex}% | 380 {2.3ex \@plus.2ex}% |
| 199 {\reset@font\Large\py@HeaderFamily}} | 381 {\reset@font\Large\py@HeaderFamily}} |
| 200 \renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}% | 382 \renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}% |
| 229 \AtBeginDocument{\catcode`\_\active\def_{\hackscore{}}}% | 411 \AtBeginDocument{\catcode`\_\active\def_{\hackscore{}}}% |
| 230 } | 412 } |
| 231 \expandafter\endgroup\next | 413 \expandafter\endgroup\next |
| 232 | 414 |
| 233 | 415 |
| 234 %% Lots of index-entry generation support. | |
| 235 | |
| 236 % Command to wrap around stuff that refers to function / module / | |
| 237 % attribute names in the index. Default behavior: like \code{}. To | |
| 238 % just keep the index entries in the roman font, uncomment the second | |
| 239 % definition to use instead; it matches O'Reilly style more. | |
| 240 % | |
| 241 \newcommand{\py@idxcode}[1]{\texttt{#1}} | |
| 242 %\renewcommand{\py@idxcode}[1]{#1} | |
| 243 | |
| 244 % Command to generate two index entries (using subentries) | |
| 245 \newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}} | |
| 246 | |
| 247 % And three entries (using only one level of subentries) | |
| 248 \newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}} | |
| 249 | |
| 250 % And four (again, using only one level of subentries) | |
| 251 \newcommand{\indexiv}[4]{ | |
| 252 \index{#1!#2 #3 #4} | |
| 253 \index{#2!#3 #4, #1} | |
| 254 \index{#3!#4, #1 #2} | |
| 255 \index{#4!#1 #2 #3} | |
| 256 } | |
| 257 | |
| 258 % Command to generate a reference to a function, statement, keyword, | |
| 259 % operator. | |
| 260 \newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}} | |
| 261 \newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}} | |
| 262 \newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}} | |
| 263 \newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}} | |
| 264 \newcommand{\obindex}[1]{\indexii{object}{#1}} | |
| 265 \newcommand{\bifuncindex}[1]{\withsubitem{(built-in function)}{\ttindex{#1()}}} | |
| 266 | |
| 267 % Add an index entry for a module | |
| 268 \newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}} | |
| 269 \newcommand{\refmodindex}[1]{\py@refmodule{#1}{}} | |
| 270 \newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }} | |
| 271 \newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }} | |
| 272 \newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }} | |
| 273 | |
| 274 % support for the module index | |
| 275 \newif\ifpy@UseModuleIndex | |
| 276 \py@UseModuleIndexfalse | |
| 277 | |
| 278 \newcommand{\makemodindex}{ | |
| 279 \newwrite\modindexfile | |
| 280 \openout\modindexfile=mod\jobname.idx | |
| 281 \py@UseModuleIndextrue | |
| 282 } | |
| 283 | |
| 284 % Add the defining entry for a module | |
| 285 \newcommand{\py@modindex}[2]{% | |
| 286 \global\def\py@thismodule{#1} | |
| 287 \setindexsubitem{(in module #1)}% | |
| 288 \index{#1@{\py@idxcode{#1}} (#2module)|textbf}% | |
| 289 \ifpy@UseModuleIndex% | |
| 290 \write\modindexfile{\protect\indexentry{#1@{\tt #1}}{\thepage}}% | |
| 291 \fi% | |
| 292 } | |
| 293 | |
| 294 % built-in & Python modules in the main distribution | |
| 295 \newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }} | |
| 296 \newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }} | |
| 297 | |
| 298 % Python & extension modules outside the main distribution | |
| 299 \newcommand{\modindex}[1]{\py@modindex{#1}{}} | |
| 300 \newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }} | |
| 301 | |
| 302 % Additional string for an index entry | |
| 303 \newcommand{\index@subitem}{} | |
| 304 \newcommand{\setindexsubitem}[1]{\renewcommand{\index@subitem}{#1}} | |
| 305 \newcommand{\ttindex}[1]{\index{#1@{\py@idxcode{#1}} \index@subitem}} | |
| 306 | |
| 307 \newcommand{\withsubitem}[2]{% | |
| 308 \begingroup% | |
| 309 \def\index@subitem{#1}#2% | |
| 310 \endgroup% | |
| 311 } | |
| 312 | |
| 313 | |
| 314 % Now for a lot of semantically-loaded environments that do a ton of magical | 416 % Now for a lot of semantically-loaded environments that do a ton of magical |
| 315 % things to get the right formatting and index entries for the stuff in | 417 % things to get the right formatting and index entries for the stuff in |
| 316 % Python modules and C API. | 418 % Python modules and C API. |
| 317 | 419 |
| 318 | 420 |
| 381 }{\end{fulllineitems}} | 483 }{\end{fulllineitems}} |
| 382 | 484 |
| 383 % classes ---------------------------------------------------------------- | 485 % classes ---------------------------------------------------------------- |
| 384 % \begin{classdesc}{name}{constructor args} | 486 % \begin{classdesc}{name}{constructor args} |
| 385 \newenvironment{classdesc}[2]{ | 487 \newenvironment{classdesc}[2]{ |
| 386 \global\def\py@thisclass{#1} | 488 \renewcommand{\py@thisclass}{#1} |
| 387 \begin{fulllineitems} | 489 \begin{fulllineitems} |
| 388 \item[\code{\bfcode{#1}(\py@varvars{#2})}% | 490 \item[\code{\bfcode{#1}(\py@varvars{#2})}% |
| 389 \withsubitem{(class in \py@thismodule)}{\ttindex{#1}}] | 491 \withsubitem{(class in \py@thismodule)}{\ttindex{#1}}] |
| 390 }{\end{fulllineitems}} | 492 }{\end{fulllineitems}} |
| 391 | 493 |
| 641 % | 743 % |
| 642 % % A funky case: module name contains '_'; have to supply an optional key | 744 % % A funky case: module name contains '_'; have to supply an optional key |
| 643 % \seemodule[copyreg]{copy_reg}{pickle interface constructor registration} | 745 % \seemodule[copyreg]{copy_reg}{pickle interface constructor registration} |
| 644 % | 746 % |
| 645 % \end{seealso} | 747 % \end{seealso} |
| 646 | |
| 647 \newcommand{\py@modulebadkey}{{--just-some-junk--}} | |
| 648 | 748 |
| 649 \@ifundefined{pdfannotlink}{% | 749 \@ifundefined{pdfannotlink}{% |
| 650 \newcommand{\py@seemodule}[3][\py@modulebadkey]{% | 750 \newcommand{\py@seemodule}[3][\py@modulebadkey]{% |
| 651 \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% | 751 \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi% |
| 652 \ref{module-\py@modulekey}:\quad % | 752 \ref{module-\py@modulekey}:\quad % |