mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 10:50:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

Make a number of small clarifications and correct a whole bunch of typos,

Browse source 
all reported by Bruce Smith.
This commit is contained in:
Fred Drake 2001-04-18 05:12:47 +00:00
parent 635a7cfcbb
commit 4c6f17a537
1 changed files with 18 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

33
Doc/doc/doc.tex
View file

@ -192,12 +192,14 @@ distribution, to create or maintain whole documents or sections.
The document body follows the preamble. This contains all the The document body follows the preamble. This contains all the
printed components of the document marked up structurally. Generic printed components of the document marked up structurally. Generic
\LaTeX{} structures include hierarchical sections \LaTeX{} structures include hierarchical sections, numbered and
bulleted lists, and special structures for the document abstract and
indexes.
\subsection{Syntax} \subsection{Syntax}
There are a things that an author of Python documentation needs to There are some things that an author of Python documentation needs
know about \LaTeX{} syntax. to know about \LaTeX{} syntax.
A \dfn{comment} is started by the ``percent'' character A \dfn{comment} is started by the ``percent'' character
(\character{\%}) and continues through the end of the line and all (\character{\%}) and continues through the end of the line and all
@ -235,7 +237,7 @@ Still more text.
{text in a group} {text in a group}
\end{verbatim} \end{verbatim}
An alternate syntax for a group using brackets (\code{[...]}) is An alternate syntax for a group using brackets, \code{[...]}, is
used by macros and environment constructors which take optional used by macros and environment constructors which take optional
parameters; brackets do not normally hold syntactic significance. parameters; brackets do not normally hold syntactic significance.
A degenerate group, containing only one atomic bit of content, A degenerate group, containing only one atomic bit of content,
@ -246,7 +248,7 @@ Still more text.
Groups are used only sparingly in the Python documentation, except Groups are used only sparingly in the Python documentation, except
for their use in marking parameters to macros and environments. for their use in marking parameters to macros and environments.
A \dfn{macro} is usually simple construct which is identified by A \dfn{macro} is usually a simple construct which is identified by
name and can take some number of parameters. In normal \LaTeX{} name and can take some number of parameters. In normal \LaTeX{}
usage, one of these can be optional. The markup is introduced usage, one of these can be optional. The markup is introduced
using the backslash character (\character{\e}), and the name is using the backslash character (\character{\e}), and the name is
@ -279,14 +281,14 @@ Still more text.
A macro name may be followed by a space or newline; a space A macro name may be followed by a space or newline; a space
between the macro name and any parameters will be consumed, but between the macro name and any parameters will be consumed, but
this usage is not practiced in the Python documentation. Such a this usage is not practiced in the Python documentation. Such a
space is still consumed if there are no parameters to the marco, space is still consumed if there are no parameters to the macro,
in which case inserting an empty group (\code{\{\}}) or explicit in which case inserting an empty group (\code{\{\}}) or explicit
word space (\samp{\e\ }) immediately after the macro name helps to word space (\samp{\e\ }) immediately after the macro name helps to
avoid running the expansion of the macro into the following text. avoid running the expansion of the macro into the following text.
Macros which take no parameters but which should not be followed Macros which take no parameters but which should not be followed
by a word space do not need special treatment if the following by a word space do not need special treatment if the following
character in the document source if not a name character (such as character in the document source if not a name character (such as
puctuation). punctuation).
Each line of this example shows an appropriate way to write text Each line of this example shows an appropriate way to write text
which includes a macro which takes no parameters: which includes a macro which takes no parameters:
@ -298,12 +300,12 @@ This \UNIX\ is also followed by a space.
\end{verbatim} \end{verbatim}
An \dfn{environment} is a larger construct than a macro, and can An \dfn{environment} is a larger construct than a macro, and can
be used for things with more content that would conveniently fit be used for things with more content than would conveniently fit
in a macro parameter. They are primarily used when formatting in a macro parameter. They are primarily used when formatting
parameters need to be changed before and after a large chunk of parameters need to be changed before and after a large chunk of
content, but the content itself needs to be highly flexible. Code content, but the content itself needs to be highly flexible. Code
samples are presented using an environment, and descriptions of samples are presented using an environment, and descriptions of
functions, methods, and classes are also marked using envionments. functions, methods, and classes are also marked using environments.
Since the content of an environment is free-form and can consist Since the content of an environment is free-form and can consist
of several paragraphs, they are actually marked using a pair of of several paragraphs, they are actually marked using a pair of
@ -333,11 +335,11 @@ This \UNIX\ is also followed by a space.
\end{datadesc} \end{datadesc}
\end{verbatim} \end{verbatim}
There are a number of less-used marks in \LaTeX{} are used to There are a number of less-used marks in \LaTeX{} which are used
enter non-\ASCII{} characters, especially those used in European to enter non-\ASCII{} characters, especially those used in
names. Given that these are often used adjacent to other European names. Given that these are often used adjacent to other
characters, the markup required to produce the proper character characters, the markup required to produce the proper character
may need to be followed by a space or an empty group, or the the 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 markup can be enclosed in a group. Some which are found in Python
documentation are: documentation are:
@ -357,8 +359,9 @@ This \UNIX\ is also followed by a space.
safely inferred when a section of equal or higher level starts. safely inferred when a section of equal or higher level starts.
There are six ``levels'' of sectioning in the document classes There are six ``levels'' of sectioning in the document classes
used for Python documentation, and the lowest two levels are not used for Python documentation, and the deepest two
used. The levels are: 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} \begin{tableiii}{c|l|c}{textrm}{Level}{Macro Name}{Notes}
\lineiii{1}{\macro{chapter}}{(1)} \lineiii{1}{\macro{chapter}}{(1)}