Use \newenvironment{envname} instead of \newcommand{\foo} &
\newcommand{\endfoo} (or \let\endfoo=...!) wherever reasonable.
Where {*desc} environment helper functions are not needed outside a
single environment definition, inline them.
Ensure that \seemodule{} and \seetext{} are only available within the
{seealso} environment.
Added "()" to the index entries for {funcdesc} and {cfuncdesc} environments.
Added {classdesc} environment which looks like the {funcdesc} environment
but doesn't add the parens in the index entry.
Code elsewhere in this file tests for the inclusion of the package and does
not need to be uncommented. Comments explain what they do and how to
disable them.
Added support for the optional "fancyhdr" package. If used, page footers
include chapter information on the left and section information on the right.
Both optional packages, "fancyhdr" and "times", are enabled by default. We
may want to disable them before shipping, but I'm not completely convinced.
(How many installations format their own documentation?)
Handle most (all?) of the page style / numbering magic here so the documents
don't have to do it individually.
Revise the \bcode / \ecode stuff so that the {verbatim} environment handles
it right directly. \bcode / \ecode will be completely removed from all files
(to be checked in momentarily).
Have the {verbatim} environment get the samples indented a bit; this
appearantly had been attempted in the old code, but didn't work because
paragraphs weren't indented.
Make all headers, from chapters on down to subparagraphs, have sans-serif
titles.
\setindexsubitem{}: New macro. Replaces \renewcommand{\indexsubitem{}(...)}
everywhere. This allows LaTeX2HTML to be made to work correctly for
this. That was near impossible with the old mechanisms.
For all {*desc} environments, make the name of the described thing bold as
well as monospaced.
{opcodedesc} environment: Don't index the byte code names; that doesn't seem
terribly useful, and there are a lot of them.
\var{}: More magic to make sure that the size is right even if embedded in
\file{} or some other macro that uses the sans-serif font in running
text.
\bfcode{}: New macro. Makes the font \code{} and bold. (Was unreasonable
using old LaTeX 2.09.)
\file{}: Adjust the size of the sans-serif font a little.
\email{}, \url{}, Make these use the same font as \file{}, but not the
surrounding single-quotes.
Update many comments.
Lots of minor nits and a little cleanliness.
\file{}: Use a sans-serif font for the filename itself.
Use the fncychap.sty package for fancy chapter headings.
Replace the \maketitle command with our own format. This is new, but it
looks a lot better than the old one.
Use \renewcommand instead of \def when extending or overriding standard LaTeX
commands. This makes it more LaTeX-like.
\idxcode{}: New macro; used to mark things that would be \code{} for entry
into the index. This allows easily switching things around for the
font used in the index. (O'Reilly seems to keep it all plain roman
in the index. Looks reasonable in the Python documentation as well.)
\*index{}: Use \idxcode{} instead of {\codefont{}}.
semantic concepts.
Added two new ones (not discussed with Guido:
\constant{}: Markup for constants defined in Python modules.
\cfunction{}: Markup for C functions; these should probably be distinguished
by font, but are not at this time (since they're typically \code{} at
this point).
These are intended to support semantic markup. There are a number
of places in the documentation where the exact meaning of an
indentifier marked \code{} in the running text is ambiguous (could
be a module or a class, a function or a method, etc.). These are
intended to clarify the intent of the identifier for processing
applications and more intelligent style processing.
longer used anywhere. Use the {*desc} environments instead.
\var{}: Ensure that the argument is always set in roman italic, in case an
alternate font is being used for code. These keeps the result of
\var{} consistent.
Some minor changes to allow easier exploration of alternate fonts for code in
the running text. Haven't changed the selected font; I haven't found one that
has everything required! (The best non-monospaced font so far was missing
the <, >, and | characters, or at least had them at the wrong locations. It
also allowed confusion between upper-case I and lower-case L.)
{seealso} environment: Always start a new paragraph after the "See Also:"
line; this ensures that formatting is consistent for each subsequent
\see*{} item.
does the right thing if the openright option is given. Allows a
lot of crud to be removed from the document files' frontmatter
sections.
\endabstract Extend standard macro. (Called as \end{abstract}.)
Does the right thing if the openright option is given.
\optional Adjust to get the brackets right under latex2e.
used to add index references for built-in and standard modules, respectively.
Modified \bimodindex{} and \stmodindex{} to make the page number bold, to
allow the defining instance of a module to stand out in the index.
Check-ins which fix improper use of \bimodindex{} and \stmodindex{} will be
made as fixes are applied. Misc. indexing updates will occur as a side
effect in some cases.
the libdis.tex file I'm about to check in.
I'm not sure this is really an optimal solution yet, but it may be the best
alternative. It avoids describing the instructions as either data items or
functions.
This change was discussed with Guido. (Guido: Take a look at the LaTeX
output for this; if this is reasonable I'll go ahead and update the perl
code in myformat.perl to match.)
Fred Drake
Guido van Rossum