Delete the LaTeX doc tree.

1 files changed, 0 insertions, 2129 deletions

diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
deleted file mode 100644
index 1d0f279..0000000
--- a/Doc/doc/doc.tex
+++ /dev/null
@@ -1,2129 +0,0 @@
-\documentclass{howto}
-\usepackage{ltxmarkup}
-
-\title{Documenting Python}
-
-\makeindex
-
-\input{boilerplate}
-
-% Now override the stuff that includes author information;
-% Guido did *not* write this one!
-
-\author{Fred L. Drake, Jr.}
-\authoraddress{
-        PythonLabs \\
-        Email: \email{fdrake@acm.org}
-}
-
-
-\begin{document}
-
-\maketitle
-
-\begin{abstract}
-\noindent
-The Python language has a substantial body of
-documentation, much of it contributed by various authors.  The markup
-used for the Python documentation is based on \LaTeX{} and requires a
-significant set of macros written specifically for documenting Python.
-This document describes the macros introduced to support Python
-documentation and how they should be used to support a wide range of
-output formats.
-
-This document describes the document classes and special markup used
-in the Python documentation.  Authors may use this guide, in
-conjunction with the template files provided with the
-distribution, to create or maintain whole documents or sections.
-
-If you're interested in contributing to Python's documentation,
-there's no need to learn \LaTeX{} if you're not so inclined; plain
-text contributions are more than welcome as well.
-\end{abstract}
-
-\tableofcontents
-
-
-\section{Introduction \label{intro}}
-
-  Python's documentation has long been considered to be good for a
-  free programming language.  There are a number of reasons for this,
-  the most important being the early commitment of Python's creator,
-  Guido van Rossum, to providing documentation on the language and its
-  libraries, and the continuing involvement of the user community in
-  providing assistance for creating and maintaining documentation.
-
-  The involvement of the community takes many forms, from authoring to
-  bug reports to just plain complaining when the documentation could
-  be more complete or easier to use.  All of these forms of input from
-  the community have proved useful during the time I've been involved
-  in maintaining the documentation.
-
-  This document is aimed at authors and potential authors of
-  documentation for Python.  More specifically, it is for people
-  contributing to the standard documentation and developing additional
-  documents using the same tools as the standard documents.  This
-  guide will be less useful for authors using the Python documentation
-  tools for topics other than Python, and less useful still for
-  authors not using the tools at all.
-
-  The material in this guide is intended to assist authors using the
-  Python documentation tools.  It includes information on the source
-  distribution of the standard documentation, a discussion of the
-  document types, reference material on the markup defined in the
-  document classes, a list of the external tools needed for processing
-  documents, and reference material on the tools provided with the
-  documentation resources.  At the end, there is also a section
-  discussing future directions for the Python documentation and where
-  to turn for more information.
-
-  If your interest is in contributing to the Python documentation, but
-  you don't have the time or inclination to learn \LaTeX{} and the
-  markup structures documented here, there's a welcoming place for you
-  among the Python contributors as well.  Any time you feel that you
-  can clarify existing documentation or provide documentation that's
-  missing, the existing documentation team will gladly work with you
-  to integrate your text, dealing with the markup for you.  Please
-  don't let the material in this document stand between the
-  documentation and your desire to help out!
-
-\section{Directory Structure \label{directories}}
-
-  The source distribution for the standard Python documentation
-  contains a large number of directories.  While third-party documents
-  do not need to be placed into this structure or need to be placed
-  within a similar structure, it can be helpful to know where to look
-  for examples and tools when developing new documents using the
-  Python documentation tools.  This section describes this directory
-  structure.
-
-  The documentation sources are usually placed within the Python
-  source distribution as the top-level directory \file{Doc/}, but
-  are not dependent on the Python source distribution in any way.
-
-  The \file{Doc/} directory contains a few files and several
-  subdirectories.  The files are mostly self-explanatory, including a
-  \file{README} and a \file{Makefile}.  The directories fall into
-  three categories:
-
-  \begin{definitions}
-    \term{Document Sources}
-        The \LaTeX{} sources for each document are placed in a
-        separate directory.  These directories are given short
-        names which vaguely indicate the document in each:
-
-        \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Document Title}
-          \lineii{api/}
-            {\citetitle[../api/api.html]{The Python/C API}}
-          \lineii{dist/}
-            {\citetitle[../dist/dist.html]{Distributing Python Modules}}
-          \lineii{doc/}
-            {\citetitle[../doc/doc.html]{Documenting Python}}
-          \lineii{ext/}
-            {\citetitle[../ext/ext.html]
-                       {Extending and Embedding the Python Interpreter}}
-          \lineii{inst/}
-            {\citetitle[../inst/inst.html]{Installing Python Modules}}
-          \lineii{lib/}
-            {\citetitle[../lib/lib.html]{Python Library Reference}}
-          \lineii{mac/}
-            {\citetitle[../mac/mac.html]{Macintosh Module Reference}}
-          \lineii{ref/}
-            {\citetitle[../ref/ref.html]{Python Reference Manual}}
-          \lineii{tut/}
-            {\citetitle[../tut/tut.html]{Python Tutorial}}
-          \lineii{whatsnew/}
-            {\citetitle[../whatsnew/whatsnew24.html]
-                       {What's New in Python \shortversion}}
-        \end{tableii}
-
-    \term{Format-Specific Output}
-        Most output formats have a directory which contains a
-        \file{Makefile} which controls the generation of that format
-        and provides storage for the formatted documents.  The only
-        variations within this category are the Portable Document
-        Format (PDF) and PostScript versions are placed in the
-        directories \file{paper-a4/} and \file{paper-letter/} (this
-        causes all the temporary files created by \LaTeX{} to be kept
-        in the same place for each paper size, where they can be more
-        easily ignored).
-
-        \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Output Formats}
-          \lineii{html/}{HTML output}
-          \lineii{info/}{GNU info output}
-          \lineii{isilo/}{\ulink{iSilo}{http://www.isilo.com/}
-                          documents (for Palm OS devices)}
-          \lineii{paper-a4/}{PDF and PostScript, A4 paper}
-          \lineii{paper-letter/}{PDF and PostScript, US-Letter paper}
-        \end{tableii}
-
-    \term{Supplemental Files}
-        Some additional directories are used to store supplemental
-        files used for the various processes.  Directories are
-        included for the shared \LaTeX{} document classes, the
-        \LaTeX2HTML support, template files for various document
-        components, and the scripts used to perform various steps in
-        the formatting processes.
-
-        \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Contents}
-          \lineii{commontex/}{Document content shared among documents}
-          \lineii{perl/}     {Support for \LaTeX2HTML processing}
-          \lineii{templates/}{Example files for source documents}
-          \lineii{texinputs/}{Style implementation for \LaTeX}
-          \lineii{tools/}    {Custom processing scripts}
-        \end{tableii}
-
-  \end{definitions}
-
-
-\section{Style Guide \label{style-guide}}
-
-  The Python documentation should follow the \citetitle
-  [http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf]
-  {Apple Publications Style Guide} wherever possible.  This particular
-  style guide was selected mostly because it seems reasonable and is
-  easy to get online.
-
-  Topics which are not covered in the Apple's style guide will be
-  discussed in this document if necessary.
-
-  Footnotes are generally discouraged due to the pain of using
-  footnotes in the HTML conversion of documents.  Footnotes may be
-  used when they are the best way to present specific information.
-  When a footnote reference is added at the end of the sentence, it
-  should follow the sentence-ending punctuation.  The \LaTeX{} markup
-  should appear something like this:
-
-\begin{verbatim}
-This sentence has a footnote reference.%
-  \footnote{This is the footnote text.}
-\end{verbatim}
-
-  Footnotes may appear in the middle of sentences where appropriate.
-
-  Many special names are used in the Python documentation, including
-  the names of operating systems, programming languages, standards
-  bodies, and the like.  Many of these were assigned \LaTeX{} macros
-  at some point in the distant past, and these macros lived on long
-  past their usefulness.  In the current markup, most of these entities
-  are not assigned any special markup, but the preferred spellings are
-  given here to aid authors in maintaining the consistency of
-  presentation in the Python documentation.
-
-  Other terms and words deserve special mention as well; these conventions
-  should be used to ensure consistency throughout the documentation:
-
-  \begin{description}
-    \item[CPU]
-    For ``central processing unit.''  Many style guides say this
-    should be spelled out on the first use (and if you must use it,
-    do so!).  For the Python documentation, this abbreviation should
-    be avoided since there's no reasonable way to predict which occurrence
-    will be the first seen by the reader.  It is better to use the
-    word ``processor'' instead.
-
-    \item[\POSIX]
-        The name assigned to a particular group of standards.  This is
-        always uppercase.  Use the macro \macro{POSIX} to represent this
-        name.
-
-    \item[Python]
-        The name of our favorite programming language is always
-        capitalized.
-
-    \item[Unicode]
-        The name of a character set and matching encoding.  This is
-        always written capitalized.
-
-    \item[\UNIX]
-        The name of the operating system developed at AT\&T Bell Labs
-        in the early 1970s.  Use the macro \macro{UNIX} to use this
-        name.
-  \end{description}
-
-
-\section{\LaTeX{} Primer \label{latex-primer}}
-
-  This section is a brief introduction to \LaTeX{} concepts and
-  syntax, to provide authors enough information to author documents
-  productively without having to become ``\TeX{}nicians.''  This does
-  not teach everything needed to know about writing \LaTeX{} for
-  Python documentation; many of the standard ``environments'' are not
-  described here (though you will learn how to mark something as an
-  environment).
-
-  Perhaps the most important concept to keep in mind while marking up
-  Python documentation is that while \TeX{} is unstructured, \LaTeX{} was
-  designed as a layer on top of \TeX{} which specifically supports
-  structured markup.  The Python-specific markup is intended to extend
-  the structure provided by standard \LaTeX{} document classes to
-  support additional information specific to Python.
-
-  \LaTeX{} documents contain two parts: the preamble and the body.
-  The preamble is used to specify certain metadata about the document
-  itself, such as the title, the list of authors, the date, and the
-  \emph{class} the document belongs to.  Additional information used
-  to control index generation and the use of bibliographic databases
-  can also be placed in the preamble.  For most authors, the preamble
-  can be most easily created by copying it from an existing document
-  and modifying a few key pieces of information.
-
-  The \dfn{class} of a document is used to place a document within a
-  broad category of documents and set some fundamental formatting
-  properties.  For Python documentation, two classes are used: the
-  \code{manual} class and the \code{howto} class.  These classes also
-  define the additional markup used to document Python concepts and
-  structures.  Specific information about these classes is provided in
-  section \ref{classes}, ``Document Classes,'' below.  The first thing
-  in the preamble is the declaration of the document's class.
-
-  After the class declaration, a number of \emph{macros} are used to
-  provide further information about the document and setup any
-  additional markup that is needed.  No output is generated from the
-  preamble; it is an error to include free text in the preamble
-  because it would cause output.
-
-  The document body follows the preamble.  This contains all the
-  printed components of the document marked up structurally.  Generic
-  \LaTeX{} structures include hierarchical sections, numbered and
-  bulleted lists, and special structures for the document abstract and
-  indexes.
-
-  \subsection{Syntax \label{latex-syntax}}
-
-    There are some things that an author of Python documentation needs
-    to know about \LaTeX{} syntax.
-
-    A \dfn{comment} is started by the ``percent'' character
-    (\character{\%}) and continues through the end of the line
-    \emph{and all leading whitespace on the following line}.  This is
-    a little different from any programming language I know of, so an
-    example is in order:
-
-\begin{verbatim}
-This is text.% comment
-    This is more text.  % another comment
-Still more text.
-\end{verbatim}
-
-    The first non-comment character following the first comment is the
-    letter \character{T} on the second line; the leading whitespace on
-    that line is consumed as part of the first comment.  This means
-    that there is no space between the first and second sentences, so
-    the period and letter \character{T} will be directly adjacent in
-    the typeset document.
-
-    Note also that though the first non-comment character after the
-    second comment is the letter \character{S}, there is whitespace
-    preceding the comment, so the two sentences are separated as
-    expected.
-
-    A \dfn{group} is an enclosure for a collection of text and
-    commands which encloses the formatting context and constrains the
-    scope of any changes to that context made by commands within the
-    group.  Groups can be nested hierarchically.  The formatting
-    context includes the font and the definition of additional macros
-    (or overrides of macros defined in outer groups).  Syntactically,
-    groups are enclosed in braces:
-
-\begin{verbatim}
-{text in a group}
-\end{verbatim}
-
-    An alternate syntax for a group using brackets, \code{[...]}, is
-    used by macros and environment constructors which take optional
-    parameters; brackets do not normally hold syntactic significance.
-    A degenerate group, containing only one atomic bit of content,
-    does not need to have an explicit group, unless it is required to
-    avoid ambiguity.  Since Python tends toward the explicit, groups
-    are also made explicit in the documentation markup.
-
-    Groups are used only sparingly in the Python documentation, except
-    for their use in marking parameters to macros and environments.
-
-    A \dfn{macro} is usually a simple construct which is identified by
-    name and can take some number of parameters.  In normal \LaTeX{}
-    usage, one of these can be optional.  The markup is introduced
-    using the backslash character (\character{\e}), and the name is
-    given by alphabetic characters (no digits, hyphens, or
-    underscores).  Required parameters should be marked as a group,
-    and optional parameters should be marked using the alternate
-    syntax for a group.
-
-    For example, a macro which takes a single parameter
-    would appear like this:
-
-\begin{verbatim}
-\name{parameter}
-\end{verbatim}
-
-    A macro which takes an optional parameter would be typed like this
-    when the optional parameter is given:
-
-\begin{verbatim}
-\name[optional]
-\end{verbatim}
-
-    If both optional and required parameters are to be required, it
-    looks like this:
-
-\begin{verbatim}
-\name[optional]{required}
-\end{verbatim}
-
-    A macro name may be followed by a space or newline; a space
-    between the macro name and any parameters will be consumed, but
-    this usage is not practiced in the Python documentation.  Such a
-    space is still consumed if there are no parameters to the macro,
-    in which case inserting an empty group (\code{\{\}}) or explicit
-    word space (\samp{\e\ }) immediately after the macro name helps to
-    avoid running the expansion of the macro into the following text.
-    Macros which take no parameters but which should not be followed
-    by a word space do not need special treatment if the following
-    character in the document source if not a name character (such as
-    punctuation).
-
-    Each line of this example shows an appropriate way to write text
-    which includes a macro which takes no parameters:
-
-\begin{verbatim}
-This \UNIX{} is followed by a space.
-This \UNIX\ is also followed by a space.
-\UNIX, followed by a comma, needs no additional markup.
-\end{verbatim}
-
-    An \dfn{environment} is a larger construct than a macro, and can
-    be used for things with more content than would conveniently fit
-    in a macro parameter.  They are primarily used when formatting
-    parameters need to be changed before and after a large chunk of
-    content, but the content itself needs to be highly flexible.  Code
-    samples are presented using an environment, and descriptions of
-    functions, methods, and classes are also marked using environments.
-
-    Since the content of an environment is free-form and can consist
-    of several paragraphs, they are actually marked using a pair of
-    macros: \macro{begin} and \macro{end}.  These macros both take the
-    name of the environment as a parameter.  An example is the
-    environment used to mark the abstract of a document:
-
-\begin{verbatim}
-\begin{abstract}
-  This is the text of the abstract.  It concisely explains what
-  information is found in the document.
-
-  It can consist of multiple paragraphs.
-\end{abstract}
-\end{verbatim}
-
-    An environment can also have required and optional parameters of
-    its own.  These follow the parameter of the \macro{begin} macro.
-    This example shows an environment which takes a single required
-    parameter:
-
-\begin{verbatim}
-\begin{datadesc}{controlnames}
-  A 33-element string array that contains the \ASCII{} mnemonics for
-  the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f
-  (US), in order, plus the mnemonic \samp{SP} for the space character.
-\end{datadesc}
-\end{verbatim}
-
-    There are a number of less-used marks in \LaTeX{} which are used
-    to enter characters which are not found in \ASCII{} or which a
-    considered special, or \emph{active} in \TeX{} or \LaTeX.  Given
-    that these are often used adjacent to other characters, the markup
-    required to produce the proper character may need to be followed
-    by a space or an empty group, or the markup can be enclosed in a
-    group.  Some which are found in Python documentation are:
-
-\begin{tableii}{c|l}{textrm}{Character}{Markup}
-  \lineii{\textasciicircum}{\code{\e textasciicircum}}
-  \lineii{\textasciitilde}{\code{\e textasciitilde}}
-  \lineii{\textgreater}{\code{\e textgreater}}
-  \lineii{\textless}{\code{\e textless}}
-  \lineii{\c c}{\code{\e c c}}
-  \lineii{\"o}{\code{\e"o}}
-  \lineii{\o}{\code{\e o}}
-\end{tableii}
-
-
-  \subsection{Hierarchical Structure \label{latex-structure}}
-
-    \LaTeX{} expects documents to be arranged in a conventional,
-    hierarchical way, with chapters, sections, sub-sections,
-    appendixes, and the like.  These are marked using macros rather
-    than environments, probably because the end of a section can be
-    safely inferred when a section of equal or higher level starts.
-
-    There are six ``levels'' of sectioning in the document classes
-    used for Python documentation, and the deepest two
-    levels\footnote{The deepest levels have the highest numbers in the
-      table.} are not used.  The levels are:
-
-      \begin{tableiii}{c|l|c}{textrm}{Level}{Macro Name}{Notes}
-        \lineiii{1}{\macro{chapter}}{(1)}
-        \lineiii{2}{\macro{section}}{}
-        \lineiii{3}{\macro{subsection}}{}
-        \lineiii{4}{\macro{subsubsection}}{}
-        \lineiii{5}{\macro{paragraph}}{(2)}
-        \lineiii{6}{\macro{subparagraph}}{}
-      \end{tableiii}
-
-    \noindent
-    Notes:
-
-    \begin{description}
-      \item[(1)]
-      Only used for the \code{manual} documents, as described in
-      section \ref{classes}, ``Document Classes.''
-      \item[(2)]
-      Not the same as a paragraph of text; nobody seems to use this.
-    \end{description}
-
-
-  \subsection{Common Environments \label{latex-environments}}
-
-    \LaTeX{} provides a variety of environments even without the
-    additional markup provided by the Python-specific document classes
-    introduced in the next section.  The following environments are
-    provided as part of standard \LaTeX{} and are being used in the
-    standard Python documentation; descriptions will be added here as
-    time allows.
-
-\begin{verbatim}
-abstract
-alltt
-description
-displaymath
-document
-enumerate
-figure
-flushleft
-itemize
-list
-math
-quotation
-quote
-sloppypar
-verbatim
-\end{verbatim}
-
-
-\section{Document Classes \label{classes}}
-
-  Two \LaTeX{} document classes are defined specifically for use with
-  the Python documentation.  The \code{manual} class is for large
-  documents which are sectioned into chapters, and the \code{howto}
-  class is for smaller documents.
-
-  The \code{manual} documents are larger and are used for most of the
-  standard documents.  This document class is based on the standard
-  \LaTeX{} \code{report} class and is formatted very much like a long
-  technical report.  The \citetitle[../ref/ref.html]{Python Reference
-  Manual} is a good example of a \code{manual} document, and the
-  \citetitle[../lib/lib.html]{Python Library Reference} is a large
-  example.
-
-  The \code{howto} documents are shorter, and don't have the large
-  structure of the \code{manual} documents.  This class is based on
-  the standard \LaTeX{} \code{article} class and is formatted somewhat
-  like the Linux Documentation Project's ``HOWTO'' series as done
-  originally using the LinuxDoc software.  The original intent for the
-  document class was that it serve a similar role as the LDP's HOWTO
-  series, but the applicability of the class turns out to be somewhat
-  broader.  This class is used for ``how-to'' documents (this
-  document is an example) and for shorter reference manuals for small,
-  fairly cohesive module libraries.  Examples of the later use include
-\citetitle[http://starship.python.net/crew/fdrake/manuals/krb5py/krb5py.html]{Using
-  Kerberos from Python}, which contains reference material for an
-  extension package.  These documents are roughly equivalent to a
-  single chapter from a larger work.
-
-
-\section{Special Markup Constructs \label{special-constructs}}
-
-  The Python document classes define a lot of new environments and
-  macros.  This section contains the reference material for these
-  facilities.  Documentation for ``standard'' \LaTeX{} constructs is
-  not included here, though they are used in the Python documentation.
-
-  \subsection{Markup for the Preamble \label{preamble-info}}
-
-    \begin{macrodesc}{release}{\p{ver}}
-      Set the version number for the software described in the
-      document.
-    \end{macrodesc}
-
-    \begin{macrodesc}{setshortversion}{\p{sver}}
-      Specify the ``short'' version number of the documented software
-      to be \var{sver}.
-    \end{macrodesc}
-
-  \subsection{Meta-information Markup \label{meta-info}}
-
-    \begin{macrodesc}{sectionauthor}{\p{author}\p{email}}
-      Identifies the author of the current section.  \var{author}
-      should be the author's name such that it can be used for
-      presentation (though it isn't), and \var{email} should be the
-      author's email address.  The domain name portion of
-      the address should be lower case.
-
-      No presentation is generated from this markup, but it is used to
-      help keep track of contributions.
-    \end{macrodesc}
-
-  \subsection{Information Units \label{info-units}}
-
-    XXX Explain terminology, or come up with something more ``lay.''
-
-    There are a number of environments used to describe specific
-    features provided by modules.  Each environment requires
-    parameters needed to provide basic information about what is being
-    described, and the environment content should be the description.
-    Most of these environments make entries in the general index (if
-    one is being produced for the document); if no index entry is
-    desired, non-indexing variants are available for many of these
-    environments.  The environments have names of the form
-    \code{\var{feature}desc}, and the non-indexing variants are named
-    \code{\var{feature}descni}.  The available variants are explicitly
-    included in the list below.
-
-    For each of these environments, the first parameter, \var{name},
-    provides the name by which the feature is accessed.
-
-    Environments which describe features of objects within a module,
-    such as object methods or data attributes, allow an optional
-    \var{type name} parameter.  When the feature is an attribute of
-    class instances, \var{type name} only needs to be given if the
-    class was not the most recently described class in the module; the
-    \var{name} value from the most recent \env{classdesc} is implied.
-    For features of built-in or extension types, the \var{type name}
-    value should always be provided.  Another special case includes
-    methods and members of general ``protocols,'' such as the
-    formatter and writer protocols described for the
-    \module{formatter} module: these may be documented without any
-    specific implementation classes, and will always require the
-    \var{type name} parameter to be provided.
-
-    \begin{envdesc}{cfuncdesc}{\p{type}\p{name}\p{args}}
-      Environment used to described a C function.  The \var{type}
-      should be specified as a \keyword{typedef} name, \code{struct
-      \var{tag}}, or the name of a primitive type.  If it is a pointer
-      type, the trailing asterisk should not be preceded by a space.
-      \var{name} should be the name of the function (or function-like
-      pre-processor macro), and \var{args} should give the types and
-      names of the parameters.  The names need to be given so they may
-      be used in the description.
-    \end{envdesc}
-
-    \begin{envdesc}{cmemberdesc}{\p{container}\p{type}\p{name}}
-      Description for a structure member.  \var{container} should be
-      the \keyword{typedef} name, if there is one, otherwise if should
-      be \samp{struct \var{tag}}.  The type of the member should given
-      as \var{type}, and the name should be given as \var{name}.  The
-      text of the description should include the range of values
-      allowed, how the value should be interpreted, and whether the
-      value can be changed.  References to structure members in text
-      should use the \macro{member} macro.
-    \end{envdesc}
-
-    \begin{envdesc}{csimplemacrodesc}{\p{name}}
-      Documentation for a ``simple'' macro.  Simple macros are macros
-      which are used for code expansion, but which do not take
-      arguments so cannot be described as functions.  This is not to
-      be used for simple constant definitions.  Examples of its use
-      in the Python documentation include
-      \csimplemacro{PyObject_HEAD} and
-      \csimplemacro{Py_BEGIN_ALLOW_THREADS}.
-    \end{envdesc}
-
-    \begin{envdesc}{ctypedesc}{\op{tag}\p{name}}
-      Environment used to described a C type.  The \var{name}
-      parameter should be the \keyword{typedef} name.  If the type is
-      defined as a \keyword{struct} without a \keyword{typedef},
-      \var{name} should have the form \code{struct \var{tag}}.
-      \var{name} will be added to the index unless \var{tag} is
-      provided, in which case \var{tag} will be used instead.
-      \var{tag} should not be used for a \keyword{typedef} name.
-    \end{envdesc}
-
-    \begin{envdesc}{cvardesc}{\p{type}\p{name}}
-      Description of a global C variable.  \var{type} should be the
-      \keyword{typedef} name, \code{struct \var{tag}}, or the name of
-      a primitive type.  If variable has a pointer type, the trailing
-      asterisk should \emph{not} be preceded by a space.
-    \end{envdesc}
-
-    \begin{envdesc}{datadesc}{\p{name}}
-      This environment is used to document global data in a module,
-      including both variables and values used as ``defined
-      constants.''  Class and object attributes are not documented
-      using this environment.
-    \end{envdesc}
-    \begin{envdesc}{datadescni}{\p{name}}
-      Like \env{datadesc}, but without creating any index entries.
-    \end{envdesc}
-
-    \begin{envdesc}{excclassdesc}{\p{name}\p{constructor parameters}}
-      Describe an exception defined by a class.  \var{constructor
-      parameters} should not include the \var{self} parameter or
-      the parentheses used in the call syntax.  To describe an
-      exception class without describing the parameters to its
-      constructor, use the \env{excdesc} environment.
-    \end{envdesc}
-
-    \begin{envdesc}{excdesc}{\p{name}}
-      Describe an exception.  In the case of class exceptions, the
-      constructor parameters are not described; use \env{excclassdesc}
-      to describe an exception class and its constructor.
-    \end{envdesc}
-
-    \begin{envdesc}{funcdesc}{\p{name}\p{parameters}}
-      Describe a module-level function.  \var{parameters} should
-      not include the parentheses used in the call syntax.  Object
-      methods are not documented using this environment.  Bound object
-      methods placed in the module namespace as part of the public
-      interface of the module are documented using this, as they are
-      equivalent to normal functions for most purposes.
-
-      The description should include information about the parameters
-      required and how they are used (especially whether mutable
-      objects passed as parameters are modified), side effects, and
-      possible exceptions.  A small example may be provided.
-    \end{envdesc}
-    \begin{envdesc}{funcdescni}{\p{name}\p{parameters}}
-      Like \env{funcdesc}, but without creating any index entries.
-    \end{envdesc}
-
-    \begin{envdesc}{classdesc}{\p{name}\p{constructor parameters}}
-      Describe a class and its constructor.  \var{constructor
-      parameters} should not include the \var{self} parameter or
-      the parentheses used in the call syntax.
-    \end{envdesc}
-
-    \begin{envdesc}{classdesc*}{\p{name}}
-      Describe a class without describing the constructor.  This can
-      be used to describe classes that are merely containers for
-      attributes or which should never be instantiated or subclassed
-      by user code.
-    \end{envdesc}
-
-    \begin{envdesc}{memberdesc}{\op{type name}\p{name}}
-      Describe an object data attribute.  The description should
-      include information about the type of the data to be expected
-      and whether it may be changed directly.
-    \end{envdesc}
-    \begin{envdesc}{memberdescni}{\op{type name}\p{name}}
-      Like \env{memberdesc}, but without creating any index entries.
-    \end{envdesc}
-
-    \begin{envdesc}{methoddesc}{\op{type name}\p{name}\p{parameters}}
-      Describe an object method.  \var{parameters} should not include
-      the \var{self} parameter or the parentheses used in the call
-      syntax.  The description should include similar information to
-      that described for \env{funcdesc}.
-    \end{envdesc}
-    \begin{envdesc}{methoddescni}{\op{type name}\p{name}\p{parameters}}
-      Like \env{methoddesc}, but without creating any index entries.
-    \end{envdesc}
-
-
-  \subsection{Showing Code Examples \label{showing-examples}}
-
-    Examples of Python source code or interactive sessions are
-    represented as \env{verbatim} environments.  This environment
-    is a standard part of \LaTeX{}.  It is important to only use
-    spaces for indentation in code examples since \TeX{} drops tabs
-    instead of converting them to spaces.
-
-    Representing an interactive session requires including the prompts
-    and output along with the Python code.  No special markup is
-    required for interactive sessions.  After the last line of input
-    or output presented, there should not be an ``unused'' primary
-    prompt; this is an example of what \emph{not} to do:
-
-\begin{verbatim}
->>> 1 + 1
-2
->>>
-\end{verbatim}
-
-    Within the \env{verbatim} environment, characters special to
-    \LaTeX{} do not need to be specially marked in any way.  The entire
-    example will be presented in a monospaced font; no attempt at
-    ``pretty-printing'' is made, as the environment must work for
-    non-Python code and non-code displays.  There should be no blank
-    lines at the top or bottom of any \env{verbatim} display.
-
-    Longer displays of verbatim text may be included by storing the
-    example text in an external file containing only plain text.  The
-    file may be included using the standard \macro{verbatiminput}
-    macro; this macro takes a single argument naming the file
-    containing the text.  For example, to include the Python source
-    file \file{example.py}, use:
-
-\begin{verbatim}
-\verbatiminput{example.py}
-\end{verbatim}
-
-    Use of \macro{verbatiminput} allows easier use of special editing
-    modes for the included file.  The file should be placed in the
-    same directory as the \LaTeX{} files for the document.
-
-    The Python Documentation Special Interest Group has discussed a
-    number of approaches to creating pretty-printed code displays and
-    interactive sessions; see the Doc-SIG area on the Python Web site
-    for more information on this topic.
-
-
-  \subsection{Inline Markup \label{inline-markup}}
-
-    The macros described in this section are used to mark just about
-    anything interesting in the document text.  They may be used in
-    headings (though anything involving hyperlinks should be avoided
-    there) as well as in the body text.
-
-    \begin{macrodesc}{bfcode}{\p{text}}
-      Like \macro{code}, but also makes the font bold-face.
-    \end{macrodesc}
-
-    \begin{macrodesc}{cdata}{\p{name}}
-      The name of a C-language variable.
-    \end{macrodesc}
-
-    \begin{macrodesc}{cfunction}{\p{name}}
-      The name of a C-language function.  \var{name} should include the
-      function name and the trailing parentheses.
-    \end{macrodesc}
-
-    \begin{macrodesc}{character}{\p{char}}
-      A character when discussing the character rather than a one-byte
-      string value.  The character will be typeset as with \macro{samp}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{citetitle}{\op{url}\p{title}}
-      A title for a referenced publication.  If \var{url} is specified,
-      the title will be made into a hyperlink when formatted as HTML.
-    \end{macrodesc}
-
-    \begin{macrodesc}{class}{\p{name}}
-      A class name; a dotted name may be used.
-    \end{macrodesc}
-
-    \begin{macrodesc}{code}{\p{text}}
-      A short code fragment or literal constant value.  Typically, it
-      should not include any spaces since no quotation marks are
-      added.
-    \end{macrodesc}
-
-    \begin{macrodesc}{constant}{\p{name}}
-      The name of a ``defined'' constant.  This may be a C-language
-      \code{\#define} or a Python variable that is not intended to be
-      changed.
-    \end{macrodesc}
-
-    \begin{macrodesc}{csimplemacro}{\p{name}}
-      The name of a ``simple'' macro.  Simple macros are macros
-      which are used for code expansion, but which do not take
-      arguments so cannot be described as functions.  This is not to
-      be used for simple constant definitions.  Examples of its use
-      in the Python documentation include
-      \csimplemacro{PyObject_HEAD} and
-      \csimplemacro{Py_BEGIN_ALLOW_THREADS}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{ctype}{\p{name}}
-      The name of a C \keyword{typedef} or structure.  For structures
-      defined without a \keyword{typedef}, use \code{\e ctype\{struct
-      struct_tag\}} to make it clear that the \keyword{struct} is
-      required.
-    \end{macrodesc}
-
-    \begin{macrodesc}{deprecated}{\p{version}\p{what to do}}
-      Declare whatever is being described as being deprecated starting
-      with release \var{version}.  The text given as \var{what to do}
-      should recommend something to use instead.  It should be
-      complete sentences.  The entire deprecation notice will be
-      presented as a separate paragraph; it should either precede or
-      succeed the description of the deprecated feature.
-    \end{macrodesc}
-
-    \begin{macrodesc}{dfn}{\p{term}}
-      Mark the defining instance of \var{term} in the text.  (No index
-      entries are generated.)
-    \end{macrodesc}
-
-    \begin{macrodesc}{e}{}
-      Produces a backslash.  This is convenient in \macro{code},
-      \macro{file}, and similar macros, and the \env{alltt}
-      environment, and is only defined there.  To
-      create a backslash in ordinary text (such as the contents of the
-      \macro{citetitle} macro), use the standard \macro{textbackslash}
-      macro.
-    \end{macrodesc}
-
-    \begin{macrodesc}{email}{\p{address}}
-      An email address.  Note that this is \emph{not} hyperlinked in
-      any of the possible output formats.  The domain name portion of
-      the address should be lower case.
-    \end{macrodesc}
-
-    \begin{macrodesc}{emph}{\p{text}}
-      Emphasized text; this will be presented in an italic font.
-    \end{macrodesc}
-
-    \begin{macrodesc}{envvar}{\p{name}}
-      An environment variable.  Index entries are generated.
-    \end{macrodesc}
-
-    \begin{macrodesc}{exception}{\p{name}}
-      The name of an exception.  A dotted name may be used.
-    \end{macrodesc}
-
-    \begin{macrodesc}{file}{\p{file or dir}}
-      The name of a file or directory.  In the PDF and PostScript
-      outputs, single quotes and a font change are used to indicate
-      the file name, but no quotes are used in the HTML output.
-      \warning{The \macro{file} macro cannot be used in the
-      content of a section title due to processing limitations.}
-    \end{macrodesc}
-
-    \begin{macrodesc}{filenq}{\p{file or dir}}
-      Like \macro{file}, but single quotes are never used.  This can
-      be used in conjunction with tables if a column will only contain
-      file or directory names.
-      \warning{The \macro{filenq} macro cannot be used in the
-      content of a section title due to processing limitations.}
-    \end{macrodesc}
-
-    \begin{macrodesc}{function}{\p{name}}
-      The name of a Python function; dotted names may be used.
-    \end{macrodesc}
-
-    \begin{macrodesc}{infinity}{}
-      The symbol for mathematical infinity: \infinity.  Some Web
-      browsers are not able to render the HTML representation of this
-      symbol properly, but support is growing.
-    \end{macrodesc}
-
-    \begin{macrodesc}{kbd}{\p{key sequence}}
-      Mark a sequence of keystrokes.  What form \var{key sequence}
-      takes may depend on platform- or application-specific
-      conventions.  When there are no relevant conventions, the names
-      of modifier keys should be spelled out, to improve accessibility
-      for new users and non-native speakers.  For example, an
-      \program{xemacs} key sequence may be marked like
-      \code{\e kbd\{C-x C-f\}}, but without reference to a specific
-      application or platform, the same sequence should be marked as
-      \code{\e kbd\{Control-x Control-f\}}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{keyword}{\p{name}}
-      The name of a keyword in a programming language.
-    \end{macrodesc}
-
-    \begin{macrodesc}{mailheader}{\p{name}}
-      The name of an \rfc{822}-style mail header.  This markup does
-      not imply that the header is being used in an email message, but
-      can be used to refer to any header of the same ``style.''  This
-      is also used for headers defined by the various MIME
-      specifications.  The header name should be entered in the same
-      way it would normally be found in practice, with the
-      camel-casing conventions being preferred where there is more
-      than one common usage.  The colon which follows the name of the
-      header should not be included.
-      For example: \code{\e mailheader\{Content-Type\}}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{makevar}{\p{name}}
-      The name of a \program{make} variable.
-    \end{macrodesc}
-
-    \begin{macrodesc}{manpage}{\p{name}\p{section}}
-      A reference to a \UNIX{} manual page.
-    \end{macrodesc}
-
-    \begin{macrodesc}{member}{\p{name}}
-      The name of a data attribute of an object.
-    \end{macrodesc}
-
-    \begin{macrodesc}{method}{\p{name}}
-      The name of a method of an object.  \var{name} should include the
-      method name and the trailing parentheses.  A dotted name may be
-      used.
-    \end{macrodesc}
-
-    \begin{macrodesc}{mimetype}{\p{name}}
-      The name of a MIME type, or a component of a MIME type (the
-      major or minor portion, taken alone).
-    \end{macrodesc}
-
-    \begin{macrodesc}{module}{\p{name}}
-       The name of a module; a dotted name may be used.  This should
-       also be used for package names.
-    \end{macrodesc}
-
-    \begin{macrodesc}{newsgroup}{\p{name}}
-      The name of a Usenet newsgroup.
-    \end{macrodesc}
-
-    \begin{macrodesc}{note}{\p{text}}
-      An especially important bit of information about an API that a
-      user should be aware of when using whatever bit of API the
-      note pertains to.  This should be the last thing in the
-      paragraph as the end of the note is not visually marked in
-      any way.  The content of \var{text} should be written in
-      complete sentences and include all appropriate punctuation.
-    \end{macrodesc}
-
-    \begin{macrodesc}{pep}{\p{number}}
-      A reference to a Python Enhancement Proposal.  This generates
-      appropriate index entries.  The text \samp{PEP \var{number}} is
-      generated; in the HTML output, this text is a hyperlink to an
-      online copy of the specified PEP.
-    \end{macrodesc}
-
-    \begin{macrodesc}{plusminus}{}
-      The symbol for indicating a value that may take a positive or
-      negative value of a specified magnitude, typically represented
-      by a plus sign placed over a minus sign.  For example:
-      \code{\e plusminus 3\%{}}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{program}{\p{name}}
-      The name of an executable program.  This may differ from the
-      file name for the executable for some platforms.  In particular,
-      the \file{.exe} (or other) extension should be omitted for
-      Windows programs.
-    \end{macrodesc}
-
-    \begin{macrodesc}{programopt}{\p{option}}
-      A command-line option to an executable program.  Use this only
-      for ``short'' options, and include the leading hyphen.
-    \end{macrodesc}
-
-    \begin{macrodesc}{longprogramopt}{\p{option}}
-      A long command-line option to an executable program.  This
-      should only be used for long option names which will be prefixed
-      by two hyphens; the hyphens should not be provided as part of
-      \var{option}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{refmodule}{\op{key}\p{name}}
-      Like \macro{module}, but create a hyperlink to the documentation
-      for the named module.  Note that the corresponding
-      \macro{declaremodule} must be in the same document.  If the
-      \macro{declaremodule} defines a module key different from the
-      module name, it must also be provided as \var{key} to the
-      \macro{refmodule} macro.
-    \end{macrodesc}
-
-    \begin{macrodesc}{regexp}{\p{string}}
-      Mark a regular expression.
-    \end{macrodesc}
-
-    \begin{macrodesc}{rfc}{\p{number}}
-      A reference to an Internet Request for Comments.  This generates
-      appropriate index entries.  The text \samp{RFC \var{number}} is
-      generated; in the HTML output, this text is a hyperlink to an
-      online copy of the specified RFC.
-    \end{macrodesc}
-
-    \begin{macrodesc}{samp}{\p{text}}
-      A short code sample, but possibly longer than would be given
-      using \macro{code}.  Since quotation marks are added, spaces are
-      acceptable.
-    \end{macrodesc}
-
-    \begin{macrodesc}{shortversion}{}
-      The ``short'' version number of the documented software, as
-      specified using the \macro{setshortversion} macro in the
-      preamble.  For Python, the short version number for a release is
-      the first three characters of the \code{sys.version} value.  For
-      example, versions 2.0b1 and 2.0.1 both have a short version of
-      2.0.  This may not apply for all packages; if
-      \macro{setshortversion} is not used, this produces an empty
-      expansion.  See also the \macro{version} macro.
-    \end{macrodesc}
-
-    \begin{macrodesc}{strong}{\p{text}}
-      Strongly emphasized text; this will be presented using a bold
-      font.
-    \end{macrodesc}
-
-    \begin{macrodesc}{ulink}{\p{text}\p{url}}
-      A hypertext link with a target specified by a URL, but for which
-      the link text should not be the title of the resource.  For
-      resources being referenced by name, use the \macro{citetitle}
-      macro.  Not all formatted versions support arbitrary hypertext
-      links.  Note that many characters are special to \LaTeX{} and
-      this macro does not always do the right thing.  In particular,
-      the tilde character (\character{\~}) is mis-handled; encoding it
-      as a hex-sequence does work, use \samp{\%7e} in place of the
-      tilde character.
-    \end{macrodesc}
-
-    \begin{macrodesc}{url}{\p{url}}
-      A URL (or URN).  The URL will be presented as text.  In the HTML
-      and PDF formatted versions, the URL will also be a hyperlink.
-      This can be used when referring to external resources without
-      specific titles; references to resources which have titles
-      should be marked using the \macro{citetitle} macro.  See the
-      comments about special characters in the description of the
-      \macro{ulink} macro for special considerations.
-    \end{macrodesc}
-
-    \begin{macrodesc}{var}{\p{name}}
-      The name of a variable or formal parameter in running text.
-    \end{macrodesc}
-
-    \begin{macrodesc}{version}{}
-      The version number of the described software, as specified using
-      \macro{release} in the preamble.  See also the
-      \macro{shortversion} macro.
-    \end{macrodesc}
-
-    \begin{macrodesc}{warning}{\p{text}}
-      An important bit of information about an API that a user should
-      be very aware of when using whatever bit of API the warning
-      pertains to.  This should be the last thing in the paragraph as
-      the end of the warning is not visually marked in any way.  The
-      content of \var{text} should be written in complete sentences
-      and include all appropriate punctuation.  This differs from
-      \macro{note} in that it is recommended over \macro{note} for
-      information regarding security.
-    \end{macrodesc}
-
-    The following two macros are used to describe information that's
-    associated with changes from one release to another.  For features
-    which are described by a single paragraph, these are typically
-    added as separate source lines at the end of the paragraph.  When
-    adding these to features described by multiple paragraphs, they
-    are usually collected in a single separate paragraph after the
-    description.  When both \macro{versionadded} and
-    \macro{versionchanged} are used, \macro{versionadded} should come
-    first; the versions should be listed in chronological order.  Both
-    of these should come before availability statements.  The location
-    should be selected so the explanation makes sense and may vary as
-    needed.
-
-    \begin{macrodesc}{versionadded}{\op{explanation}\p{version}}
-      The version of Python which added the described feature to the
-      library or C API.  \var{explanation} should be a \emph{brief}
-      explanation of the change consisting of a capitalized sentence
-      fragment; a period will be appended by the formatting process.
-      When this applies to an entire module, it should be placed at
-      the top of the module section before any prose.
-    \end{macrodesc}
-
-    \begin{macrodesc}{versionchanged}{\op{explanation}\p{version}}
-      The version of Python in which the named feature was changed in
-      some way (new parameters, changed side effects, etc.).
-      \var{explanation} should be a \emph{brief} explanation of the
-      change consisting of a capitalized sentence fragment; a
-      period will be appended by the formatting process.  This should
-      not generally be applied to modules.
-    \end{macrodesc}
-
-
-  \subsection{Miscellaneous Text Markup \label{misc-text-markup}}
-
-  In addition to the inline markup, some additional ``block'' markup
-  is defined to make it easier to bring attention to various bits of
-  text.  The markup described here serves this purpose, and is
-  intended to be used when marking one or more paragraphs or other
-  block constructs (such as \env{verbatim} environments).
-
-  \begin{envdesc}{notice}{\op{type}}
-    Label some paragraphs as being worthy of additional attention from
-    the reader.  What sort of attention is warranted can be indicated
-    by specifying the \var{type} of the notice.  The only values
-    defined for \var{type} are \code{note} and \code{warning}; these
-    are equivalent in intent to the inline markup of the same name.
-    If \var{type} is omitted, \code{note} is used.  Additional values
-    may be defined in the future.
-  \end{envdesc}
-
-
-  \subsection{Module-specific Markup \label{module-markup}}
-
-  The markup described in this section is used to provide information
-  about a module being documented.  Each module should be documented
-  in its own \macro{section}.  A typical use of this markup
-  appears at the top of that section and might look like this:
-
-\begin{verbatim}
-\section{\module{spam} ---
-         Access to the SPAM facility}
-
-\declaremodule{extension}{spam}
-  \platform{Unix}
-\modulesynopsis{Access to the SPAM facility of \UNIX.}
-\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
-\end{verbatim}
-
-  Python packages\index{packages} --- collections of modules that can
-  be described as a unit --- are documented using the same markup as
-  modules.  The name for a module in a package should be typed in
-  ``fully qualified'' form (it should include the package name).
-  For example, a module ``foo'' in package ``bar'' should be marked as
-  \code{\e module\{bar.foo\}}, and the beginning of the reference
-  section would appear as:
-
-\begin{verbatim}
-\section{\module{bar.foo} ---
-         Module from the \module{bar} package}
-
-\declaremodule{extension}{bar.foo}
-\modulesynopsis{Nifty module from the \module{bar} package.}
-\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
-\end{verbatim}
-
-  Note that the name of a package is also marked using
-  \macro{module}.
-
-  \begin{macrodesc}{declaremodule}{\op{key}\p{type}\p{name}}
-    Requires two parameters: module type (\samp{standard},
-    \samp{builtin}, \samp{extension}, or \samp{}), 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 any
-    underscores, and should be the name with the underscores stripped.
-    Note that the \var{type} parameter must be one of the values
-    listed above or an error will be printed.  For modules which are
-    contained in packages, the fully-qualified name should be given as
-    \var{name} parameter.  This should be the first thing after the
-    \macro{section} used to introduce the module.
-  \end{macrodesc}
-
-  \begin{macrodesc}{platform}{\p{specifier}}
-    Specifies the portability of the module.  \var{specifier} is a
-    comma-separated list of keys that specify what platforms the
-    module is available on.  The keys are short identifiers;
-    examples that are in use include \samp{IRIX}, \samp{Mac},
-    \samp{Windows}, and \samp{Unix}.  It is important to use a key
-    which has already been used when applicable.  This is used to
-    provide annotations in the Module Index and the HTML and GNU info
-    output.
-  \end{macrodesc}
-
-  \begin{macrodesc}{modulesynopsis}{\p{text}}
-    The \var{text} is a short, ``one line'' description of the
-    module that can be used as part of the chapter introduction.
-    This is must be placed after \macro{declaremodule}.
-    The synopsis is used in building the contents of the table
-    inserted as the \macro{localmoduletable}.  No text is
-    produced at the point of the markup.
-  \end{macrodesc}
-
-  \begin{macrodesc}{moduleauthor}{\p{name}\p{email}}
-    This macro is used to encode information about who authored a
-    module.  This is currently not used to generate output, but can be
-    used to help determine the origin of the module.
-  \end{macrodesc}
-
-
-  \subsection{Library-level Markup \label{library-markup}}
-
-    This markup is used when describing a selection of modules.  For
-    example, the \citetitle[../mac/mac.html]{Macintosh Library
-    Modules} document uses this to help provide an overview of the
-    modules in the collection, and many chapters in the
-    \citetitle[../lib/lib.html]{Python Library Reference} use it for
-    the same purpose.
-
-  \begin{macrodesc}{localmoduletable}{}
-    If a \file{.syn} file exists for the current
-    chapter (or for the entire document in \code{howto} documents), a
-    \env{synopsistable} is created with the contents loaded from the
-    \file{.syn} file.
-  \end{macrodesc}
-
-
-  \subsection{Table Markup \label{table-markup}}
-
-    There are three general-purpose table environments defined which
-    should be used whenever possible.  These environments are defined
-    to provide tables of specific widths and some convenience for
-    formatting.  These environments are not meant to be general
-    replacements for the standard \LaTeX{} table environments, but can
-    be used for an advantage when the documents are processed using
-    the tools for Python documentation processing.  In particular, the
-    generated HTML looks good!  There is also an advantage for the
-    eventual conversion of the documentation to XML (see section
-    \ref{futures}, ``Future Directions'').
-
-    Each environment is named \env{table\var{cols}}, where \var{cols}
-    is the number of columns in the table specified in lower-case
-    Roman numerals.  Within each of these environments, an additional
-    macro, \macro{line\var{cols}}, is defined, where \var{cols}
-    matches the \var{cols} value of the corresponding table
-    environment.  These are supported for \var{cols} values of
-    \code{ii}, \code{iii}, and \code{iv}.  These environments are all
-    built on top of the \env{tabular} environment.  Variants based on
-    the \env{longtable} environment are also provided.
-
-    Note that all tables in the standard Python documentation use
-    vertical lines between columns, and this must be specified in the
-    markup for each table.  A general border around the outside of the
-    table is not used, but would be the responsibility of the
-    processor; the document markup should not include an exterior
-    border.
-
-    The \env{longtable}-based variants of the table environments are
-    formatted with extra space before and after, so should only be
-    used on tables which are long enough that splitting over multiple
-    pages is reasonable; tables with fewer than twenty rows should
-    never by marked using the long flavors of the table environments.
-    The header row is repeated across the top of each part of the
-    table.
-
-    \begin{envdesc}{tableii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}}
-      Create a two-column table using the \LaTeX{} column specifier
-      \var{colspec}.  The column specifier should indicate vertical
-      bars between columns as appropriate for the specific table, but
-      should not specify vertical bars on the outside of the table
-      (that is considered a stylesheet issue).  The \var{col1font}
-      parameter is used as a stylistic treatment of the first column
-      of the table: the first column is presented as
-      \code{\e\var{col1font}\{column1\}}.  To avoid treating the first
-      column specially, \var{col1font} may be \samp{textrm}.  The
-      column headings are taken from the values \var{heading1} and
-      \var{heading2}.
-    \end{envdesc}
-
-    \begin{envdesc}{longtableii}{\unspecified}
-      Like \env{tableii}, but produces a table which may be broken
-      across page boundaries.  The parameters are the same as for
-      \env{tableii}.
-    \end{envdesc}
-
-    \begin{macrodesc}{lineii}{\p{column1}\p{column2}}
-      Create a single table row within a \env{tableii} or
-      \env{longtableii} environment.
-      The text for the first column will be generated by applying the
-      macro named by the \var{col1font} value when the \env{tableii}
-      was opened.
-    \end{macrodesc}
-
-    \begin{envdesc}{tableiii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}}
-      Like the \env{tableii} environment, but with a third column.
-      The heading for the third column is given by \var{heading3}.
-    \end{envdesc}
-
-    \begin{envdesc}{longtableiii}{\unspecified}
-      Like \env{tableiii}, but produces a table which may be broken
-      across page boundaries.  The parameters are the same as for
-      \env{tableiii}.
-    \end{envdesc}
-
-    \begin{macrodesc}{lineiii}{\p{column1}\p{column2}\p{column3}}
-      Like the \macro{lineii} macro, but with a third column.  The
-      text for the third column is given by \var{column3}.
-    \end{macrodesc}
-
-    \begin{envdesc}{tableiv}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}\p{heading4}}
-      Like the \env{tableiii} environment, but with a fourth column.
-      The heading for the fourth column is given by \var{heading4}.
-    \end{envdesc}
-
-    \begin{envdesc}{longtableiv}{\unspecified}
-      Like \env{tableiv}, but produces a table which may be broken
-      across page boundaries.  The parameters are the same as for
-      \env{tableiv}.
-    \end{envdesc}
-
-    \begin{macrodesc}{lineiv}{\p{column1}\p{column2}\p{column3}\p{column4}}
-      Like the \macro{lineiii} macro, but with a fourth column.  The
-      text for the fourth column is given by \var{column4}.
-    \end{macrodesc}
-
-    \begin{envdesc}{tablev}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}\p{heading4}\p{heading5}}
-      Like the \env{tableiv} environment, but with a fifth column.
-      The heading for the fifth column is given by \var{heading5}.
-    \end{envdesc}
-
-    \begin{envdesc}{longtablev}{\unspecified}
-      Like \env{tablev}, but produces a table which may be broken
-      across page boundaries.  The parameters are the same as for
-      \env{tablev}.
-    \end{envdesc}
-
-    \begin{macrodesc}{linev}{\p{column1}\p{column2}\p{column3}\p{column4}\p{column5}}
-      Like the \macro{lineiv} macro, but with a fifth column.  The
-      text for the fifth column is given by \var{column5}.
-    \end{macrodesc}
-
-
-    An additional table-like environment is \env{synopsistable}.  The
-    table generated by this environment contains two columns, and each
-    row is defined by an alternate definition of
-    \macro{modulesynopsis}.  This environment is not normally used by
-    authors, but is created by the \macro{localmoduletable} macro.
-
-    Here is a small example of a table given in the documentation for
-    the \module{warnings} module; markup inside the table cells is
-    minimal so the markup for the table itself is readily discernable.
-    Here is the markup for the table:
-
-\begin{verbatim}
-\begin{tableii}{l|l}{exception}{Class}{Description}
-  \lineii{Warning}
-         {This is the base class of all warning category classes.  It
-          is a subclass of \exception{Exception}.}
-  \lineii{UserWarning}
-         {The default category for \function{warn()}.}
-  \lineii{DeprecationWarning}
-         {Base category for warnings about deprecated features.}
-  \lineii{SyntaxWarning}
-         {Base category for warnings about dubious syntactic
-          features.}
-  \lineii{RuntimeWarning}
-         {Base category for warnings about dubious runtime features.}
-  \lineii{FutureWarning}
-         {Base category for warnings about constructs that will change
-         semantically in the future.}
-\end{tableii}
-\end{verbatim}
-
-    Here is the resulting table:
-
-\begin{tableii}{l|l}{exception}{Class}{Description}
-  \lineii{Warning}
-         {This is the base class of all warning category classes.  It
-          is a subclass of \exception{Exception}.}
-  \lineii{UserWarning}
-         {The default category for \function{warn()}.}
-  \lineii{DeprecationWarning}
-         {Base category for warnings about deprecated features.}
-  \lineii{SyntaxWarning}
-         {Base category for warnings about dubious syntactic
-          features.}
-  \lineii{RuntimeWarning}
-         {Base category for warnings about dubious runtime features.}
-\end{tableii}
-
-    Note that the class names are implicitly marked using the
-    \macro{exception} macro, since that is given as the \var{col1font}
-    value for the \env{tableii} environment.  To create a table using
-    different markup for the first column, use \code{textrm} for the
-    \var{col1font} value and mark each entry individually.
-
-    To add a horizontal line between vertical sections of a table, use
-    the standard \macro{hline} macro between the rows which should be
-    separated:
-
-\begin{verbatim}
-\begin{tableii}{l|l}{constant}{Language}{Audience}
-  \lineii{APL}{Masochists.}
-  \lineii{BASIC}{First-time programmers on PC hardware.}
-  \lineii{C}{\UNIX{} \&\ Linux kernel developers.}
-    \hline
-  \lineii{Python}{Everyone!}
-\end{tableii}
-\end{verbatim}
-
-    Note that not all presentation formats are capable of displaying a
-    horizontal rule in this position.  This is how the table looks in
-    the format you're reading now:
-
-\begin{tableii}{l|l}{constant}{Language}{Audience}
-  \lineii{APL}{Masochists.}
-  \lineii{C}{\UNIX{} \&\ Linux kernel developers.}
-  \lineii{JavaScript}{Web developers.}
-    \hline
-  \lineii{Python}{Everyone!}
-\end{tableii}
-
-
-  \subsection{Reference List Markup \label{references}}
-
-    Many sections include a list of references to module documentation
-    or external documents.  These lists are created using the
-    \env{seealso} or \env{seealso*} environments.  These environments
-    define some additional macros to support creating reference
-    entries in a reasonable manner.
-
-    The \env{seealso} environment is typically placed in a section
-    just before any sub-sections.  This is done to ensure that
-    reference links related to the section are not hidden in a
-    subsection in the hypertext renditions of the documentation.  For
-    the HTML output, it is shown as a ``side bar,'' boxed off from the
-    main flow of the text.  The \env{seealso*} environment is
-    different in that it should be used when a list of references is
-    being presented as part of the primary content; it is not
-    specially set off from the text.
-
-    \begin{envdesc}{seealso}{}
-      This environment creates a ``See also:'' heading and defines the
-      markup used to describe individual references.
-    \end{envdesc}
-
-    \begin{envdesc}{seealso*}{}
-      This environment is used to create a list of references which
-      form part of the main content.  It is not given a special
-      header and is not set off from the main flow of the text.  It
-      provides the same additional markup used to describe individual
-      references.
-    \end{envdesc}
-
-    For each of the following macros, \var{why} should be one or more
-    complete sentences, starting with a capital letter (unless it
-    starts with an identifier, which should not be modified), and
-    ending with the appropriate punctuation.
-
-    These macros are only defined within the content of the
-    \env{seealso} and \env{seealso*} environments.
-
-    \begin{macrodesc}{seelink}{\p{url}\p{linktext}\p{why}}
-      References to specific on-line resources should be given using
-      the \macro{seelink} macro if they don't have a meaningful title
-      but there is some short description of what's at the end of the
-      link.  Online documents which have identifiable titles should be
-      referenced using the \macro{seetitle} macro, using the optional
-      parameter to that macro to provide the URL.
-    \end{macrodesc}
-
-    \begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
-      Refer to another module.  \var{why} should be a brief
-      explanation of why the reference may be interesting.  The module
-      name is given in \var{name}, with the link key given in
-      \var{key} if necessary.  In the HTML and PDF conversions, the
-      module name will be a hyperlink to the referred-to module.
-      \note{The module must be documented in the same
-      document (the corresponding \macro{declaremodule} is required).}
-    \end{macrodesc}
-
-    \begin{macrodesc}{seepep}{\p{number}\p{title}\p{why}}
-      Refer to an Python Enhancement Proposal (PEP).  \var{number}
-      should be the official number assigned by the PEP Editor,
-      \var{title} should be the human-readable title of the PEP as
-      found in the official copy of the document, and \var{why} should
-      explain what's interesting about the PEP.  This should be used
-      to refer the reader to PEPs which specify interfaces or language
-      features relevant to the material in the annotated section of the
-      documentation.
-    \end{macrodesc}
-
-    \begin{macrodesc}{seerfc}{\p{number}\p{title}\p{why}}
-      Refer to an IETF Request for Comments (RFC).  Otherwise very
-      similar to \macro{seepep}.  This should be used
-      to refer the reader to PEPs which specify protocols or data
-      formats relevant to the material in the annotated section of the
-      documentation.
-    \end{macrodesc}
-
-    \begin{macrodesc}{seetext}{\p{text}}
-      Add arbitrary text \var{text} to the ``See also:'' list.  This
-      can be used to refer to off-line materials or on-line materials
-      using the \macro{url} macro.  This should consist of one or more
-      complete sentences.
-    \end{macrodesc}
-
-    \begin{macrodesc}{seetitle}{\op{url}\p{title}\p{why}}
-      Add a reference to an external document named \var{title}.  If
-      \var{url} is given, the title is made a hyperlink in the HTML
-      version of the documentation, and displayed below the title in
-      the typeset versions of the documentation.
-    \end{macrodesc}
-
-    \begin{macrodesc}{seeurl}{\p{url}\p{why}}
-      References to specific on-line resources should be given using
-      the \macro{seeurl} macro if they don't have a meaningful title.
-      Online documents which have identifiable titles should be
-      referenced using the \macro{seetitle} macro, using the optional
-      parameter to that macro to provide the URL.
-    \end{macrodesc}
-
-
-  \subsection{Index-generating Markup \label{indexing}}
-
-    Effective index generation for technical documents can be very
-    difficult, especially for someone familiar with the topic but not
-    the creation of indexes.  Much of the difficulty arises in the
-    area of terminology: including the terms an expert would use for a
-    concept is not sufficient.  Coming up with the terms that a novice
-    would look up is fairly difficult for an author who, typically, is
-    an expert in the area she is writing on.
-
-    The truly difficult aspects of index generation are not areas with
-    which the documentation tools can help.  However, ease
-    of producing the index once content decisions are made is within
-    the scope of the tools.  Markup is provided which the processing
-    software is able to use to generate a variety of kinds of index
-    entry with minimal effort.  Additionally, many of the environments
-    described in section \ref{info-units}, ``Information Units,'' will
-    generate appropriate entries into the general and module indexes.
-
-    The following macro can be used to control the generation of index
-    data, and should be used in the document preamble:
-
-    \begin{macrodesc}{makemodindex}{}
-      This should be used in the document preamble if a ``Module
-      Index'' is desired for a document containing reference material
-      on many modules.  This causes a data file
-      \code{lib\var{jobname}.idx} to be created from the
-      \macro{declaremodule} macros.  This file can be processed by the
-      \program{makeindex} program to generate a file which can be
-      \macro{input} into the document at the desired location of the
-      module index.
-    \end{macrodesc}
-
-    There are a number of macros that are useful for adding index
-    entries for particular concepts, many of which are specific to
-    programming languages or even Python.
-
-    \begin{macrodesc}{bifuncindex}{\p{name}}
-      Add an index entry referring to a built-in function named
-      \var{name}; parentheses should not be included after
-      \var{name}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{exindex}{\p{exception}}
-      Add a reference to an exception named \var{exception}.  The
-      exception should be class-based.
-    \end{macrodesc}
-
-    \begin{macrodesc}{kwindex}{\p{keyword}}
-      Add a reference to a language keyword (not a keyword parameter
-      in a function or method call).
-    \end{macrodesc}
-
-    \begin{macrodesc}{obindex}{\p{object type}}
-      Add an index entry for a built-in object type.
-    \end{macrodesc}
-
-    \begin{macrodesc}{opindex}{\p{operator}}
-      Add a reference to an operator, such as \samp{+}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{refmodindex}{\op{key}\p{module}}
-      Add an index entry for module \var{module}; if \var{module}
-      contains an underscore, the optional parameter \var{key} should
-      be provided as the same string with underscores removed.  An
-      index entry ``\var{module} (module)'' will be generated.  This
-      is intended for use with non-standard modules implemented in
-      Python.
-    \end{macrodesc}
-
-    \begin{macrodesc}{refexmodindex}{\op{key}\p{module}}
-      As for \macro{refmodindex}, but the index entry will be
-      ``\var{module} (extension module).''  This is intended for use
-      with non-standard modules not implemented in Python.
-    \end{macrodesc}
-
-    \begin{macrodesc}{refbimodindex}{\op{key}\p{module}}
-      As for \macro{refmodindex}, but the index entry will be
-      ``\var{module} (built-in module).''  This is intended for use
-      with standard modules not implemented in Python.
-    \end{macrodesc}
-
-    \begin{macrodesc}{refstmodindex}{\op{key}\p{module}}
-      As for \macro{refmodindex}, but the index entry will be
-      ``\var{module} (standard module).''  This is intended for use
-      with standard modules implemented in Python.
-    \end{macrodesc}
-
-    \begin{macrodesc}{stindex}{\p{statement}}
-      Add an index entry for a statement type, such as \keyword{print}
-      or \keyword{try}/\keyword{finally}.
-
-      XXX Need better examples of difference from \macro{kwindex}.
-    \end{macrodesc}
-
-
-    Additional macros are provided which are useful for conveniently
-    creating general index entries which should appear at many places
-    in the index by rotating a list of words.  These are simple macros
-    that simply use \macro{index} to build some number of index
-    entries.  Index entries build using these macros contain both
-    primary and secondary text.
-
-    \begin{macrodesc}{indexii}{\p{word1}\p{word2}}
-      Build two index entries.  This is exactly equivalent to using
-      \code{\e index\{\var{word1}!\var{word2}\}} and
-      \code{\e index\{\var{word2}!\var{word1}\}}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{indexiii}{\p{word1}\p{word2}\p{word3}}
-      Build three index entries.  This is exactly equivalent to using
-      \code{\e index\{\var{word1}!\var{word2} \var{word3}\}},
-      \code{\e index\{\var{word2}!\var{word3}, \var{word1}\}}, and
-      \code{\e index\{\var{word3}!\var{word1} \var{word2}\}}.
-    \end{macrodesc}
-
-    \begin{macrodesc}{indexiv}{\p{word1}\p{word2}\p{word3}\p{word4}}
-      Build four index entries.  This is exactly equivalent to using
-      \code{\e index\{\var{word1}!\var{word2} \var{word3} \var{word4}\}},
-      \code{\e index\{\var{word2}!\var{word3} \var{word4}, \var{word1}\}},
-      \code{\e index\{\var{word3}!\var{word4}, \var{word1} \var{word2}\}},
-      and
-      \code{\e index\{\var{word4}!\var{word1} \var{word2} \var{word3}\}}.
-    \end{macrodesc}
-
-  \subsection{Grammar Production Displays \label{grammar-displays}}
-
-    Special markup is available for displaying the productions of a
-    formal grammar.  The markup is simple and does not attempt to
-    model all aspects of BNF (or any derived forms), but provides
-    enough to allow context-free grammars to be displayed in a way
-    that causes uses of a symbol to be rendered as hyperlinks to the
-    definition of the symbol.  There is one environment and a pair of
-    macros:
-
-    \begin{envdesc}{productionlist}{\op{language}}
-      This environment is used to enclose a group of productions.  The
-      two macros are only defined within this environment.  If a
-      document describes more than one language, the optional parameter
-      \var{language} should be used to distinguish productions between
-      languages.  The value of the parameter should be a short name
-      that can be used as part of a filename; colons or other
-      characters that can't be used in filename across platforms
-      should be included.
-    \end{envdesc}
-
-    \begin{macrodesc}{production}{\p{name}\p{definition}}
-      A production rule in the grammar.  The rule defines the symbol
-      \var{name} to be \var{definition}.  \var{name} should not
-      contain any markup, and the use of hyphens in a document which
-      supports more than one grammar is undefined.  \var{definition}
-      may contain \macro{token} macros and any additional content
-      needed to describe the grammatical model of \var{symbol}.  Only
-      one \macro{production} may be used to define a symbol ---
-      multiple definitions are not allowed.
-    \end{macrodesc}
-
-    \begin{macrodesc}{token}{\p{name}}
-      The name of a symbol defined by a \macro{production} macro, used
-      in the \var{definition} of a symbol.  Where possible, this will
-      be rendered as a hyperlink to the definition of the symbol
-      \var{name}.
-    \end{macrodesc}
-
-    Note that the entire grammar does not need to be defined in a
-    single \env{productionlist} environment; any number of
-    groupings may be used to describe the grammar.  Every use of the
-    \macro{token} must correspond to a \macro{production}.
-
-    The following is an example taken from the
-    \citetitle[../ref/identifiers.html]{Python Reference Manual}:
-
-\begin{verbatim}
-\begin{productionlist}
-  \production{identifier}
-             {(\token{letter}|"_") (\token{letter} | \token{digit} | "_")*}
-  \production{letter}
-             {\token{lowercase} | \token{uppercase}}
-  \production{lowercase}
-             {"a"..."z"}
-  \production{uppercase}
-             {"A"..."Z"}
-  \production{digit}
-             {"0"..."9"}
-\end{productionlist}
-\end{verbatim}
-
-
-\subsection{Graphical Interface Components \label{gui-markup}}
-
-  The components of graphical interfaces will be assigned markup, but
-  most of the specifics have not been determined.
-
-  \begin{macrodesc}{guilabel}{\p{label}}
-    Labels presented as part of an interactive user interface should
-    be marked using \macro{guilabel}.  This includes labels from
-    text-based interfaces such as those created using \code{curses} or
-    other text-based libraries.  Any label used in the interface
-    should be marked with this macro, including button labels, window
-    titles, field names, menu and menu selection names, and even
-    values in selection lists.
-  \end{macrodesc}
-
-  \begin{macrodesc}{menuselection}{\p{menupath}}
-    Menu selections should be marked using a combination of
-    \macro{menuselection} and \macro{sub}.  This macro is used to mark
-    a complete sequence of menu selections, including selecting
-    submenus and choosing a specific operation, or any subsequence of
-    such a sequence.  The names of individual selections should be
-    separated by occurrences of \macro{sub}.
-
-    For example, to mark the selection ``\menuselection{Start \sub
-    Programs}'', use this markup:
-
-\begin{verbatim}
-\menuselection{Start \sub Programs}
-\end{verbatim}
-
-    When including a selection that includes some trailing indicator,
-    such as the ellipsis some operating systems use to indicate that
-    the command opens a dialog, the indicator should be omitted from
-    the selection name.
-
-    Individual selection names within the \macro{menuselection} should
-    not be marked using \macro{guilabel} since that's implied by using
-    \macro{menuselection}.
-  \end{macrodesc}
-
-  \begin{macrodesc}{sub}{}
-    Separator for menu selections that include multiple levels.  This
-    macro is only defined within the context of the
-    \macro{menuselection} macro.
-  \end{macrodesc}
-
-
-\section{Processing Tools \label{tools}}
-
-  \subsection{External Tools \label{tools-external}}
-
-    Many tools are needed to be able to process the Python
-    documentation if all supported formats are required.  This
-    section lists the tools used and when each is required.  Consult
-    the \file{Doc/README} file to see if there are specific version
-    requirements for any of these.
-
-    \begin{description}
-      \item[\program{dvips}]
-        This program is a typical part of \TeX{} installations.  It is
-        used to generate PostScript from the ``device independent''
-        \file{.dvi} files.  It is needed for the conversion to
-        PostScript.
-
-      \item[\program{emacs}]
-        Emacs is the kitchen sink of programmers' editors, and a damn
-        fine kitchen sink it is.  It also comes with some of the
-        processing needed to support the proper menu structures for
-        Texinfo documents when an info conversion is desired.  This is
-        needed for the info conversion.  Using \program{xemacs}
-        instead of FSF \program{emacs} may lead to instability in the
-        conversion, but that's because nobody seems to maintain the
-        Emacs Texinfo code in a portable manner.
-
-      \item[\program{latex}]
-        \LaTeX{} is a large and extensible macro package by Leslie
-        Lamport, based on \TeX, a world-class typesetter by Donald
-        Knuth.  It is used for the conversion to PostScript, and is
-        needed for the HTML conversion as well (\LaTeX2HTML requires
-        one of the intermediate files it creates).
-
-      \item[\program{latex2html}]
-        Probably the longest Perl script anyone ever attempted to
-        maintain.  This converts \LaTeX{} documents to HTML documents,
-        and does a pretty reasonable job.  It is required for the
-        conversions to HTML and GNU info.
-
-      \item[\program{lynx}]
-        This is a text-mode Web browser which includes an
-        HTML-to-plain text conversion.  This is used to convert
-        \code{howto} documents to text.
-
-      \item[\program{make}]
-        Just about any version should work for the standard documents,
-        but GNU \program{make} is required for the experimental
-        processes in \file{Doc/tools/sgmlconv/}, at least while
-        they're experimental.  This is not required for running the
-        \program{mkhowto} script.
-
-      \item[\program{makeindex}]
-        This is a standard program for converting \LaTeX{} index data
-        to a formatted index; it should be included with all \LaTeX{}
-        installations.  It is needed for the PDF and PostScript
-        conversions.
-
-      \item[\program{makeinfo}]
-        GNU \program{makeinfo} is used to convert Texinfo documents to
-        GNU info files.  Since Texinfo is used as an intermediate
-        format in the info conversion, this program is needed in that
-        conversion.
-
-      \item[\program{pdflatex}]
-        pdf\TeX{} is a relatively new variant of \TeX, and is used to
-        generate the PDF version of the manuals.  It is typically
-        installed as part of most of the large \TeX{} distributions.
-        \program{pdflatex} is pdf\TeX{} using the \LaTeX{} format.
-
-      \item[\program{perl}]
-        Perl is required for \LaTeX2HTML{} and one of the scripts used
-        to post-process \LaTeX2HTML output, as well as the
-        HTML-to-Texinfo conversion.  This is required for
-        the HTML and GNU info conversions.
-
-      \item[\program{python}]
-        Python is used for many of the scripts in the
-        \file{Doc/tools/} directory; it is required for all
-        conversions.  This shouldn't be a problem if you're interested
-        in writing documentation for Python!
-    \end{description}
-
-
-  \subsection{Internal Tools \label{tools-internal}}
-
-    This section describes the various scripts that are used to
-    implement various stages of document processing or to orchestrate
-    entire build sequences.  Most of these tools are only useful
-    in the context of building the standard documentation, but some
-    are more general.
-
-    \begin{description}
-      \item[\program{mkhowto}]
-        This is the primary script used to format third-party
-        documents.  It contains all the logic needed to ``get it
-        right.''  The proper way to use this script is to make a
-        symbolic link to it or run it in place; the actual script file
-        must be stored as part of the documentation source tree,
-        though it may be used to format documents outside the tree.
-        Use \program{mkhowto} \longprogramopt{help} for a list of
-        command line options.
-
-        \program{mkhowto} can be used for both \code{howto} and
-        \code{manual} class documents.  It is usually a good idea to
-        always use the latest version of this tool rather than a
-        version from an older source release of Python.  It can be
-        used to generate DVI, HTML, PDF, PostScript, and plain text
-        documents.  The GNU info and iSilo formats will be supported
-        by this script in some future version.
-
-        Use the \longprogramopt{help} option on this script's command
-        line to get a summary of options for this script.
-
-        XXX  Need more here.
-    \end{description}
-
-
-  \subsection{Working on Cygwin \label{cygwin}}
-
-    Installing the required tools under Cygwin under Cygwin can be a
-    little tedious.  Most of the required packages can be installed
-    using Cygwin's graphical installer, while netpbm and \LaTeX2HTML
-    must be installed from source. 
-
-    Start with a reasonably modern version of Cygwin.  If you haven't
-    upgraded for a few years, now would be a good time.
-
-    Using the Cygwin installer, make sure your Cygwin installation
-    includes Perl, Python, and the \TeX{} packages.  Perl and Python
-    are located under the \menuselection{Interpreters} heading.  The
-    \TeX{} packages are located under the \menuselection{Text}
-    heading, and are named \code{tetex-*}.  To ensure that all
-    required packages are available, install every \code{tetex}
-    package, except \code{tetex-x11}.  (There may be a more minimal
-    set, but I've not spent time trying to minimize the installation.) 
-
-    The netpbm package is used by \LaTeX2HTML, and \emph{must} be
-    installed before \LaTeX2HTML can be successfully installed, even
-    though its features will not be used for most Python
-    documentation.  References to download locations are located in
-    the \ulink{netpbm README}{http://netpbm.sourceforge.net/README}.
-    Install from the latest stable source distribution according to
-    the instructions.  (Note that binary packages of netpbm are
-    sometimes available, but these may not work correctly with
-    \LaTeX2HTML.)
-
-    \LaTeX2HTML can be installed from the source archive, but only
-    after munging one of the files in the distribution.  Download the
-    source archive from the \LaTeX2HTML website
-    \url{http://www.latex2html.org/} (or one of the many alternate
-    sites) and unpack it to a build directory. In the top level of
-    this build directory there will be a file named \file{L2hos.pm}.
-    Open \file{L2hos.pm} in an editor, and near the bottom of the file
-    replace the text \code{\$\textasciicircum{}O} with the text
-    \code{'unix'}.  Proceed using this command to build and install
-    the software:
-
-\begin{verbatim}
-% ./configure && make install
-\end{verbatim}
-
-    You should now be able to build at least the DVI, HTML, PDF, and
-    PostScript versions of the formatted documentation.
-
-
-\section{Including Graphics \label{graphics}}
-
-  The standard documentation included with Python makes no use of
-  diagrams or images; this is intentional.  The outside tools used to
-  format the documentation have not always been suited to working with
-  graphics.  As the tools have evolved and been improved by their
-  maintainers, support for graphics has improved.
-
-  The internal tools, starting with the \program{mkhowto} script, do
-  not provide any direct support for graphics.  However,
-  \program{mkhowto} will not interfere with graphics support in the
-  external tools.
-
-  Experience using graphics together with these tools and the
-  \code{howto} and \code{manual} document classes is not extensive,
-  but has been known to work.  The basic approach is this:
-
-  \begin{enumerate}
-    \item Create the image or graphic using your favorite
-          application.
-
-    \item Convert the image to a format supported by the conversion to
-          your desired output format.  If you want to generate HTML or
-          PostScript, you can convert the image or graphic to
-          encapsulated PostScript (a \file{.eps} file); \LaTeX2HTML
-          can convert that to a \file{.gif} file; it may be possible
-          to provide a \file{.gif} file directly.  If you want to
-          generate PDF, you need to provide an ``encapsulated'' PDF
-          file.  This can be generated from encapsulated PostScript
-          using the \program{epstopdf} tool provided with the te\TeX{}
-          distribution on Linux and \UNIX.
-
-    \item In your document, add this line to ``import'' the general
-          graphics support package \code{graphicx}:
-
-\begin{verbatim}
-\usepackage{graphicx}
-\end{verbatim}
-
-    \item Where you want to include your graphic or image, include
-          markup similar to this:
-
-\begin{verbatim}
-\begin{figure}
-  \centering
-  \includegraphics[width=5in]{myimage}
-  \caption{Description of my image}
-\end{figure}
-\end{verbatim}
-
-          In particular, note for the \macro{includegraphics} macro
-          that no file extension is provided.  If you're only
-          interested in one target format, you can include the
-          extension of the appropriate input file, but to allow
-          support for multiple formats, omitting the extension makes
-          life easier.
-
-    \item Run \program{mkhowto} normally.
-  \end{enumerate}
-
-  If you're working on systems which support some sort of
-  \program{make} facility, you can use that to ensure the intermediate
-  graphic formats are kept up to date.  This example shows a
-  \file{Makefile} used to format a document containing a diagram
-  created using the \program{dia} application:
-
-\begin{verbatim}
-default: pdf
-all:     html pdf ps
-
-html:   mydoc/mydoc.html
-pdf:    mydoc.pdf
-ps:     mydoc.ps
-
-mydoc/mydoc.html:  mydoc.tex mygraphic.eps
-        mkhowto --html $<
-
-mydoc.pdf:  mydoc.tex mygraphic.pdf
-        mkhowto --pdf $<
-
-mydoc.ps:   mydoc.tex mygraphic.eps
-        mkhowto --postscript $<
-
-.SUFFIXES: .dia .eps .pdf
-
-.dia.eps:
-        dia --nosplash --export $@ $<
-
-.eps.pdf:
-        epstopdf $<
-\end{verbatim} % $ <-- bow to font-lock
-
-
-\section{Future Directions \label{futures}}
-
-  The history of the Python documentation is full of changes, most of
-  which have been fairly small and evolutionary.  There has been a
-  great deal of discussion about making large changes in the markup
-  languages and tools used to process the documentation.  This section
-  deals with the nature of the changes and what appears to be the most
-  likely path of future development.
-
-  \subsection{Structured Documentation \label{structured}}
-
-    Most of the small changes to the \LaTeX{} markup have been made
-    with an eye to divorcing the markup from the presentation, making
-    both a bit more maintainable.  Over the course of 1998, a large
-    number of changes were made with exactly this in mind; previously,
-    changes had been made but in a less systematic manner and with
-    more concern for not needing to update the existing content.  The
-    result has been a highly structured and semantically loaded markup
-    language implemented in \LaTeX.  With almost no basic \TeX{} or
-    \LaTeX{} markup in use, however, the markup syntax is about the
-    only evidence of \LaTeX{} in the actual document sources.
-
-    One side effect of this is that while we've been able to use
-    standard ``engines'' for manipulating the documents, such as
-    \LaTeX{} and \LaTeX2HTML, most of the actual transformations have
-    been created specifically for Python.  The \LaTeX{} document
-    classes and \LaTeX2HTML support are both complete implementations
-    of the specific markup designed for these documents.
-
-    Combining highly customized markup with the somewhat esoteric
-    systems used to process the documents leads us to ask some
-    questions:  Can we do this more easily?  and, Can we do this
-    better?  After a great deal of discussion with the community, we
-    have determined that actively pursuing modern structured
-    documentation systems is worth some investment of time.
-
-    There appear to be two real contenders in this arena: the Standard
-    General Markup Language (SGML), and the Extensible Markup Language
-    (XML).  Both of these standards have advantages and disadvantages,
-    and many advantages are shared.
-
-    SGML offers advantages which may appeal most to authors,
-    especially those using ordinary text editors.  There are also
-    additional abilities to define content models.  A number of
-    high-quality tools with demonstrated maturity are available, but
-    most are not free; for those which are, portability issues remain
-    a problem.
-
-    The advantages of XML include the availability of a large number
-    of evolving tools.  Unfortunately, many of the associated
-    standards are still evolving, and the tools will have to follow
-    along.  This means that developing a robust tool set that uses
-    more than the basic XML 1.0 recommendation is not possible in the
-    short term.  The promised availability of a wide variety of
-    high-quality tools which support some of the most important
-    related standards is not immediate.  Many tools are likely to be
-    free, and the portability issues of those which are, are not
-    expected to be significant.
-
-    It turns out that converting to an XML or SGML system holds
-    promise for translators as well; how much can be done to ease the
-    burden on translators remains to be seen, and may have some impact
-    on the schema and specific technologies used.
-
-    XXX Eventual migration to XML.
-
-    The documentation will be moved to XML in the future, and tools
-    are being written which will convert the documentation from the
-    current format to something close to a finished version, to the
-    extent that the desired information is already present in the
-    documentation.  Some XSLT stylesheets have been started for
-    presenting a preliminary XML version as HTML, but the results are
-    fairly rough.
-
-    The timeframe for the conversion is not clear since there doesn't
-    seem to be much time available to work on this, but the apparent
-    benefits are growing more substantial at a moderately rapid pace.
-
-
-  \subsection{Discussion Forums \label{discussion}}
-
-    Discussion of the future of the Python documentation and related
-    topics takes place in the Documentation Special Interest Group, or
-    ``Doc-SIG.''  Information on the group, including mailing list
-    archives and subscription information, is available at
-    \url{http://www.python.org/sigs/doc-sig/}.  The SIG is open to all
-    interested parties.
-
-    Comments and bug reports on the standard documents should be sent
-    to \email{docs@python.org}.  This may include comments
-    about formatting, content, grammatical and spelling errors, or
-    this document.  You can also send comments on this document
-    directly to the author at \email{fdrake@acm.org}.
-
-\input{doc.ind}
-
-\end{document}