root / docs / build / latex / sphinx.sty @ 216bb34c
History | View | Annotate | Download (22.3 kB)
1 |
% |
---|---|
2 |
% sphinx.sty |
3 |
% |
4 |
% Adapted from the old python.sty, mostly written by Fred Drake, |
5 |
% by Georg Brandl. |
6 |
% |
7 |
|
8 |
\NeedsTeXFormat{LaTeX2e}[1995/12/01] |
9 |
\ProvidesPackage{sphinx}[2008/05/01 LaTeX package (Sphinx markup)] |
10 |
|
11 |
\RequirePackage{textcomp} |
12 |
\RequirePackage{fancyhdr} |
13 |
\RequirePackage{fancybox} |
14 |
\RequirePackage{titlesec} |
15 |
\RequirePackage{tabulary} |
16 |
\RequirePackage{amsmath} % for \text |
17 |
\RequirePackage{makeidx} |
18 |
\RequirePackage{framed} |
19 |
\RequirePackage{color} |
20 |
% For highlighted code. |
21 |
\RequirePackage{fancyvrb} |
22 |
% For table captions. |
23 |
\RequirePackage{threeparttable} |
24 |
% Handle footnotes in tables. |
25 |
\RequirePackage{footnote} |
26 |
\makesavenoteenv{tabulary} |
27 |
% For floating figures in the text. |
28 |
\RequirePackage{wrapfig} |
29 |
|
30 |
% Redefine these colors to your liking in the preamble. |
31 |
\definecolor{TitleColor}{rgb}{0.126,0.263,0.361} |
32 |
\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486} |
33 |
\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388} |
34 |
% Redefine these colors to something not white if you want to have colored |
35 |
% background and border for code examples. |
36 |
\definecolor{VerbatimColor}{rgb}{1,1,1} |
37 |
\definecolor{VerbatimBorderColor}{rgb}{1,1,1} |
38 |
|
39 |
% Uncomment these two lines to ignore the paper size and make the page |
40 |
% size more like a typical published manual. |
41 |
%\renewcommand{\paperheight}{9in} |
42 |
%\renewcommand{\paperwidth}{8.5in} % typical squarish manual |
43 |
%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' |
44 |
|
45 |
% For graphicx, check if we are compiling under latex or pdflatex. |
46 |
\ifx\pdftexversion\undefined |
47 |
\usepackage{graphicx} |
48 |
\else |
49 |
\usepackage[pdftex]{graphicx} |
50 |
\fi |
51 |
|
52 |
% for PDF output, use colors and maximal compression |
53 |
\newif\ifsphinxpdfoutput\sphinxpdfoutputfalse |
54 |
\ifx\pdfoutput\undefined\else\ifcase\pdfoutput |
55 |
\let\py@NormalColor\relax |
56 |
\let\py@TitleColor\relax |
57 |
\else |
58 |
\sphinxpdfoutputtrue |
59 |
\input{pdfcolor} |
60 |
\def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} |
61 |
\def\py@TitleColor{\color{TitleColor}} |
62 |
\pdfcompresslevel=9 |
63 |
\fi\fi |
64 |
|
65 |
% XeLaTeX can do colors, too |
66 |
\ifx\XeTeXrevision\undefined\else |
67 |
\def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} |
68 |
\def\py@TitleColor{\color{TitleColor}} |
69 |
\fi |
70 |
|
71 |
% Increase printable page size (copied from fullpage.sty) |
72 |
\topmargin 0pt |
73 |
\advance \topmargin by -\headheight |
74 |
\advance \topmargin by -\headsep |
75 |
|
76 |
% attempt to work a little better for A4 users |
77 |
\textheight \paperheight |
78 |
\advance\textheight by -2in |
79 |
|
80 |
\oddsidemargin 0pt |
81 |
\evensidemargin 0pt |
82 |
%\evensidemargin -.25in % for ``manual size'' documents |
83 |
\marginparwidth 0.5in |
84 |
|
85 |
\textwidth \paperwidth |
86 |
\advance\textwidth by -2in |
87 |
|
88 |
|
89 |
% Style parameters and macros used by most documents here |
90 |
\raggedbottom |
91 |
\sloppy |
92 |
\parindent = 0mm |
93 |
\parskip = 2mm |
94 |
\hbadness = 5000 % don't print trivial gripes |
95 |
|
96 |
\pagestyle{empty} % start this way; change for |
97 |
\pagenumbering{roman} % ToC & chapters |
98 |
|
99 |
% Use this to set the font family for headers and other decor: |
100 |
\newcommand{\py@HeaderFamily}{\sffamily\bfseries} |
101 |
|
102 |
% Redefine the 'normal' header/footer style when using "fancyhdr" package: |
103 |
\@ifundefined{fancyhf}{}{ |
104 |
% Use \pagestyle{normal} as the primary pagestyle for text. |
105 |
\fancypagestyle{normal}{ |
106 |
\fancyhf{} |
107 |
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
108 |
\fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} |
109 |
\fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} |
110 |
\fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}} |
111 |
\renewcommand{\headrulewidth}{0.4pt} |
112 |
\renewcommand{\footrulewidth}{0.4pt} |
113 |
} |
114 |
% Update the plain style so we get the page number & footer line, |
115 |
% but not a chapter or section title. This is to keep the first |
116 |
% page of a chapter and the blank page between chapters `clean.' |
117 |
\fancypagestyle{plain}{ |
118 |
\fancyhf{} |
119 |
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
120 |
\renewcommand{\headrulewidth}{0pt} |
121 |
\renewcommand{\footrulewidth}{0.4pt} |
122 |
} |
123 |
} |
124 |
|
125 |
% Some custom font markup commands. |
126 |
% |
127 |
\newcommand{\strong}[1]{{\bf #1}} |
128 |
\newcommand{\code}[1]{\texttt{#1}} |
129 |
\newcommand{\bfcode}[1]{\code{\bfseries#1}} |
130 |
\newcommand{\samp}[1]{`\code{#1}'} |
131 |
\newcommand{\email}[1]{\textsf{#1}} |
132 |
|
133 |
\newcommand{\py@modulebadkey}{{--just-some-junk--}} |
134 |
|
135 |
% Redefine the Verbatim environment to allow border and background colors. |
136 |
% The original environment is still used for verbatims within tables. |
137 |
\let\OriginalVerbatim=\Verbatim |
138 |
\let\endOriginalVerbatim=\endVerbatim |
139 |
|
140 |
% Play with vspace to be able to keep the indentation. |
141 |
\newlength\distancetoright |
142 |
\newlength\leftsidespace |
143 |
\def\mycolorbox#1{% |
144 |
\setlength\leftsidespace{\@totalleftmargin}% |
145 |
\setlength\distancetoright{\textwidth}% |
146 |
\advance\distancetoright -\@totalleftmargin % |
147 |
\noindent\hspace*{\@totalleftmargin}% |
148 |
\fcolorbox{VerbatimBorderColor}{VerbatimColor}{% |
149 |
\begin{minipage}{\distancetoright}% |
150 |
\smallskip% |
151 |
\noindent\hspace*{-\leftsidespace}% |
152 |
#1 |
153 |
\end{minipage}% |
154 |
}% |
155 |
} |
156 |
\def\FrameCommand{\mycolorbox} |
157 |
|
158 |
\renewcommand{\Verbatim}[1][1]{% |
159 |
% The list environement is needed to control perfectly the vertical |
160 |
% space. |
161 |
\list{}{% |
162 |
\setlength\parskip{0pt}% |
163 |
\setlength\itemsep{0ex}% |
164 |
\setlength\topsep{0ex}% |
165 |
\setlength\partopsep{0pt}% |
166 |
\setlength\leftmargin{0pt}% |
167 |
}% |
168 |
\item\MakeFramed {\FrameRestore}% |
169 |
\small% |
170 |
\OriginalVerbatim[#1]% |
171 |
} |
172 |
\renewcommand{\endVerbatim}{% |
173 |
\endOriginalVerbatim% |
174 |
\endMakeFramed% |
175 |
\endlist% |
176 |
} |
177 |
|
178 |
|
179 |
% Index-entry generation support. |
180 |
% |
181 |
|
182 |
% Command to generate two index entries (using subentries) |
183 |
\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}} |
184 |
|
185 |
% And three entries (using only one level of subentries) |
186 |
\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}} |
187 |
|
188 |
% And four (again, using only one level of subentries) |
189 |
\newcommand{\indexiv}[4]{ |
190 |
\index{#1!#2 #3 #4} |
191 |
\index{#2!#3 #4, #1} |
192 |
\index{#3!#4, #1 #2} |
193 |
\index{#4!#1 #2 #3} |
194 |
} |
195 |
|
196 |
% support for the module index |
197 |
\newif\ifpy@UseModuleIndex |
198 |
\py@UseModuleIndexfalse |
199 |
|
200 |
\newcommand{\makemodindex}{ |
201 |
\newwrite\modindexfile |
202 |
\openout\modindexfile=mod\jobname.idx |
203 |
\py@UseModuleIndextrue |
204 |
} |
205 |
|
206 |
\newcommand{\printmodindex}{ |
207 |
\@input@{mod\jobname.ind} |
208 |
} |
209 |
|
210 |
% Add the defining entry for a module |
211 |
\newcommand{\py@modindex}[2]{% |
212 |
\renewcommand{\py@thismodule}{#1} |
213 |
\ifpy@UseModuleIndex% |
214 |
\@ifundefined{py@modplat@\py@thismodulekey}{ |
215 |
\write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}|hyperpage}{\thepage}}% |
216 |
}{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1 }% |
217 |
\emph{(\platformof{\py@thismodulekey})}}|hyperpage}{\thepage}}% |
218 |
} |
219 |
\fi% |
220 |
} |
221 |
|
222 |
% "Current" keys |
223 |
\newcommand{\py@thisclass}{} |
224 |
\newcommand{\py@thismodule}{} |
225 |
\newcommand{\py@thismodulekey}{} |
226 |
\newcommand{\py@thismoduletype}{} |
227 |
\newcommand{\py@emptymodule}{} |
228 |
|
229 |
% \declaremodule[key]{type}{name} |
230 |
\newcommand{\declaremodule}[3][\py@modulebadkey]{ |
231 |
\renewcommand{\py@thismoduletype}{#2} |
232 |
\ifx\py@modulebadkey#1 |
233 |
\renewcommand{\py@thismodulekey}{#3} |
234 |
\else |
235 |
\renewcommand{\py@thismodulekey}{#1} |
236 |
\fi |
237 |
\py@modindex{#3}{} |
238 |
%\label{module-\py@thismodulekey} |
239 |
} |
240 |
|
241 |
% Record module platforms for the Module Index |
242 |
\newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse |
243 |
\long\def\py@writeModPlatformFile#1{% |
244 |
\protected@write\py@ModPlatformFile% |
245 |
{\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}% |
246 |
{\string#1}% |
247 |
} |
248 |
\newcommand{\py@ModPlatformFilename}{\jobname.pla} |
249 |
\newcommand{\platform}[1]{ |
250 |
\ifpy@ModPlatformFileIsOpen\else |
251 |
\newwrite\py@ModPlatformFile |
252 |
\openout\py@ModPlatformFile=\py@ModPlatformFilename |
253 |
\py@ModPlatformFileIsOpentrue |
254 |
\fi |
255 |
\py@writeModPlatformFile{\py@defplatform{\py@thismodulekey}{#1}} |
256 |
} |
257 |
\newcommand{\py@defplatform}[2]{\expandafter\def\csname py@modplat@#1\endcsname{#2}} |
258 |
\newcommand{\platformof}[1]{\csname py@modplat@#1\endcsname} |
259 |
|
260 |
\InputIfFileExists{\jobname.pla}{}{} |
261 |
|
262 |
% \moduleauthor{name}{email} |
263 |
\newcommand{\moduleauthor}[2]{} |
264 |
|
265 |
% \sectionauthor{name}{email} |
266 |
\newcommand{\sectionauthor}[2]{} |
267 |
|
268 |
% Ignore module synopsis. |
269 |
\newcommand{\modulesynopsis}[1]{} |
270 |
|
271 |
% Reset "current" objects. |
272 |
\newcommand{\resetcurrentobjects}{ |
273 |
\renewcommand{\py@thisclass}{} |
274 |
\renewcommand{\py@thismodule}{} |
275 |
\renewcommand{\py@thismodulekey}{} |
276 |
\renewcommand{\py@thismoduletype}{} |
277 |
} |
278 |
|
279 |
% Augment the sectioning commands used to get our own font family in place, |
280 |
% and reset some internal data items: |
281 |
\titleformat{\section}{\Large\py@HeaderFamily}% |
282 |
{\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor} |
283 |
\titleformat{\subsection}{\large\py@HeaderFamily}% |
284 |
{\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} |
285 |
\titleformat{\subsubsection}{\py@HeaderFamily}% |
286 |
{\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} |
287 |
\titleformat{\paragraph}{\large\py@HeaderFamily}% |
288 |
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor} |
289 |
|
290 |
|
291 |
% Now for a lot of semantically-loaded environments that do a ton of magical |
292 |
% things to get the right formatting and index entries for the stuff in |
293 |
% Python modules and C API. |
294 |
|
295 |
|
296 |
% {fulllineitems} is used in one place in libregex.tex, but is really for |
297 |
% internal use in this file. |
298 |
% |
299 |
\newcommand{\py@itemnewline}[1]{% |
300 |
\@tempdima\linewidth% |
301 |
\advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% |
302 |
} |
303 |
|
304 |
\newenvironment{fulllineitems}{ |
305 |
\begin{list}{}{\labelwidth \leftmargin \labelsep 0pt |
306 |
\rightmargin 0pt \topsep -\parskip \partopsep \parskip |
307 |
\itemsep -\parsep |
308 |
\let\makelabel=\py@itemnewline} |
309 |
}{\end{list}} |
310 |
|
311 |
% \optional is mostly for use in the arguments parameters to the various |
312 |
% {*desc} environments defined below, but may be used elsewhere. Known to |
313 |
% be used in the debugger chapter. |
314 |
% |
315 |
% Typical usage: |
316 |
% |
317 |
% \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}} |
318 |
% ^^^ ^^^ |
319 |
% No space here No space here |
320 |
% |
321 |
% When a function has multiple optional parameters, \optional should be |
322 |
% nested, not chained. This is right: |
323 |
% |
324 |
% \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}} |
325 |
% |
326 |
\let\py@badkey=\@undefined |
327 |
|
328 |
\newcommand{\optional}[1]{% |
329 |
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} |
330 |
|
331 |
% This can be used when a function or method accepts an varying number |
332 |
% of arguments, such as by using the *args syntax in the parameter list. |
333 |
\newcommand{\py@moreargs}{...} |
334 |
|
335 |
% This can be used when you don't want to document the parameters to a |
336 |
% function or method, but simply state that it's an alias for |
337 |
% something else. |
338 |
\newcommand{\py@unspecified}{...} |
339 |
|
340 |
\newcommand{\py@varvars}[1]{{% |
341 |
{\let\unspecified=\py@unspecified% |
342 |
\let\moreargs=\py@moreargs% |
343 |
\emph{#1}}}} |
344 |
|
345 |
\newlength{\py@argswidth} |
346 |
\newcommand{\py@sigparams}[1]{% |
347 |
\parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}} |
348 |
\newcommand{\py@sigline}[2]{% |
349 |
\settowidth{\py@argswidth}{#1\code{(}}% |
350 |
\addtolength{\py@argswidth}{-2\py@argswidth}% |
351 |
\addtolength{\py@argswidth}{\textwidth}% |
352 |
\item[#1\code{(}\py@sigparams{#2}]} |
353 |
|
354 |
% C functions ------------------------------------------------------------ |
355 |
% \begin{cfuncdesc}[refcount]{type}{name}{arglist} |
356 |
% Note that the [refcount] slot should only be filled in by |
357 |
% tools/anno-api.py; it pulls the value from the refcounts database. |
358 |
\newcommand{\cfuncline}[3]{ |
359 |
\py@sigline{\code{#1 \bfcode{#2}}}{#3}% |
360 |
} |
361 |
\newenvironment{cfuncdesc}[3]{ |
362 |
\begin{fulllineitems} |
363 |
\cfuncline{#1}{#2}{#3} |
364 |
}{\end{fulllineitems}} |
365 |
|
366 |
% C variables ------------------------------------------------------------ |
367 |
% \begin{cvardesc}{type}{name} |
368 |
\newenvironment{cvardesc}[2]{ |
369 |
\begin{fulllineitems} |
370 |
\item[\code{#1 \bfcode{#2}}] |
371 |
}{\end{fulllineitems}} |
372 |
|
373 |
% C data types ----------------------------------------------------------- |
374 |
% \begin{ctypedesc}[index name]{typedef name} |
375 |
\newenvironment{ctypedesc}[2][\py@badkey]{ |
376 |
\begin{fulllineitems} |
377 |
\item[\bfcode{#2}] |
378 |
}{\end{fulllineitems}} |
379 |
|
380 |
% C type fields ---------------------------------------------------------- |
381 |
% \begin{cmemberdesc}{container type}{ctype}{membername} |
382 |
\newcommand{\cmemberline}[3]{ |
383 |
\item[\code{#2 \bfcode{#3}}] |
384 |
} |
385 |
\newenvironment{cmemberdesc}[3]{ |
386 |
\begin{fulllineitems} |
387 |
\cmemberline{#1}{#2}{#3} |
388 |
}{\end{fulllineitems}} |
389 |
|
390 |
% Funky macros ----------------------------------------------------------- |
391 |
% \begin{csimplemacrodesc}{name} |
392 |
% -- "simple" because it has no args; NOT for constant definitions! |
393 |
\newenvironment{csimplemacrodesc}[1]{ |
394 |
\begin{fulllineitems} |
395 |
\item[\bfcode{#1}] |
396 |
}{\end{fulllineitems}} |
397 |
|
398 |
% simple functions (not methods) ----------------------------------------- |
399 |
% \begin{funcdesc}{name}{args} |
400 |
\newcommand{\funcline}[2]{% |
401 |
\py@sigline{\bfcode{#1}}{#2}} |
402 |
\newenvironment{funcdesc}[2]{ |
403 |
\begin{fulllineitems} |
404 |
\funcline{#1}{#2} |
405 |
}{\end{fulllineitems}} |
406 |
|
407 |
% classes ---------------------------------------------------------------- |
408 |
% \begin{classdesc}{name}{constructor args} |
409 |
\newcommand{\classline}[2]{ |
410 |
\py@sigline{\strong{class }\bfcode{#1}}{#2}} |
411 |
\newenvironment{classdesc}[2]{ |
412 |
% Using \renewcommand doesn't work for this, for unknown reasons: |
413 |
\global\def\py@thisclass{#1} |
414 |
\begin{fulllineitems} |
415 |
\classline{#1}{#2} |
416 |
}{\end{fulllineitems}} |
417 |
|
418 |
% \begin{excclassdesc}{name}{constructor args} |
419 |
% but indexes as an exception |
420 |
\newenvironment{excclassdesc}[2]{ |
421 |
% Using \renewcommand doesn't work for this, for unknown reasons: |
422 |
\global\def\py@thisclass{#1} |
423 |
\begin{fulllineitems} |
424 |
\py@sigline{\strong{exception }\bfcode{#1}}{#2}% |
425 |
}{\end{fulllineitems}} |
426 |
|
427 |
% There is no corresponding {excclassdesc*} environment. To describe |
428 |
% a class exception without parameters, use the {excdesc} environment. |
429 |
|
430 |
|
431 |
\let\py@classbadkey=\@undefined |
432 |
|
433 |
% object method ---------------------------------------------------------- |
434 |
% \begin{methoddesc}[classname]{methodname}{args} |
435 |
\newcommand{\methodline}[3][\@undefined]{ |
436 |
\py@sigline{\bfcode{#2}}{#3}} |
437 |
\newenvironment{methoddesc}[3][\@undefined]{ |
438 |
\begin{fulllineitems} |
439 |
\ifx\@undefined#1\relax |
440 |
\methodline{#2}{#3} |
441 |
\else |
442 |
\def\py@thisclass{#1} |
443 |
\methodline{#2}{#3} |
444 |
\fi |
445 |
}{\end{fulllineitems}} |
446 |
|
447 |
% static method ---------------------------------------------------------- |
448 |
% \begin{staticmethoddesc}[classname]{methodname}{args} |
449 |
\newcommand{\staticmethodline}[3][\@undefined]{ |
450 |
\py@sigline{static \bfcode{#2}}{#3}} |
451 |
\newenvironment{staticmethoddesc}[3][\@undefined]{ |
452 |
\begin{fulllineitems} |
453 |
\ifx\@undefined#1\relax |
454 |
\staticmethodline{#2}{#3} |
455 |
\else |
456 |
\def\py@thisclass{#1} |
457 |
\staticmethodline{#2}{#3} |
458 |
\fi |
459 |
}{\end{fulllineitems}} |
460 |
|
461 |
% class method ---------------------------------------------------------- |
462 |
% \begin{classmethoddesc}[classname]{methodname}{args} |
463 |
\newcommand{\classmethodline}[3][\@undefined]{ |
464 |
\py@sigline{class \bfcode{#2}}{#3}} |
465 |
\newenvironment{classmethoddesc}[3][\@undefined]{ |
466 |
\begin{fulllineitems} |
467 |
\ifx\@undefined#1\relax |
468 |
\classmethodline{#2}{#3} |
469 |
\else |
470 |
\def\py@thisclass{#1} |
471 |
\classmethodline{#2}{#3} |
472 |
\fi |
473 |
}{\end{fulllineitems}} |
474 |
|
475 |
% object data attribute -------------------------------------------------- |
476 |
% \begin{memberdesc}[classname]{membername} |
477 |
\newcommand{\memberline}[2][\py@classbadkey]{% |
478 |
\ifx\@undefined#1\relax |
479 |
\item[\bfcode{#2}] |
480 |
\else |
481 |
\item[\bfcode{#2}] |
482 |
\fi |
483 |
} |
484 |
\newenvironment{memberdesc}[2][\py@classbadkey]{ |
485 |
\begin{fulllineitems} |
486 |
\ifx\@undefined#1\relax |
487 |
\memberline{#2} |
488 |
\else |
489 |
\def\py@thisclass{#1} |
490 |
\memberline{#2} |
491 |
\fi |
492 |
}{\end{fulllineitems}} |
493 |
|
494 |
% For exceptions: -------------------------------------------------------- |
495 |
% \begin{excdesc}{name} |
496 |
% -- for constructor information, use excclassdesc instead |
497 |
\newenvironment{excdesc}[1]{ |
498 |
\begin{fulllineitems} |
499 |
\item[\strong{exception }\bfcode{#1}] |
500 |
}{\end{fulllineitems}} |
501 |
|
502 |
% Module data or constants: ---------------------------------------------- |
503 |
% \begin{datadesc}{name} |
504 |
\newcommand{\dataline}[1]{% |
505 |
\item[\bfcode{#1}]\nopagebreak} |
506 |
\newenvironment{datadesc}[1]{ |
507 |
\begin{fulllineitems} |
508 |
\dataline{#1} |
509 |
}{\end{fulllineitems}} |
510 |
|
511 |
% bytecode instruction --------------------------------------------------- |
512 |
% \begin{opcodedesc}{name}{var} |
513 |
% -- {var} may be {} |
514 |
\newenvironment{opcodedesc}[2]{ |
515 |
\begin{fulllineitems} |
516 |
\item[\bfcode{#1}\quad\emph{#2}] |
517 |
}{\end{fulllineitems}} |
518 |
|
519 |
% generic description ---------------------------------------------------- |
520 |
\newcommand{\descline}[1]{% |
521 |
\item[\bfcode{#1}]\nopagebreak% |
522 |
} |
523 |
\newenvironment{describe}[1]{ |
524 |
\begin{fulllineitems} |
525 |
\descline{#1} |
526 |
}{\end{fulllineitems}} |
527 |
|
528 |
% This version is being checked in for the historical record; it shows |
529 |
% how I've managed to get some aspects of this to work. It will not |
530 |
% be used in practice, so a subsequent revision will change things |
531 |
% again. This version has problems, but shows how to do something |
532 |
% that proved more tedious than I'd expected, so I don't want to lose |
533 |
% the example completely. |
534 |
% |
535 |
\newcommand{\grammartoken}[1]{\texttt{#1}} |
536 |
\newenvironment{productionlist}[1][\py@badkey]{ |
537 |
\def\optional##1{{\Large[}##1{\Large]}} |
538 |
\def\production##1##2{\code{##1}&::=&\code{##2}\\} |
539 |
\def\productioncont##1{& &\code{##1}\\} |
540 |
\def\token##1{##1} |
541 |
\let\grammartoken=\token |
542 |
\parindent=2em |
543 |
\indent |
544 |
\begin{tabular}{lcl} |
545 |
}{% |
546 |
\end{tabular} |
547 |
} |
548 |
|
549 |
% Notices / Admonitions |
550 |
% |
551 |
\newlength{\py@noticelength} |
552 |
|
553 |
\newcommand{\py@heavybox}{ |
554 |
\setlength{\fboxrule}{1pt} |
555 |
\setlength{\fboxsep}{7pt} |
556 |
\setlength{\py@noticelength}{\linewidth} |
557 |
\addtolength{\py@noticelength}{-2\fboxsep} |
558 |
\addtolength{\py@noticelength}{-2\fboxrule} |
559 |
\setlength{\shadowsize}{3pt} |
560 |
\Sbox |
561 |
\minipage{\py@noticelength} |
562 |
} |
563 |
\newcommand{\py@endheavybox}{ |
564 |
\endminipage |
565 |
\endSbox |
566 |
\fbox{\TheSbox} |
567 |
} |
568 |
|
569 |
% Some are quite plain: |
570 |
\newcommand{\py@noticestart@note}{} |
571 |
\newcommand{\py@noticeend@note}{} |
572 |
\newcommand{\py@noticestart@hint}{} |
573 |
\newcommand{\py@noticeend@hint}{} |
574 |
\newcommand{\py@noticestart@important}{} |
575 |
\newcommand{\py@noticeend@important}{} |
576 |
\newcommand{\py@noticestart@tip}{} |
577 |
\newcommand{\py@noticeend@tip}{} |
578 |
|
579 |
% Others gets more visible distinction: |
580 |
\newcommand{\py@noticestart@warning}{\py@heavybox} |
581 |
\newcommand{\py@noticeend@warning}{\py@endheavybox} |
582 |
\newcommand{\py@noticestart@caution}{\py@heavybox} |
583 |
\newcommand{\py@noticeend@caution}{\py@endheavybox} |
584 |
\newcommand{\py@noticestart@attention}{\py@heavybox} |
585 |
\newcommand{\py@noticeend@attention}{\py@endheavybox} |
586 |
\newcommand{\py@noticestart@danger}{\py@heavybox} |
587 |
\newcommand{\py@noticeend@danger}{\py@endheavybox} |
588 |
\newcommand{\py@noticestart@error}{\py@heavybox} |
589 |
\newcommand{\py@noticeend@error}{\py@endheavybox} |
590 |
|
591 |
\newenvironment{notice}[2]{ |
592 |
\def\py@noticetype{#1} |
593 |
\csname py@noticestart@#1\endcsname |
594 |
\par\strong{#2} |
595 |
}{\csname py@noticeend@\py@noticetype\endcsname} |
596 |
|
597 |
% Allow the release number to be specified independently of the |
598 |
% \date{}. This allows the date to reflect the document's date and |
599 |
% release to specify the release that is documented. |
600 |
% |
601 |
\newcommand{\py@release}{} |
602 |
\newcommand{\version}{} |
603 |
\newcommand{\shortversion}{} |
604 |
\newcommand{\releaseinfo}{} |
605 |
\newcommand{\releasename}{Release} |
606 |
\newcommand{\release}[1]{% |
607 |
\renewcommand{\py@release}{\releasename\space\version}% |
608 |
\renewcommand{\version}{#1}} |
609 |
\newcommand{\setshortversion}[1]{% |
610 |
\renewcommand{\shortversion}{#1}} |
611 |
\newcommand{\setreleaseinfo}[1]{% |
612 |
\renewcommand{\releaseinfo}{#1}} |
613 |
|
614 |
% Allow specification of the author's address separately from the |
615 |
% author's name. This can be used to format them differently, which |
616 |
% is a good thing. |
617 |
% |
618 |
\newcommand{\py@authoraddress}{} |
619 |
\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}} |
620 |
|
621 |
% This sets up the fancy chapter headings that make the documents look |
622 |
% at least a little better than the usual LaTeX output. |
623 |
% |
624 |
\@ifundefined{ChTitleVar}{}{ |
625 |
\ChNameVar{\raggedleft\normalsize\py@HeaderFamily} |
626 |
\ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} |
627 |
\ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily} |
628 |
% This creates chapter heads without the leading \vspace*{}: |
629 |
\def\@makechapterhead#1{% |
630 |
{\parindent \z@ \raggedright \normalfont |
631 |
\ifnum \c@secnumdepth >\m@ne |
632 |
\DOCH |
633 |
\fi |
634 |
\interlinepenalty\@M |
635 |
\DOTI{#1} |
636 |
} |
637 |
} |
638 |
} |
639 |
|
640 |
% Redefine description environment so that it is usable inside fulllineitems. |
641 |
% |
642 |
\renewcommand{\description}{% |
643 |
\list{}{\labelwidth\z@% |
644 |
\itemindent-\leftmargin% |
645 |
\labelsep5pt% |
646 |
\let\makelabel=\descriptionlabel}} |
647 |
|
648 |
% Definition lists; requested by AMK for HOWTO documents. Probably useful |
649 |
% elsewhere as well, so keep in in the general style support. |
650 |
% |
651 |
\newenvironment{definitions}{% |
652 |
\begin{description}% |
653 |
\def\term##1{\item[##1]\mbox{}\\*[0mm]} |
654 |
}{% |
655 |
\end{description}% |
656 |
} |
657 |
|
658 |
% Tell TeX about pathological hyphenation cases: |
659 |
\hyphenation{Base-HTTP-Re-quest-Hand-ler} |
660 |
|
661 |
|
662 |
% The following is stuff copied from docutils' latex writer. |
663 |
% |
664 |
\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} |
665 |
\newenvironment{optionlist}[1] |
666 |
{\begin{list}{} |
667 |
{\setlength{\labelwidth}{#1} |
668 |
\setlength{\rightmargin}{1cm} |
669 |
\setlength{\leftmargin}{\rightmargin} |
670 |
\addtolength{\leftmargin}{\labelwidth} |
671 |
\addtolength{\leftmargin}{\labelsep} |
672 |
\renewcommand{\makelabel}{\optionlistlabel}} |
673 |
}{\end{list}} |
674 |
|
675 |
\newlength{\lineblockindentation} |
676 |
\setlength{\lineblockindentation}{2.5em} |
677 |
\newenvironment{lineblock}[1] |
678 |
{\begin{list}{} |
679 |
{\setlength{\partopsep}{\parskip} |
680 |
\addtolength{\partopsep}{\baselineskip} |
681 |
\topsep0pt\itemsep0.15\baselineskip\parsep0pt |
682 |
\leftmargin#1} |
683 |
\raggedright} |
684 |
{\end{list}} |
685 |
|
686 |
% Redefine includgraphics for avoiding images larger than the screen size |
687 |
% If the size is not specified. |
688 |
\let\py@Oldincludegraphics\includegraphics |
689 |
|
690 |
\newbox\image@box% |
691 |
\newdimen\image@width% |
692 |
\renewcommand\includegraphics[2][\@empty]{% |
693 |
\ifx#1\@empty% |
694 |
\setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}% |
695 |
\image@width\wd\image@box% |
696 |
\ifdim \image@width>\linewidth% |
697 |
\setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}% |
698 |
\fi% |
699 |
\box\image@box% |
700 |
\else% |
701 |
\py@Oldincludegraphics[#1]{#2}% |
702 |
\fi% |
703 |
} |
704 |
|
705 |
|
706 |
% Fix the index and bibliography environments to add an entry to the Table of |
707 |
% Contents; this is much nicer than just having to jump to the end of the book |
708 |
% and flip around, especially with multiple indexes. |
709 |
% |
710 |
\let\py@OldTheindex=\theindex |
711 |
\renewcommand{\theindex}{ |
712 |
\cleardoublepage |
713 |
\phantomsection |
714 |
\py@OldTheindex |
715 |
\addcontentsline{toc}{chapter}{\indexname} |
716 |
} |
717 |
|
718 |
\let\py@OldThebibliography=\thebibliography |
719 |
\renewcommand{\thebibliography}[1]{ |
720 |
\cleardoublepage |
721 |
\phantomsection |
722 |
\py@OldThebibliography{1} |
723 |
\addcontentsline{toc}{chapter}{\bibname} |
724 |
} |
725 |
|
726 |
% Include hyperref last. |
727 |
\RequirePackage[colorlinks,breaklinks, |
728 |
linkcolor=InnerLinkColor,filecolor=OuterLinkColor, |
729 |
menucolor=OuterLinkColor,pagecolor=OuterLinkColor, |
730 |
urlcolor=OuterLinkColor]{hyperref} |
731 |
|
732 |
% From docutils.writers.latex2e |
733 |
\providecommand{\DUspan}[2]{% |
734 |
{% group ("span") to limit the scope of styling commands |
735 |
\@for\node@class@name:=#1\do{% |
736 |
\ifcsname docutilsrole\node@class@name\endcsname% |
737 |
\csname docutilsrole\node@class@name\endcsname% |
738 |
\fi% |
739 |
}% |
740 |
{#2}% node content |
741 |
}% close "span" |
742 |
} |