1999-03-16 12:09:13 -04:00
|
|
|
\documentclass{howto}
|
|
|
|
\usepackage{ltxmarkup}
|
|
|
|
|
|
|
|
\title{Documenting Python}
|
|
|
|
|
|
|
|
\input{boilerplate}
|
|
|
|
|
1999-04-28 15:24:02 -03:00
|
|
|
% Now override the stuff that includes author information;
|
|
|
|
% Guido did *not* write this one!
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\author{Fred L. Drake, Jr.}
|
|
|
|
\authoraddress{
|
|
|
|
Corporation for National Research Initiatives (CNRI) \\
|
|
|
|
1895 Preston White Drive, Reston, Va 20191, USA \\
|
|
|
|
E-mail: \email{fdrake@acm.org}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
\begin{document}
|
|
|
|
|
|
|
|
\maketitle
|
|
|
|
|
|
|
|
\begin{abstract}
|
|
|
|
\noindent
|
|
|
|
The Python language documentation 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.
|
1999-06-11 11:25:45 -03:00
|
|
|
This document describes the macros introduced to support Python
|
|
|
|
documentation and how they should be used to support a wide range of
|
|
|
|
output formats.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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.
|
|
|
|
\end{abstract}
|
|
|
|
|
|
|
|
\tableofcontents
|
|
|
|
|
|
|
|
|
|
|
|
\section{Introduction}
|
|
|
|
|
|
|
|
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
|
1999-04-23 11:41:44 -03:00
|
|
|
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.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
1999-03-29 10:55:55 -04:00
|
|
|
This document is aimed at authors and potential authors of
|
1999-04-23 11:41:44 -03:00
|
|
|
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.
|
1999-03-29 10:55:55 -04:00
|
|
|
|
|
|
|
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
|
1999-04-23 11:41:44 -03:00
|
|
|
document types, reference material on the markup defined in the
|
|
|
|
document classes, a list of the external tools needed for processing
|
1999-03-29 10:55:55 -04:00
|
|
|
documents, and reference material on the tools provided with the
|
|
|
|
documentation resources. At the end, there is also a section
|
1999-04-23 11:41:44 -03:00
|
|
|
discussing future directions for the Python documentation and where
|
|
|
|
to turn for more information.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\section{Directory Structure}
|
|
|
|
|
|
|
|
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
|
1999-04-23 11:41:44 -03:00
|
|
|
source distribution as the top-level directory \file{Doc/}, but
|
|
|
|
are not dependent on the Python source distribution in any way.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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,
|
1999-04-28 13:43:11 -03:00
|
|
|
three-character names:
|
|
|
|
|
|
|
|
\begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Document Title}
|
|
|
|
\lineii{api/}{\emph{The Python/C API}}
|
|
|
|
\lineii{doc/}{\emph{Documenting Python}}
|
|
|
|
\lineii{ext/}{\emph{Extending and Embedding the Python Interpreter}}
|
|
|
|
\lineii{lib/}{\emph{Python Library Reference}}
|
|
|
|
\lineii{mac/}{\emph{Macintosh Module Reference}}
|
|
|
|
\lineii{ref/}{\emph{Python Reference Manual}}
|
|
|
|
\lineii{tut/}{\emph{Python Tutorial}}
|
|
|
|
\end{tableii}
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\term{Format-Specific Output}
|
1999-03-29 10:55:55 -04:00
|
|
|
Most output formats have a directory which contains a
|
1999-03-16 12:09:13 -04:00
|
|
|
\file{Makefile} which controls the generation of that format
|
|
|
|
and provides storage for the formatted documents. The only
|
1999-03-29 10:55:55 -04:00
|
|
|
variations within this category are the Portable Document
|
|
|
|
Format (PDF) and PostScript versions are placed in the
|
1999-04-23 11:41:44 -03:00
|
|
|
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).
|
1999-03-16 12:09:13 -04:00
|
|
|
|
1999-04-28 13:43:11 -03:00
|
|
|
\begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Output Formats}
|
|
|
|
\lineii{html/}{HTML output}
|
|
|
|
\lineii{info/}{GNU info output}
|
|
|
|
\lineii{paper-a4/}{PDF and PostScript, A4 paper}
|
|
|
|
\lineii{paper-letter/}{PDF and PostScript, US-Letter paper}
|
|
|
|
\end{tableii}
|
|
|
|
|
1999-03-16 12:09:13 -04:00
|
|
|
\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.
|
1999-04-28 13:43:11 -03:00
|
|
|
|
|
|
|
\begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Contents}
|
|
|
|
\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}
|
|
|
|
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{definitions}
|
|
|
|
|
1999-03-29 10:55:55 -04:00
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\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.''
|
|
|
|
|
1999-06-11 11:25:45 -03:00
|
|
|
Perhaps the most important concept to keep in mind while marking up
|
|
|
|
Python documentation is the 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.
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\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
|
1999-04-23 11:41:44 -03:00
|
|
|
can also be placed in the preamble. For most authors, the preamble
|
1999-04-22 10:05:27 -03:00
|
|
|
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
|
1999-04-23 11:41:44 -03:00
|
|
|
section \ref{classes}, ``Document Classes,'' below. The first thing
|
1999-04-22 10:05:27 -03:00
|
|
|
in the preamble is the declaration of the document's class.
|
1999-03-29 10:55:55 -04:00
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
After the class declaration, a number of \emph{macros} are used to
|
|
|
|
provide further information about the document and setup any
|
1999-04-23 11:41:44 -03:00
|
|
|
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.
|
1999-03-29 10:55:55 -04:00
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
The document body follows the preamble. This contains all the
|
|
|
|
printed components of the document marked up structurally.
|
1999-03-29 10:55:55 -04:00
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
XXX This section will discuss what the markup looks like, and
|
|
|
|
explain the difference between an environment and a macro.
|
|
|
|
|
|
|
|
|
|
|
|
\section{Document Classes \label{classes}}
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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
|
1999-04-22 10:05:27 -03:00
|
|
|
technical report. The \emph{Python Reference Manual} is a good
|
1999-04-23 11:41:44 -03:00
|
|
|
example of a \code{manual} document, and the \emph{Python Library
|
|
|
|
Reference} is a large example.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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
|
|
|
|
more broad. 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
|
|
|
|
the standard \emph{Macintosh Library Modules} and \emph{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.
|
|
|
|
|
|
|
|
|
1999-04-23 11:41:44 -03:00
|
|
|
\section{Special Markup Constructs}
|
1999-03-16 12:09:13 -04:00
|
|
|
|
1999-03-29 10:55:55 -04:00
|
|
|
The Python document classes define a lot of new environments and
|
|
|
|
macros. This section contains the reference material for these
|
|
|
|
facilities.
|
|
|
|
|
1999-03-16 12:09:13 -04:00
|
|
|
\subsection{Information Units \label{info-units}}
|
|
|
|
|
1999-04-28 13:43:11 -03:00
|
|
|
XXX Explain terminology, or come up with something more ``lay.''
|
1999-04-22 10:05:27 -03:00
|
|
|
|
|
|
|
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}
|
1999-04-23 11:41:44 -03:00
|
|
|
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.
|
1999-04-22 10:05:27 -03:00
|
|
|
|
|
|
|
\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.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{envdesc}
|
1999-04-23 11:41:44 -03:00
|
|
|
\begin{envdesc}{datadescni}{\p{name}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like \env{datadesc}, but without creating any index entries.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{excdesc}{\p{name}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Describe an exception. This may be either a string exception or
|
|
|
|
a class exception.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\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.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{envdesc}
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{funcdescni}{\p{name}\p{parameters}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like \env{funcdesc}, but without creating any index entries.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\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.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\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.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{envdesc}
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{memberdescni}{\op{type name}\p{name}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like \env{memberdesc}, but without creating any index entries.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\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}.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{envdesc}
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{methoddescni}{\op{type name}\p{name}\p{parameters}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like \env{methoddesc}, but without creating any index entries.
|
|
|
|
\end{envdesc}
|
|
|
|
|
|
|
|
|
1999-06-11 11:25:45 -03:00
|
|
|
\subsection{Showing Code 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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
1999-03-16 12:09:13 -04:00
|
|
|
\subsection{Inline Markup}
|
|
|
|
|
1999-05-17 12:22:45 -03:00
|
|
|
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.
|
1999-04-28 13:43:11 -03:00
|
|
|
|
|
|
|
\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}{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}{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.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
\begin{macrodesc}{dfn}{\p{term}}
|
|
|
|
Mark the defining instance of \var{term} in the text. (No index
|
|
|
|
entries are generated.)
|
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-05-17 13:33:54 -03:00
|
|
|
\begin{macrodesc}{e}{}
|
|
|
|
Produces a backslash. This is convenient in \macro{code} and
|
|
|
|
similar macros.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-28 13:43:11 -03:00
|
|
|
\begin{macrodesc}{email}{\p{address}}
|
|
|
|
An email address. Note that this is \emph{not} hyperlinked in
|
|
|
|
any of the possible output formats.
|
|
|
|
\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.
|
|
|
|
\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.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
\begin{macrodesc}{function}{\p{name}}
|
|
|
|
The name of a Python function; dotted names may be used.
|
|
|
|
\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. For example, an \program{xemacs} key sequence
|
|
|
|
may be marked like \code{\e kbd\{C-x C-f\}}.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
\begin{macrodesc}{keyword}{\p{name}}
|
|
|
|
The name of a keyword in a programming language.
|
|
|
|
\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.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
\begin{macrodesc}{module}{\p{name}}
|
|
|
|
The name of a module; a dotted name may be used.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
\begin{macrodesc}{newsgroup}{\p{name}}
|
|
|
|
The name of a USENET newsgroup.
|
|
|
|
\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 DOS
|
|
|
|
and Windows programs.
|
|
|
|
\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}{strong}{\p{text}}
|
|
|
|
Strongly emphasized text; this will be presented using a bold
|
|
|
|
font.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-05-17 13:33:54 -03:00
|
|
|
\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. 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}
|
|
|
|
|
1999-04-28 13:43:11 -03:00
|
|
|
\begin{macrodesc}{var}{\p{name}}
|
|
|
|
The name of a variable or formal parameter in running text.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
\begin{macrodesc}{version}{}
|
|
|
|
The version number for the documentation, as specified using
|
|
|
|
\macro{release} in the preamble.
|
|
|
|
\end{macrodesc}
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
|
|
|
|
\subsection{Module-specific Markup}
|
|
|
|
|
|
|
|
The markup described in this section is used to provide information
|
|
|
|
about a module being documented. A typical use of this markup
|
|
|
|
appears at the top of the section used to document a module. A
|
|
|
|
typical example might look like this:
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
\section{\module{spam} ---
|
|
|
|
Access to the SPAM facility}
|
|
|
|
|
|
|
|
\declaremodule{extension}{spam}
|
1999-03-29 10:55:55 -04:00
|
|
|
\platform{Unix}
|
1999-04-22 10:05:27 -03:00
|
|
|
\modulesynopsis{Access to the SPAM facility of \UNIX{}.}
|
1999-03-29 10:55:55 -04:00
|
|
|
\moduleauthor{Jane Doe}{jane.doe@frobnitz.org}
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{verbatim}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{declaremodule}{\op{key}\p{type}\p{name}}
|
1999-05-17 12:22:45 -03:00
|
|
|
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.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{platform}{\p{specifier}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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
|
1999-04-23 11:41:44 -03:00
|
|
|
which has already been used when applicable. This is used to
|
|
|
|
provide annotations in the Module Index and the HTML and GNU info
|
|
|
|
output.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{modulesynopsis}{\p{text}}
|
1999-03-16 12:09:13 -04:00
|
|
|
The \var{text} is a short, ``one line'' description of the
|
|
|
|
module that can be used as part of the chapter introduction.
|
1999-04-22 10:05:27 -03:00
|
|
|
This is must be placed after \macro{declaremodule}.
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{moduleauthor}{\p{name}\p{email}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
|
|
|
This markup is used when describing a selection of modules. For
|
|
|
|
example, the \emph{Macintosh Library Modules} document uses this
|
|
|
|
to help provide an overview of the modules in the collection, and
|
|
|
|
many chapters in the \emph{Python Library Reference} use it for
|
|
|
|
the same purpose.
|
|
|
|
|
|
|
|
\begin{macrodesc}{localmoduletable}{}
|
1999-03-29 10:55:55 -04:00
|
|
|
If a \file{.syn} file exists for the current
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
|
|
|
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
|
1999-04-23 11:41:44 -03:00
|
|
|
eventual conversion of the documentation to SGML (see section
|
1999-03-29 10:55:55 -04:00
|
|
|
\ref{futures}, ``Future Directions'').
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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
|
1999-03-29 10:55:55 -04:00
|
|
|
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.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{tableii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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
|
1999-04-22 10:05:27 -03:00
|
|
|
column specially, \var{col1font} may be \samp{textrm}. The
|
1999-03-16 12:09:13 -04:00
|
|
|
column headings are taken from the values \var{heading1} and
|
|
|
|
\var{heading2}.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{lineii}{\p{column1}\p{column2}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Create a single table row within a \env{tableii} 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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{tableiii}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like the \env{tableii} environment, but with a third column.
|
|
|
|
The heading for the third column is given by \var{heading3}.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{lineiii}{\p{column1}\p{column2}\p{column3}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like the \macro{lineii} macro, but with a third column. The
|
|
|
|
text for the third column is given by \var{column3}.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{envdesc}{tableiv}{\p{colspec}\p{col1font}\p{heading1}\p{heading2}\p{heading3}\p{heading4}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like the \env{tableiii} environment, but with a fourth column.
|
|
|
|
The heading for the fourth column is given by \var{heading4}.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{lineiv}{\p{column1}\p{column2}\p{column3}\p{column4}}
|
1999-03-16 12:09:13 -04:00
|
|
|
Like the \macro{lineiii} macro, but with a fourth column. The
|
|
|
|
text for the fourth column is given by \var{column4}.
|
|
|
|
\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 use by
|
|
|
|
the user, but is created by the \macro{localmoduletable} macro.
|
|
|
|
|
|
|
|
|
|
|
|
\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} environment. This environment defines some
|
|
|
|
additional macros to support creating reference entries in a
|
|
|
|
reasonable manner.
|
|
|
|
|
|
|
|
\begin{envdesc}{seealso}{}
|
|
|
|
This environment creates a ``See also:'' heading and defines the
|
|
|
|
markup used to describe individual references.
|
|
|
|
\end{envdesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{seemodule}{\op{key}\p{name}\p{why}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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.
|
1999-04-22 10:05:27 -03:00
|
|
|
\strong{Note:} The module must be documented in the same
|
|
|
|
document (the corresponding \macro{declaremodule} is required).
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{seetext}{\p{text}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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.
|
|
|
|
\end{macrodesc}
|
|
|
|
|
|
|
|
|
|
|
|
\subsection{Index-generating Markup \label{indexing}}
|
|
|
|
|
|
|
|
Effective index generation for technical documents can be very
|
|
|
|
difficult, especially for someone familliar 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
|
1999-03-29 10:55:55 -04:00
|
|
|
would look up is fairly difficult for an author who, typically, is
|
1999-03-16 12:09:13 -04:00
|
|
|
an expert in the area she is writing on.
|
|
|
|
|
1999-03-29 10:55:55 -04:00
|
|
|
The truly difficult aspects of index generation are not areas with
|
|
|
|
which the documentation tools can help. However, ease
|
1999-03-16 12:09:13 -04:00
|
|
|
of producing the index once content decisions are make 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
|
1999-04-23 11:41:44 -03:00
|
|
|
described in section \ref{info-units}, ``Information Units,'' will
|
1999-03-16 12:09:13 -04:00
|
|
|
generate appropriate entries into the general and module indexes.
|
|
|
|
|
|
|
|
The following macro can be used to control the generation of index
|
1999-04-22 10:05:27 -03:00
|
|
|
data, and should be used in the document preamble:
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\begin{macrodesc}{makemodindex}{}
|
1999-04-22 10:05:27 -03:00
|
|
|
This should be used in the document preamble if a ``Module
|
1999-03-16 12:09:13 -04:00
|
|
|
Index'' is desired for a document containing reference material
|
|
|
|
on many modules. This causes a data file
|
1999-05-17 13:33:54 -03:00
|
|
|
\code{lib\var{jobname}.idx} to be created from the
|
1999-03-16 12:09:13 -04:00
|
|
|
\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.
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{bifuncindex}{\p{name}}
|
1999-04-23 17:01:17 -03:00
|
|
|
Add an index entry referring to a built-in function named
|
|
|
|
\var{name}; parentheses should not be included after
|
1999-03-29 10:55:55 -04:00
|
|
|
\var{name}.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{exindex}{\p{exception}}
|
1999-03-29 10:55:55 -04:00
|
|
|
Add a reference to an exception named \var{exception}. The
|
|
|
|
exception may be either string- or class-based.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{kwindex}{\p{keyword}}
|
1999-03-29 10:55:55 -04:00
|
|
|
Add a reference to a language keyword (not a keyword parameter
|
|
|
|
in a function or method call).
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{obindex}{\p{object type}}
|
1999-03-29 10:55:55 -04:00
|
|
|
Add an index entry for a built-in object type.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{opindex}{\p{operator}}
|
1999-03-29 10:55:55 -04:00
|
|
|
Add a reference to an operator, such as \samp{+}.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{macrodesc}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{refmodindex}{\op{key}\p{module}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{refexmodindex}{\op{key}\p{module}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{refbimodindex}{\op{key}\p{module}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{refstmodindex}{\op{key}\p{module}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{stindex}{\p{statement}}
|
1999-03-29 10:55:55 -04:00
|
|
|
Add an index entry for a statement type, such as \keyword{print}
|
1999-04-22 10:05:27 -03:00
|
|
|
or \keyword{try}/\keyword{finally}.
|
|
|
|
|
|
|
|
XXX Need better examples of difference from \macro{kwindex}.
|
1999-03-16 12:09:13 -04:00
|
|
|
\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.
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{indexii}{\p{word1}\p{word2}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{indexiii}{\p{word1}\p{word2}\p{word3}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
\begin{macrodesc}{indexiv}{\p{word1}\p{word2}\p{word3}\p{word4}}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
|
|
|
|
|
|
|
\section{Special Names}
|
|
|
|
|
|
|
|
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, 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.
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
\item[POSIX]
|
|
|
|
The name assigned to a particular group of standards. This is
|
|
|
|
always uppercase.
|
|
|
|
|
|
|
|
\item[Python]
|
|
|
|
The name of our favorite programming language is always
|
|
|
|
capitalized.
|
|
|
|
\end{description}
|
|
|
|
|
|
|
|
|
|
|
|
\section{Processing Tools}
|
|
|
|
|
|
|
|
\subsection{External Tools}
|
|
|
|
|
|
|
|
Many tools are needed to be able to process the Python
|
|
|
|
documentation if all supported formats are required. This
|
1999-04-22 10:05:27 -03:00
|
|
|
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.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
\item[\program{dvips}]
|
|
|
|
This program is a typical part of \TeX{} installations. It is
|
|
|
|
used to generate PostScript from the ``device independent''
|
1999-03-29 10:55:55 -04:00
|
|
|
\file{.dvi} files. It is needed for the conversion to
|
1999-03-16 12:09:13 -04:00
|
|
|
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
|
1999-03-29 10:55:55 -04:00
|
|
|
needed for the info conversion. Using \program{xemacs}
|
1999-03-16 12:09:13 -04:00
|
|
|
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}]
|
|
|
|
This is 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.
|
|
|
|
|
|
|
|
\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.
|
1999-04-23 11:41:44 -03:00
|
|
|
\program{pdflatex} is pdf\TeX{} using the \LaTeX{} format.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\item[\program{perl}]
|
|
|
|
Perl is required for \LaTeX2HTML{} and one of the scripts used
|
|
|
|
to post-process \LaTeX2HTML output, as well as the
|
1999-03-29 10:55:55 -04:00
|
|
|
HTML-to-Texinfo conversion. This is required for
|
1999-03-16 12:09:13 -04:00
|
|
|
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}
|
|
|
|
|
|
|
|
This section describes the various scripts that are used to
|
|
|
|
implement various stages of document processing or to orchestrate
|
1999-03-29 10:55:55 -04:00
|
|
|
entire build sequences. Most of these tools are only useful
|
1999-03-16 12:09:13 -04:00
|
|
|
in the context of building the standard documentation, but some
|
|
|
|
are more general.
|
|
|
|
|
|
|
|
\begin{description}
|
|
|
|
\item[\program{mkhowto}]
|
1999-05-17 12:22:45 -03:00
|
|
|
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
|
1999-11-09 14:03:00 -04:00
|
|
|
tree. Use \program{mkhowto} \programopt{-}\programopt{-help}
|
|
|
|
for a list of
|
1999-05-27 18:45:54 -03:00
|
|
|
command line options.
|
1999-05-17 12:22:45 -03:00
|
|
|
|
1999-05-17 13:33:54 -03:00
|
|
|
\program{mkhowto} can be used for both \code{howto} and
|
|
|
|
\code{manual} class documents. (For the later, be sure to get
|
|
|
|
the latest version from the Python CVS repository rather than
|
|
|
|
the version distributed in the \file{latex-1.5.2.tgz} source
|
|
|
|
archive.)
|
|
|
|
|
1999-05-17 12:22:45 -03:00
|
|
|
XXX Need more here.
|
1999-03-16 12:09:13 -04:00
|
|
|
\end{description}
|
|
|
|
|
|
|
|
|
|
|
|
\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
|
1999-04-23 11:41:44 -03:00
|
|
|
been created specifically for Python. The \LaTeX{} document
|
|
|
|
classes and \LaTeX2HTML support are both complete implementations
|
|
|
|
of the specific markup designed for these documents.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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
|
1999-03-29 10:55:55 -04:00
|
|
|
documentation systems is worth some investment of time.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
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 is 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.
|
|
|
|
|
1999-04-22 10:05:27 -03:00
|
|
|
XXX Eventual migration to SGML/XML.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\subsection{Discussion Forums \label{discussion}}
|
|
|
|
|
|
|
|
Discussion of the future of the Python documentation and related
|
1999-04-23 11:41:44 -03:00
|
|
|
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
|
1999-03-16 12:09:13 -04:00
|
|
|
\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{python-docs@python.org}. This may include comments
|
1999-04-22 10:05:27 -03:00
|
|
|
about formatting, content, grammatical and spelling errors, or
|
1999-05-17 13:33:54 -03:00
|
|
|
this document. You can also send comments on this document
|
|
|
|
directly to the author at \email{fdrake@acm.org}.
|
1999-03-16 12:09:13 -04:00
|
|
|
|
|
|
|
\end{document}
|