[Notes and questions in brackets, like this, are notes to myself while

developing this document.]

This document is aimed at authors and potential authors of

documentation for Python. Among this group, it is aimed primarily

at 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

Python document classes, reference material on the markup defined in

the document classes, a list of the tools need 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.

are independent of the Python source distribution.

Most output formats have a directory which contains a

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/}.

\section{\LaTeX{} Syntax Primer \label{latex-primer}}

[This section will discuss what the markup looks like, and explain

the difference between an environment and a macro.]

The Python document classes define a lot of new environments and

macros. This section contains the reference material for these

facilities.

module's name contains any underscores, and should be the name

with the underscores stripped. This should be the first thing

after the \macro{section} used to introduce the module.

If a \file{.syn} file exists for the current

eventual conversion of the documentation to SGML (see Section

\ref{futures}, ``Future Directions'').

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.

would look up is fairly difficult for an author who, typically, is

The truly difficult aspects of index generation are not areas with

which the documentation tools can help. However, ease

Add a index entry referring to a built-in function named

\var{name}; parenthesis should not be included after

\var{name}.

Add a reference to an exception named \var{exception}. The

exception may be either string- or class-based.

Add a reference to a language keyword (not a keyword parameter

in a function or method call).

Add an index entry for a built-in object type.

Add a reference to an operator, such as \samp{+}.

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}.

\file{.dvi} files. It is needed for the conversion to

needed for the info conversion. Using \program{xemacs}

HTML-to-Texinfo conversion. This is required for

entire build sequences. Most of these tools are only useful

documentation systems is worth some investment of time.

about formatting, content, grammatical errors, or this document.