[Python-checkins] python/dist/src/Doc/doc doc.tex,1.73,1.74
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Thu, 10 Jul 2003 20:36:17 -0700
Update of /cvsroot/python/python/dist/src/Doc/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv6532
Modified Files:
doc.tex
Log Message:
normalize whitespace
Index: doc.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/doc/doc.tex,v
retrieving revision 1.73
retrieving revision 1.74
diff -C2 -d -r1.73 -r1.74
*** doc.tex 11 Jul 2003 03:34:17 -0000 1.73
--- doc.tex 11 Jul 2003 03:36:15 -0000 1.74
***************
*** 13,18 ****
\author{Fred L. Drake, Jr.}
\authoraddress{
! PythonLabs \\
! Email: \email{fdrake@acm.org}
}
--- 13,18 ----
\author{Fred L. Drake, Jr.}
\authoraddress{
! PythonLabs \\
! Email: \email{fdrake@acm.org}
}
***************
*** 95,157 ****
\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}}
! \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{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}
--- 95,157 ----
\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}}
! \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{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}
***************
*** 191,209 ****
\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}
--- 191,210 ----
\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}
***************
*** 217,221 ****
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
--- 218,222 ----
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
***************
*** 502,506 ****
the address should be lower case.
! No presentation is generated from this markup, but it is used to
help keep track of contributions.
\end{macrodesc}
--- 503,507 ----
the address should be lower case.
! No presentation is generated from this markup, but it is used to
help keep track of contributions.
\end{macrodesc}
***************
*** 679,683 ****
>>> 1 + 1
2
! >>>
\end{verbatim}
--- 680,684 ----
>>> 1 + 1
2
! >>>
\end{verbatim}
***************
*** 774,778 ****
\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. It should be
--- 775,779 ----
\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. It should be
***************
*** 783,787 ****
\begin{macrodesc}{dfn}{\p{term}}
! Mark the defining instance of \var{term} in the text. (No index
entries are generated.)
\end{macrodesc}
--- 784,788 ----
\begin{macrodesc}{dfn}{\p{term}}
! Mark the defining instance of \var{term} in the text. (No index
entries are generated.)
\end{macrodesc}
***************
*** 822,826 ****
\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.
\warning{The \macro{filenq} macro cannot be used in the
--- 823,827 ----
\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.
\warning{The \macro{filenq} macro cannot be used in the
***************
*** 924,929 ****
\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
Windows programs.
\end{macrodesc}
--- 925,930 ----
\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
Windows programs.
\end{macrodesc}
***************
*** 942,946 ****
\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
--- 943,947 ----
\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
***************
*** 955,959 ****
\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
--- 956,960 ----
\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
***************
*** 963,967 ****
\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}
--- 964,968 ----
\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}
***************
*** 996,1000 ****
\begin{macrodesc}{url}{\p{url}}
! A URL (or URN). The URL will be presented as text. In the HTML
and PDF formatted versions, the URL will also be a hyperlink.
This can be used when referring to external resources without
--- 997,1001 ----
\begin{macrodesc}{url}{\p{url}}
! A URL (or URN). The URL will be presented as text. In the HTML
and PDF formatted versions, the URL will also be a hyperlink.
This can be used when referring to external resources without
***************
*** 1305,1310 ****
{Base category for warnings about dubious runtime features.}
\lineii{FutureWarning}
! {Base category for warnings about constructs that will change
! semantically in the future.}
\end{tableii}
\end{verbatim}
--- 1306,1311 ----
{Base category for warnings about dubious runtime features.}
\lineii{FutureWarning}
! {Base category for warnings about constructs that will change
! semantically in the future.}
\end{tableii}
\end{verbatim}
***************
*** 1556,1560 ****
\begin{macrodesc}{indexii}{\p{word1}\p{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}
--- 1557,1561 ----
\begin{macrodesc}{indexii}{\p{word1}\p{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}
***************
*** 1767,1776 ****
\item[\program{mkhowto}]
This is the primary script used to format third-party
! documents. It contains all the logic needed to ``get it
! right.'' The proper way to use this script is to make a
! symbolic link to it or run it in place; the actual script file
! must be stored as part of the documentation source tree,
! though it may be used to format documents outside the
! tree. Use \program{mkhowto} \longprogramopt{help}
for a list of
command line options.
--- 1768,1777 ----
\item[\program{mkhowto}]
This is the primary script used to format third-party
! documents. It contains all the logic needed to ``get it
! right.'' The proper way to use this script is to make a
! symbolic link to it or run it in place; the actual script file
! must be stored as part of the documentation source tree,
! though it may be used to format documents outside the
! tree. Use \program{mkhowto} \longprogramopt{help}
for a list of
command line options.
***************
*** 1781,1785 ****
version from an older source release of Python.
! XXX Need more here.
\end{description}
--- 1782,1786 ----
version from an older source release of Python.
! XXX Need more here.
\end{description}
***************
*** 1894,1898 ****
documentation. Some XSLT stylesheets have been started for
presenting a preliminary XML version as HTML, but the results are
! fairly rough..
The timeframe for the conversion is not clear since there doesn't
--- 1895,1899 ----
documentation. Some XSLT stylesheets have been started for
presenting a preliminary XML version as HTML, but the results are
! fairly rough.
The timeframe for the conversion is not clear since there doesn't