90 |
Write in the present tense, not in the past or the future. |
Write in the present tense, not in the past or the future. |
91 |
|
|
92 |
</li><li> |
</li><li> |
93 |
Write actively! For example, write "We recommend that …" rather |
Write actively! For example, write “We recommend that …” rather |
94 |
than "It is recommended that …". |
than “It is recommended that …”. |
95 |
|
|
96 |
</li><li> |
</li><li> |
97 |
Use 70 or 72 as your fill column. Longer lines are hard to read. |
Use 70 or 72 as your fill column. Longer lines are hard to read. |
121 |
|
|
122 |
</li><li> |
</li><li> |
123 |
Write index entries only where a topic is discussed significantly. For |
Write index entries only where a topic is discussed significantly. For |
124 |
example, it is not useful to index "debugging information" in a |
example, it is not useful to index “debugging information” in a |
125 |
chapter on reporting bugs. Someone who wants to know about debugging |
chapter on reporting bugs. Someone who wants to know about debugging |
126 |
information will certainly not find it in that chapter. |
information will certainly not find it in that chapter. |
127 |
|
|
144 |
a paragraph before that paragraph. |
a paragraph before that paragraph. |
145 |
|
|
146 |
<p>In the example that follows, a blank line comes after the index |
<p>In the example that follows, a blank line comes after the index |
147 |
entry for "Leaping": |
entry for “Leaping”: |
148 |
</p> |
</p> |
149 |
<table><tr><td> </td><td><pre class="example">@section The Dog and the Fox |
<table><tr><td> </td><td><pre class="example">@section The Dog and the Fox |
150 |
@cindex Jumping, in general |
@cindex Jumping, in general |
158 |
</pre></td></tr></table> |
</pre></td></tr></table> |
159 |
|
|
160 |
<p>(Note that the example shows entries for the same concept that are |
<p>(Note that the example shows entries for the same concept that are |
161 |
written in different ways--<samp>`Lazy dog'</samp>, and <samp>`Dog, lazy'</samp>--so |
written in different ways—<samp>`Lazy dog'</samp>, and <samp>`Dog, lazy'</samp>—so |
162 |
readers can look up the concept in different ways.) |
readers can look up the concept in different ways.) |
163 |
</p></li></ul> |
</p></li></ul> |
164 |
|
|
211 |
|
|
212 |
</li><li> |
</li><li> |
213 |
Write the prefatory sentence or phrase for a multi-item list or table as |
Write the prefatory sentence or phrase for a multi-item list or table as |
214 |
a complete expression. Do not write "You can set:"; instead, write |
a complete expression. Do not write “You can set:”; instead, write |
215 |
"You can set these variables:". The former expression sounds cut off. |
“You can set these variables:”. The former expression sounds cut off. |
216 |
</li></ul> |
</li></ul> |
217 |
|
|
218 |
<a name="SEC282"></a> |
<a name="SEC282"></a> |
252 |
|
|
253 |
<ul> |
<ul> |
254 |
<li> |
<li> |
255 |
Capitalize "Texinfo"; it is a name. Do not write the <samp>`x'</samp> or |
Capitalize “Texinfo”; it is a name. Do not write the <samp>`x'</samp> or |
256 |
<samp>`i'</samp> in upper case. |
<samp>`i'</samp> in upper case. |
257 |
|
|
258 |
</li><li> |
</li><li> |
259 |
Capitalize "Info"; it is a name. |
Capitalize “Info”; it is a name. |
260 |
|
|
261 |
</li><li> |
</li><li> |
262 |
Write TeX using the <code>@TeX{}</code> command. Note the uppercase |
Write TeX using the <code>@TeX{}</code> command. Note the uppercase |
340 |
Introduce new terms so that a reader who does not know them can |
Introduce new terms so that a reader who does not know them can |
341 |
understand them from context; or write a definition for the term. |
understand them from context; or write a definition for the term. |
342 |
|
|
343 |
<p>For example, in the following, the terms "check in", "register" and |
<p>For example, in the following, the terms “check in”, “register” and |
344 |
"delta" are all appearing for the first time; the example sentence should be |
“delta” are all appearing for the first time; the example sentence should be |
345 |
rewritten so they are understandable. |
rewritten so they are understandable. |
346 |
</p> |
</p> |
347 |
<blockquote><p>The major function assists you in checking in a file to your |
<blockquote><p>The major function assists you in checking in a file to your |
411 |
|
|
412 |
<p>Here are several examples of bad writing to avoid: |
<p>Here are several examples of bad writing to avoid: |
413 |
</p> |
</p> |
414 |
<p>In this example, say, " … you must <code>@dfn</code>{check |
<p>In this example, say, “ … you must <code>@dfn</code>{check |
415 |
in} the new version." That flows better. |
in} the new version.” That flows better. |
416 |
</p> |
</p> |
417 |
<blockquote><p>When you are done editing the file, you must perform a |
<blockquote><p>When you are done editing the file, you must perform a |
418 |
<code>@dfn</code>{check in}. |
<code>@dfn</code>{check in}. |
419 |
</p></blockquote> |
</p></blockquote> |
420 |
|
|
421 |
<p>In the following example, say, "… makes a unified interface such as VC |
<p>In the following example, say, “… makes a unified interface such as VC |
422 |
mode possible." |
mode possible.” |
423 |
</p> |
</p> |
424 |
<blockquote><p>SCCS, RCS and other version-control systems all perform similar |
<blockquote><p>SCCS, RCS and other version-control systems all perform similar |
425 |
functions in broadly similar ways (it is this resemblance which makes |
functions in broadly similar ways (it is this resemblance which makes |
439 |
<li> |
<li> |
440 |
Pronounce TeX as if the <samp>`X'</samp> were a Greek `chi', as the last |
Pronounce TeX as if the <samp>`X'</samp> were a Greek `chi', as the last |
441 |
sound in the name `Bach'. But pronounce Texinfo as in `speck': |
sound in the name `Bach'. But pronounce Texinfo as in `speck': |
442 |
"teckinfo". |
“teckinfo”. |
443 |
|
|
444 |
</li><li> |
</li><li> |
445 |
Write notes for yourself at the very end of a Texinfo file after the |
Write notes for yourself at the very end of a Texinfo file after the |