\documentclass{howto}\usepackage{ltxmarkup} \title{Documenting Python} \makeindex \input{boilerplate} % Now override the stuff that includes author information;% Guido did *not* write this one! \author{Fred L. Drake, Jr.}\authoraddress{        PythonLabs \\        Email: \email{fdrake@acm.org}}  \begin{document} \maketitle \begin{abstract}\noindentThe Python language has a substantial body ofdocumentation, much of it contributed by various authors.  The markupused for the Python documentation is based on \LaTeX{} and requires asignificant set of macros written specifically for documenting Python.This document describes the macros introduced to support Pythondocumentation and how they should be used to support a wide range ofoutput formats. This document describes the document classes and special markup usedin the Python documentation.  Authors may use this guide, inconjunction with the template files provided with thedistribution, to create or maintain whole documents or sections. If you're interested in contributing to Python's documentation,there's no need to learn \LaTeX{} if you're not so inclined; plaintext contributions are more than welcome as well.\end{abstract} \tableofcontents  \section{Introduction \label{intro}}   Python's documentation has long been considered to be good for a  free programming language.  There are a number of reasons for this,  the most important being the early commitment of Python's creator,  Guido van Rossum, to providing documentation on the language and its  libraries, and the continuing involvement of the user community in  providing assistance for creating and maintaining documentation.   The involvement of the community takes many forms, from authoring to  bug reports to just plain complaining when the documentation could  be more complete or easier to use.  All of these forms of input from  the community have proved useful during the time I've been involved  in maintaining the documentation.   This document is aimed at authors and potential authors of  documentation for Python.  More specifically, it is for people  contributing to the standard documentation and developing additional  documents using the same tools as the standard documents.  This  guide will be less useful for authors using the Python documentation  tools for topics other than Python, and less useful still for  authors not using the tools at all.   The material in this guide is intended to assist authors using the  Python documentation tools.  It includes information on the source  distribution of the standard documentation, a discussion of the  document types, reference material on the markup defined in the  document classes, a list of the external tools needed for processing  documents, and reference material on the tools provided with the  documentation resources.  At the end, there is also a section  discussing future directions for the Python documentation and where  to turn for more information.   If your interest is in contributing to the Python documentation, but  you don't have the time or inclination to learn \LaTeX{} and the  markup structures documented here, there's a welcoming place for you  among the Python contributors as well.  Any time you feel that you  can clarify existing documentation or provide documentation that's  missing, the existing documentation team will gladly work with you  to integrate your text, dealing with the markup for you.  Please  don't let the material in this document stand between the  documentation and your desire to help out! \section{Directory Structure \label{directories}}   The source distribution for the standard Python documentation  contains a large number of directories.  While third-party documents  do not need to be placed into this structure or need to be placed  within a similar structure, it can be helpful to know where to look  for examples and tools when developing new documents using the  Python documentation tools.  This section describes this directory  structure.   The documentation sources are usually placed within the Python  source distribution as the top-level directory \file{Doc/}, but  are not dependent on the Python source distribution in any way.   The \file{Doc/} directory contains a few files and several  subdirectories.  The files are mostly self-explanatory, including a  \file{README} and a \file{Makefile}.  The directories fall into  three categories:   \begin{definitions}    \term{Document Sources}        The \LaTeX{} sources for each document are placed in a        separate directory.  These directories are given short        names which vaguely indicate the document in each:         \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Document Title}          \lineii{api/}            {\citetitle[../api/api.html]{The Python/C API}}          \lineii{dist/}            {\citetitle[../dist/dist.html]{Distributing Python Modules}}          \lineii{doc/}            {\citetitle[../doc/doc.html]{Documenting Python}}          \lineii{ext/}            {\citetitle[../ext/ext.html]                       {Extending and Embedding the Python Interpreter}}          \lineii{inst/}            {\citetitle[../inst/inst.html]{Installing Python Modules}}          \lineii{lib/}            {\citetitle[../lib/lib.html]{Python Library Reference}}          \lineii{mac/}            {\citetitle[../mac/mac.html]{Macintosh Module Reference}}          \lineii{ref/}            {\citetitle[../ref/ref.html]{Python Reference Manual}}          \lineii{tut/}            {\citetitle[../tut/tut.html]{Python Tutorial}}          \lineii{whatsnew/}            {\citetitle[../whatsnew/whatsnew24.html]                       {What's New in Python \shortversion}}        \end{tableii}     \term{Format-Specific Output}        Most output formats have a directory which contains a        \file{Makefile} which controls the generation of that format        and provides storage for the formatted documents.  The only        variations within this category are the Portable Document        Format (PDF) and PostScript versions are placed in the        directories \file{paper-a4/} and \file{paper-letter/} (this        causes all the temporary files created by \LaTeX{} to be kept        in the same place for each paper size, where they can be more        easily ignored).         \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Output Formats}          \lineii{html/}{HTML output}          \lineii{info/}{GNU info output}          \lineii{isilo/}{\ulink{iSilo}{http://www.isilo.com/}                          documents (for Palm OS devices)}          \lineii{paper-a4/}{PDF and PostScript, A4 paper}          \lineii{paper-letter/}{PDF and PostScript, US-Letter paper}        \end{tableii}     \term{Supplemental Files}        Some additional directories are used to store supplemental        files used for the various processes.  Directories are        included for the shared \LaTeX{} document classes, the        \LaTeX2HTML support, template files for various document        components, and the scripts used to perform various steps in        the formatting processes.         \begin{tableii}{p{.75in}|p{3in}}{filenq}{Directory}{Contents}          \lineii{commontex/}{Document content shared among documents}          \lineii{perl/}     {Support for \LaTeX2HTML processing}          \lineii{templates/}{Example files for source documents}          \lineii{texinputs/}{Style implementation for \LaTeX}          \lineii{tools/}    {Custom processing scripts}        \end{tableii}   \end{definitions}  \section{Style Guide \label{style-guide}}   The Python documentation should follow the \citetitle  [http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf]  {Apple Publications Style Guide} wherever possible.  This particular  style guide was selected mostly because it seems reasonable and is  easy to get online.   Topics which are not covered in the Apple's style guide will be  discussed in this document if necessary.   Footnotes are generally discouraged due to the pain of using  footnotes in the HTML conversion of documents.  Footnotes may be  used when they are the best way to present specific information.  When a footnote reference is added at the end of the sentence, it  should follow the sentence-ending punctuation.  The \LaTeX{} markup  should appear something like this: \begin{verbatim}This sentence has a footnote reference.%  \footnote{This is the footnote text.}\end{verbatim}   Footnotes may appear in the middle of sentences where appropriate.   Many special names are used in the Python documentation, including  the names of operating systems, programming languages, standards  bodies, and the like.  Many of these were assigned \LaTeX{} macros  at some point in the distant past, and these macros lived on long  past their usefulness.  In the current markup, most of these entities  are not assigned any special markup, but the preferred spellings are  given here to aid authors in maintaining the consistency of  presentation in the Python documentation.   Other terms and words deserve special mention as well; these conventions  should be used to ensure consistency throughout the documentation:   \begin{description}    \item[CPU]    For ``central processing unit.''  Many style guides say this    should be spelled out on the first use (and if you must use it,    do so!).  For the Python documentation, this abbreviation should    be avoided since there's no reasonable way to predict which occurrence    will be the first seen by the reader.  It is better to use the    word ``processor'' instead.     \item[\POSIX]        The name assigned to a particular group of standards.  This is        always uppercase.  Use the macro \macro{POSIX} to represent this        name.     \item[Python]        The name of our favorite programming language is always        capitalized.     \item[Unicode]        The name of a character set and matching encoding.  This is        always written capitalized.     \item[\UNIX]        The name of the operating system developed at AT\&T Bell Labs        in the early 1970s.  Use the macro \macro{UNIX} to use this        name.  \end{description}  \section{\LaTeX{} Primer \label{latex-primer}}   This section is a brief introduction to \LaTeX{} concepts and  syntax, to provide authors enough information to author documents  productively without having to become ``\TeX{}nicians.''  This does  not teach everything needed to know about writing \LaTeX{} for  Python documentation; many of the standard ``environments'' are not  described here (though you will learn how to mark something as an  environment).   Perhaps the most important concept to keep in mind while marking up  Python documentation is that while \TeX{} is unstructured, \LaTeX{} was  designed as a layer on top of \TeX{} which specifically supports  structured markup.  The Python-specific markup is intended to extend  the structure provided by standard \LaTeX{} document classes to  support additional information specific to Python.   \LaTeX{} documents contain two parts: the preamble and the body.  The preamble is used to specify certain metadata about the document  itself, such as the title, the list of authors, the date, and the  \emph{class} the document belongs to.  Additional information used  to control index generation and the use of bibliographic databases  can also be placed in the preamble.  For most authors, the preamble  can be most easily created by copying it from an existing document  and modifying a few key pieces of information.   The \dfn{class} of a document is used to place a document within a  broad category of documents and set some fundamental formatting  properties.  For Python documentation, two classes are used: the  \code{manual} class and the \code{howto} class.  These classes also  define the additional markup used to document Python concepts and  structures.  Specific information about these classes is provided in  section \ref{classes}, ``Document Classes,'' below.  The first thing  in the preamble is the declaration of the document's class.   After the class declaration, a number of \emph{macros} are used to  provide further information about the document and setup any  additional markup that is needed.  No output is generated from the  preamble; it is an error to include free text in the preamble  because it would cause output.   The document body follows the preamble.  This contains all the  printed components of the document marked up structurally.  Generic  \LaTeX{} structures include hierarchical sections, numbered and  bulleted lists, and special structures for the document abstract and  indexes.   \subsection{Syntax \label{latex-syntax}}     There are some things that an author of Python documentation needs    to know about \LaTeX{} syntax.     A \dfn{comment} is started by the ``percent'' character    (\character{\%}) and continues through the end of the line    \emph{and all leading whitespace on the following line}.  This is    a little different from any programming language I know of, so an    example is in order: \begin{verbatim}This is text.% comment    This is more text.  % another commentStill more text.\end{verbatim}     The first non-comment character following the first comment is the    letter \character{T} on the second line; the leading whitespace on    that line is consumed as part of the first comment.  This means    that there is no space between the first and second sentences, so    the period and letter \character{T} will be directly adjacent in    the typeset document.     Note also that though the first non-comment character after the    second comment is the letter \character{S}, there is whitespace    preceding the comment, so the two sentences are separated as    expected.     A \dfn{group} is an enclosure for a collection of text and    commands which encloses the formatting context and constrains the    scope of any changes to that context made by commands within the    group.  Groups can be nested hierarchically.  The formatting    context includes the font and the definition of additional macros    (or overrides of macros defined in outer groups).  Syntactically,    groups are enclosed in braces: \begin{verbatim}{text in a group}\end{verbatim}     An alternate syntax for a group using brackets, \code{[...]}, is    used by macros and environment constructors which take optional    parameters; brackets do not normally hold syntactic significance.    A degenerate group, containing only one atomic bit of content,    does not need to have an explicit group, unless it is required to    avoid ambiguity.  Since Python tends toward the explicit, groups    are also made explicit in the documentation markup.     Groups are used only sparingly in the Python documentation, except    for their use in marking parameters to macros and environments.     A \dfn{macro} is usually a simple construct which is identified by    name and can take some number of parameters.  In normal \LaTeX{}    usage, one of these can be optional.  The markup is introduced    using the backslash character (\character{\e}), and the name is    given by alphabetic characters (no digits, hyphens, or    underscores).  Required parameters should be marked as a group,    and optional parameters should be marked using the alternate    syntax for a group.     For example, a macro which takes a single parameter    would appear like this: \begin{verbatim}\name{parameter}\end{verbatim}     A macro which takes an optional parameter would be typed like this    when the optional parameter is given: \begin{verbatim}\name[optional]\end{verbatim}     If both optional and required parameters are to be required, it    looks like this: \begin{verbatim}\name[optional]{required}\end{verbatim}     A macro name may be followed by a space or newline; a space    between the macro name and any parameters will be consumed, but    this usage is not practiced in the Python documentation.  Such a    space is still consumed if there are no parameters to the macro,    in which case inserting an empty group (\code{\{\}}) or explicit    word space (\samp{\e\ }) immediately after the macro name helps to    avoid running the expansion of the macro into the following text.    Macros which take no parameters but which should not be followed    by a word space do not need special treatment if the following    character in the document source if not a name character (such as    punctuation).     Each line of this example shows an appropriate way to write text    which includes a macro which takes no parameters: \begin{verbatim}This \UNIX{} is followed by a space.This \UNIX\ is also followed by a space.\UNIX, followed by a comma, needs no additional markup.\end{verbatim}     An \dfn{environment} is a larger construct than a macro, and can    be used for things with more content than would conveniently fit    in a macro parameter.  They are primarily used when formatting    parameters need to be changed before and after a large chunk of    content, but the content itself needs to be highly flexible.  Code    samples are presented using an environment, and descriptions of    functions, methods, and classes are also marked using environments.     Since the content of an environment is free-form and can consist    of several paragraphs, they are actually marked using a pair of    macros: \macro{begin} and \macro{end}.  These macros both take the    name of the environment as a parameter.  An example is the    environment used to mark the abstract of a document: \begin{verbatim}\begin{abstract}  This is the text of the abstract.  It concisely explains what  information is found in the document.   It can consist of multiple paragraphs.\end{abstract}\end{verbatim}     An environment can also have required and optional parameters of    its own.  These follow the parameter of the \macro{begin} macro.    This example shows an environment which takes a single required    parameter: \begin{verbatim}\begin{datadesc}{controlnames}  A 33-element string array that contains the \ASCII{} mnemonics for  the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f  (US), in order, plus the mnemonic \samp{SP} for the space character.\end{datadesc}\end{verbatim}     There are a number of less-used marks in \LaTeX{} which are used    to enter characters which are not found in \ASCII{} or which a    considered special, or \emph{active} in \TeX{} or \LaTeX.  Given    that these are often used adjacent to other characters, the markup    required to produce the proper character may need to be followed    by a space or an empty group, or the markup can be enclosed in a    group.  Some which are found in Python documentation are: \begin{tableii}{c|l}{textrm}{Character}{Markup}  \lineii{\textasciicircum}{\code{\e textasciicircum}}  \lineii{\textasciitilde}{\code{\e textasciitilde}}  \lineii{\textgreater}{\code{\e textgreater}}  \lineii{\textless}{\code{\e textless}}  \lineii{\c c}{\code{\e c c}}  \lineii{\"o}{\code{\e"o}}  \lineii{\o}{\code{\e o}}\end{tableii}    \subsection{Hierarchical Structure \label{latex-structure}}     \LaTeX{} expects documents to be arranged in a conventional,    hierarchical way, with chapters, sections, sub-sections,    appendixes, and the like.  These are marked using macros rather    than environments, probably because the end of a section can be    safely inferred when a section of equal or higher level starts.     There are six ``levels'' of sectioning in the document classes    used for Python documentation, and the deepest two    levels\footnote{The deepest levels have the highest numbers in the      table.} are not used.  The levels are:       \begin{tableiii}{c|l|c}{textrm}{Level}{Macro Name}{Notes}        \lineiii{1}{\macro{chapter}}{(1)}        \lineiii{2}{\macro{section}}{}        \lineiii{3}{\macro{subsection}}{}        \lineiii{4}{\macro{subsubsection}}{}        \lineiii{5}{\macro{paragraph}}{(2)}        \lineiii{6}{\macro{subparagraph}}{}      \end{tableiii}     \noindent    Notes:     \begin{description}      \item[(1)]      Only used for the \code{manual} documents, as described in      section \ref{classes}, ``Document Classes.''      \item[(2)]      Not the same as a paragraph of text; nobody seems to use this.    \end{description}    \subsection{Common Environments \label{latex-environments}}     \LaTeX{} provides a variety of environments even without the    additional markup provided by the Python-specific document classes    introduced in the next section.  The following environments are    provided as part of standard \LaTeX{} and are being used in the    standard Python documentation; descriptions will be added here as    time allows. \begin{verbatim}abstractallttdescriptiondisplaymathdocumentenumeratefigure

Lines 1–500 of 2129. Load more