Skip to content

Commit 9120df3

Browse files
committed
Add a little more information about the usage of some terms where the
style guide can use a little clarification, and present some minor specific markup. Make a few adjustments to conform to the style guide.
1 parent 7a889ce commit 9120df3

File tree

1 file changed

+24
-8
lines changed

1 file changed

+24
-8
lines changed

Doc/doc/doc.tex

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
\author{Fred L. Drake, Jr.}
1212
\authoraddress{
1313
PythonLabs \\
14-
E-mail: \email{[email protected]}
14+
Email: \email{[email protected]}
1515
}
1616

1717

@@ -170,23 +170,39 @@ \section{Style Guide}
170170
the names of operating systems, programming languages, standards
171171
bodies, and the like. Many of these were assigned \LaTeX{} macros
172172
at some point in the distant past, and these macros lived on long
173-
past their usefulness. In the current markup, these entities are
174-
not assigned any special markup, but the preferred spellings are
173+
past their usefulness. In the current markup, most of these entities
174+
are not assigned any special markup, but the preferred spellings are
175175
given here to aid authors in maintaining the consistency of
176176
presentation in the Python documentation.
177177

178+
Other terms and words deserve special mention as well; these conventions
179+
should be used to ensure consistency throughout the documentation:
180+
178181
\begin{description}
179-
\item[POSIX]
182+
\item[CPU]
183+
For ``central processing unit.'' Many style guides say this
184+
should be spelled out on the first use (and if you must use it,
185+
do so!). For the Python documentation, this abbreviation should
186+
be avoided since there's no reasonable way to predict which occurance
187+
will be the first seen by the reader. It is better to use the
188+
word ``processor'' instead.
189+
190+
\item[\POSIX]
180191
The name assigned to a particular group of standards. This is
181-
always uppercase.
192+
always uppercase. Use the macro \macro{POSIX} to represent this
193+
name.
182194

183195
\item[Python]
184196
The name of our favorite programming language is always
185197
capitalized.
186198

187199
\item[Unicode]
188200
The name of a character set and matching encoding. This is
189-
always written capitalized.
201+
always written capitalized.
202+
203+
\item[\UNIX]
204+
The name of the operating system developed at AT\&T Bell Labs
205+
in the early 1970s. Use the macro \macro{UNIX} to use this name.
190206
\end{description}
191207

192208

@@ -828,7 +844,7 @@ \section{Special Markup Constructs}
828844
\end{macrodesc}
829845

830846
\begin{macrodesc}{newsgroup}{\p{name}}
831-
The name of a USENET newsgroup.
847+
The name of a Usenet newsgroup.
832848
\end{macrodesc}
833849

834850
\begin{macrodesc}{pep}{\p{number}}
@@ -975,7 +991,7 @@ \section{\module{spam} ---
975991
976992
\declaremodule{extension}{spam}
977993
\platform{Unix}
978-
\modulesynopsis{Access to the SPAM facility of \UNIX{}.}
994+
\modulesynopsis{Access to the SPAM facility of \UNIX.}
979995
\moduleauthor{Jane Doe}{[email protected]}
980996
\end{verbatim}
981997

0 commit comments

Comments
 (0)