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