\term{Document Sources}
The \LaTeX{} sources for each document are placed in a
separate directory. These directories are given short,
- three-character names.
+ 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}
\term{Format-Specific Output}
Most output formats have a directory which contains a
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{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
\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{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}
\subsection{Information Units \label{info-units}}
- XXX Check Maler's book for proper terminology.
+ XXX Explain terminology, or come up with something more ``lay.''
There are a number of environments used to describe specific
features provided by modules. Each environment requires
\subsection{Inline Markup}
- This is where to explain \macro{code}, \macro{function},
- \macro{email}, etc.
+
+ \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}
+
+ \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}{optional}{\p{text}}
+ \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}
+
+ \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}
\subsection{Module-specific Markup}
projects / python / commitdiff