diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/doc/doc.tex | 644 |
1 files changed, 644 insertions, 0 deletions
diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex new file mode 100644 index 0000000..a2d0336 --- /dev/null +++ b/Doc/doc/doc.tex @@ -0,0 +1,644 @@ +\documentclass{howto} +\usepackage{ltxmarkup} + +\title{Documenting Python} + +\input{boilerplate} + +% Now override the stuff that includes author information: + +\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} +} +\date{\today} + + +\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. +Maintaining the documentation requires substantial effort, in part +because selecting the correct markup to use is not always easy. + +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 + 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. + + [Who is this document for?] + + [What does it cover?] + +\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 + source distribution as the top-level subdirectory \file{Doc/}, but + is independent of the Python source distribution. + + 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, + three-character names. + + \term{Format-Specific Output} + Most output formats have a directory provided which contains a + \file{Makefile} which controls the generation of that format + and provides storage for the formatted documents. The only + variation within this category is the Portable Document Format + (PDF) and PostScript versions are placed in the directories + \file{paper-a4/} and \file{paper-letter/}. + + \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. + \end{definitions} + +\section{Document 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 \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. + + +\section{Python-specific Markup} + + \subsection{Information Units \label{info-units}} + + Most of the environments should be described here: \env{excdesc}, + \env{funcdesc}, etc. + + \begin{envdesc}{datadesc}{\{\var{name}\}} + \end{envdesc} + \begin{envdesc}{datadesc}{\{\var{name}\}} + Like \env{datadesc}, but without creating any index entries. + \end{envdesc} + + \begin{envdesc}{excdesc}{\{\var{name}\}} + Describe an exception. This may be either a string exception or + a class exception. + \end{envdesc} + + \begin{envdesc}{funcdesc}{\{\var{name}\}\{\var{parameter list}\}} + \end{envdesc} + \begin{envdesc}{funcdescni}{\{\var{name}\}\{\var{parameter list}\}} + Like \env{funcdesc}, but without creating any index entries. + \end{envdesc} + + \begin{envdesc}{classdesc}{\{\var{name}\}\{\var{constructor parameter list}\}} + \end{envdesc} + + \begin{envdesc}{memberdesc}{\{\var{name}\}} + \end{envdesc} + \begin{envdesc}{memberdescni}{\{\var{name}\}} + Like \env{memberdesc}, but without creating any index entries. + \end{envdesc} + + \begin{envdesc}{methoddesc}{{[}\var{class name}{]}\{\var{name}\}\{\var{parameter list}\}} + \end{envdesc} + \begin{envdesc}{methoddescni}{{[}\var{class name}{]}\{\var{name}\}\{\var{parameter list}\}} + Like \env{methoddesc}, but without creating any index entries. + \end{envdesc} + + + \subsection{Inline Markup} + + This is where to explain \macro{code}, \macro{function}, + \macro{email}, etc. + + + \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} + \platform{SomeOS} +\modulesynopsis{Access to the SPAM facility of SomeOS.} +\moduleauthor{John Doe}{john.doe@frobnication.org} +\end{verbatim} + + \begin{macrodesc}{declaremodule}{{[}\var{key}{]}\{\var{type}\}\{\var{name}\}} + Requires two parameters: module type (standard, builtin, + extension), 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 underscores, and should be the name with the + underscore's stripped. This should be the first thing after the + \macro{section} used to introduce the module. + \end{macrodesc} + + \begin{macrodesc}{platform}{\{\var{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. + \end{macrodesc} + + \begin{macrodesc}{modulesynopsis}{\{\var{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 typically placed just 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}{\{\var{name}\}\{\var{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} + + 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}{} + No parameters. 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} + + 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 SGML; 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 environments are all built on top of the + \env{tabular} environment. + + \begin{envdesc}{tableii}{\{\var{colspec}\}\{\var{col1font}\}\{\var{heading1}\}\{\var{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 \code{textrm}. The + column headings are taken from the values \var{heading1} and + \var{heading2}. + \end{envdesc} + + \begin{macrodesc}{lineii}{\{\var{column1}\}\{\var{column2}\}} + 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} + + \begin{envdesc}{tableiii}{\{\var{colspec}\}\{\var{col1font}\}\{\var{heading1}\}\{\var{heading2}\}\{\var{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{macrodesc}{lineiii}{\{\var{column1}\}\{\var{column2}\}\{\var{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}{\{\var{colspec}\}\{\var{col1font}\}\{\var{heading1}\}\{\var{heading2}\}\{\var{heading3}\}\{\var{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{macrodesc}{lineiv}{\{\var{column1}\}\{\var{column2}\}\{\var{column3}\}\{\var{column4}\}} + 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} + + \begin{macrodesc}{seemodule}{{[}\var{key}{]}\{\var{name}\}\{\var{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. + \end{macrodesc} + + \begin{macrodesc}{seetext}{\{\var{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. + \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 + would look up is fairly difficult for an author who, hopefully, is + an expert in the area she is writing on. + + The truly difficult aspects of index generation are not something + which the documentation tools can help with, unfortunately. Ease + 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 + 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 prologue: + + \begin{macrodesc}{makemodindex}{} + This should be used in the document prologue if a ``Module + Index'' is desired for a document containing reference material + on many modules. This causes a data file + \code{lib\macro{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}{\{\var{name}\}} + \end{macrodesc} + + \begin{macrodesc}{exindex}{\{\var{exception}\}} + \end{macrodesc} + + \begin{macrodesc}{kwindex}{\{\var{keyword}\}} + \end{macrodesc} + + \begin{macrodesc}{obindex}{\{\var{object type}\}} + \end{macrodesc} + + \begin{macrodesc}{opindex}{\{\var{operator}\}} + \end{macrodesc} + + \begin{macrodesc}{refmodindex}{{[}\var{key}{]}\{\var{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}{{[}\var{key}{]}\{\var{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}{{[}\var{key}{]}\{\var{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}{{[}\var{key}{]}\{\var{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}{\{\var{statement}\}} + \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}{\{\var{word1}\}\{\var{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}{\{\var{word1}\}\{\var{word2}\}\{\var{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}{\{\var{word1}\}\{\var{word2}\}\{\var{word3}\}\{\var{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} + + +\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 + section lists the tools used and when each is required. + + \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 only 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 + only 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}] + 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. + \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 only 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} + + 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 still only useful + in the context of building the standard documentation, but some + are more general. + + \begin{description} + \item[\program{mkhowto}] + \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 + 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. + + 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 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 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. + + [Eventual migration to SGML/XML.] + + \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 + \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 + about formatting, content, or grammatical errors. + +\end{document} |