add hg and python

1 files changed, 2129 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/doc/doc.tex b/sys/src/cmd/python/Doc/doc/doc.tex
new file mode 100644
index 000000000..1d0f279f3
--- /dev/null
+++ b/sys/src/cmd/python/Doc/doc/doc.tex
@@ -0,0 +1,2129 @@
+\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}