# [Python-checkins] CVS: python/dist/src/Doc/doc doc.tex,1.38,1.39

Fred L. Drake fdrake@users.sourceforge.net
Tue, 17 Apr 2001 22:12:49 -0700

Update of /cvsroot/python/python/dist/src/Doc/doc
In directory usw-pr-cvs1:/tmp/cvs-serv5930/doc

Modified Files:
doc.tex
Log Message:

Make a number of small clarifications and correct a whole bunch of typos,
all reported by Bruce Smith.

Index: doc.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/doc/doc.tex,v
retrieving revision 1.38
retrieving revision 1.39
diff -C2 -r1.38 -r1.39
*** doc.tex	2001/03/28 16:51:20	1.38
--- doc.tex	2001/04/18 05:12:47	1.39
***************
*** 193,202 ****
The document body follows the preamble.  This contains all the
printed components of the document marked up structurally.  Generic
!   \LaTeX{} structures include hierarchical sections

\subsection{Syntax}

!     There are a things that an author of Python documentation needs to

A \dfn{comment} is started by the percent'' character
--- 193,204 ----
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}

!     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
***************
*** 236,240 ****
\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.
--- 238,242 ----
\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.
***************
*** 247,251 ****
for their use in marking parameters to macros and environments.

!     A \dfn{macro} is usually 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
--- 249,253 ----
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
***************
*** 280,284 ****
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 marco,
in which case inserting an empty group (\code{\{\}}) or explicit
word space (\samp{\e\ }) immediately after the macro name helps to
--- 282,286 ----
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
***************
*** 287,291 ****
by a word space do not need special treatment if the following
character in the document source if not a name character (such as
!     puctuation).

Each line of this example shows an appropriate way to write text
--- 289,293 ----
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
***************
*** 299,308 ****

An \dfn{environment} is a larger construct than a macro, and can
!     be used for things with more content that 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 envionments.

Since the content of an environment is free-form and can consist
--- 301,310 ----

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
***************
*** 334,342 ****
\end{verbatim}

!     There are a number of less-used marks in \LaTeX{} are used to
!     enter non-\ASCII{} characters, especially those used in European
!     names.  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 the
markup can be enclosed in a group.  Some which are found in Python
documentation are:
--- 336,344 ----
\end{verbatim}

!     There are a number of less-used marks in \LaTeX{} which are used
!     to enter non-\ASCII{} characters, especially those used in
!     European names.  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:
***************
*** 358,363 ****

There are six levels'' of sectioning in the document classes
!     used for Python documentation, and the lowest two levels are not
!     used.  The levels are:

\begin{tableiii}{c|l|c}{textrm}{Level}{Macro Name}{Notes}
--- 360,366 ----

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}