|
11 | 11 | \author{Fred L. Drake, Jr.} |
12 | 12 | \authoraddress{ |
13 | 13 | PythonLabs \\ |
14 | | - |
| 14 | + |
15 | 15 | } |
16 | 16 |
|
17 | 17 |
|
@@ -170,23 +170,39 @@ \section{Style Guide} |
170 | 170 | the names of operating systems, programming languages, standards |
171 | 171 | bodies, and the like. Many of these were assigned \LaTeX{} macros |
172 | 172 | 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 |
175 | 175 | given here to aid authors in maintaining the consistency of |
176 | 176 | presentation in the Python documentation. |
177 | 177 |
|
| 178 | + Other terms and words deserve special mention as well; these conventions |
| 179 | + should be used to ensure consistency throughout the documentation: |
| 180 | + |
178 | 181 | \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] |
180 | 191 | 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. |
182 | 194 |
|
183 | 195 | \item[Python] |
184 | 196 | The name of our favorite programming language is always |
185 | 197 | capitalized. |
186 | 198 |
|
187 | 199 | \item[Unicode] |
188 | 200 | 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. |
190 | 206 | \end{description} |
191 | 207 |
|
192 | 208 |
|
@@ -828,7 +844,7 @@ \section{Special Markup Constructs} |
828 | 844 | \end{macrodesc} |
829 | 845 |
|
830 | 846 | \begin{macrodesc}{newsgroup}{\p{name}} |
831 | | - The name of a USENET newsgroup. |
| 847 | + The name of a Usenet newsgroup. |
832 | 848 | \end{macrodesc} |
833 | 849 |
|
834 | 850 | \begin{macrodesc}{pep}{\p{number}} |
@@ -975,7 +991,7 @@ \section{\module{spam} --- |
975 | 991 |
|
976 | 992 | \declaremodule{extension}{spam} |
977 | 993 | \platform{Unix} |
978 | | -\modulesynopsis{Access to the SPAM facility of \UNIX{}.} |
| 994 | +\modulesynopsis{Access to the SPAM facility of \UNIX.} |
979 | 995 | \moduleauthor{Jane Doe}{[email protected]} |
980 | 996 | \end{verbatim} |
981 | 997 |
|
|
0 commit comments