Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

General small improvements and fixes.

This commit is contained in:
Fred Drake 1999-04-23 14:41:44 +00:00
parent 9dd52099fa
commit 7a737dffc4
1 changed files with 47 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
Doc/doc/doc.tex
View File

@ -48,27 +48,28 @@ distribution, to create or maintain whole documents or sections.
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 aspects of the
documentation could be 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.
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. 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.
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
Python document classes, reference material on the markup defined in
the document classes, a list of the tools need for processing
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.
discussing future directions for the Python documentation and where
to turn for more information.
\section{Directory Structure}
@ -81,8 +82,8 @@ distribution, to create or maintain whole documents or sections.
structure.
The documentation sources are usually placed within the Python
source distribution as the top-level subdirectory \file{Doc/}, but
are independent of the Python source distribution.
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
@ -101,7 +102,10 @@ distribution, to create or maintain whole documents or sections.
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/}.
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).
\term{Supplemental Files}
Some additional directories are used to store supplemental
@ -124,7 +128,7 @@ distribution, to create or maintain whole documents or sections.
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 users, the preamble
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.
@ -134,12 +138,14 @@ distribution, to create or maintain whole documents or sections.
\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
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.
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.
@ -159,7 +165,8 @@ distribution, to create or maintain whole documents or sections.
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 \emph{Python Reference Manual} is a good
example of a \code{manual} document.
example of a \code{manual} document, and the \emph{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
@ -177,7 +184,7 @@ distribution, to create or maintain whole documents or sections.
single chapter from a larger work.
\section{Python-specific Markup}
\section{Special Markup Constructs}
The Python document classes define a lot of new environments and
macros. This section contains the reference material for these
@ -209,12 +216,12 @@ distribution, to create or maintain whole documents or sections.
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 which
deserves mention are the 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.
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}{datadesc}{\p{name}}
This environment is used to document global data in a module,
@ -222,7 +229,7 @@ distribution, to create or maintain whole documents or sections.
constants.'' Class and object attributes are not documented
using this environment.
\end{envdesc}
\begin{envdesc}{datadesc}{\p{name}}
\begin{envdesc}{datadescni}{\p{name}}
Like \env{datadesc}, but without creating any index entries.
\end{envdesc}
@ -313,7 +320,9 @@ distribution, to create or maintain whole documents or sections.
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.
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}}
@ -358,7 +367,7 @@ distribution, to create or maintain whole documents or sections.
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 SGML (see Section
eventual conversion of the documentation to SGML (see section
\ref{futures}, ``Future Directions'').
Each environment is named \env{table\var{cols}}, where \var{cols}
@ -465,7 +474,7 @@ distribution, to create or maintain whole documents or sections.
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
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
@ -663,7 +672,7 @@ distribution, to create or maintain whole documents or sections.
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.
\program{pdflatex} is pdf\TeX{} using the \LaTeX{} format.
\item[\program{perl}]
Perl is required for \LaTeX2HTML{} and one of the scripts used
@ -717,10 +726,9 @@ distribution, to create or maintain whole documents or sections.
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 this documentation. The \LaTeX{}
document classes and \LaTeX2HTML support are both complete
implementations of the specific markup designed for these
documents.
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
@ -756,9 +764,9 @@ distribution, to create or maintain whole documents or sections.
\subsection{Discussion Forums \label{discussion}}
Discussion of the future of the Python documentation and related
topics takes place in the ``Doc-SIG'' special interest group.
Information on the group, including mailing list archives and
subscriptions, is available at
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.