89 |
Write in the present tense, not in the past or the future. |
Write in the present tense, not in the past or the future. |
90 |
|
|
91 |
</li><li> |
</li><li> |
92 |
Write actively! For example, write "We recommend that …" rather |
Write actively! For example, write “We recommend that …” rather |
93 |
than "It is recommended that …". |
than “It is recommended that …”. |
94 |
|
|
95 |
</li><li> |
</li><li> |
96 |
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. |
120 |
|
|
121 |
</li><li> |
</li><li> |
122 |
Write index entries only where a topic is discussed significantly. For |
Write index entries only where a topic is discussed significantly. For |
123 |
example, it is not useful to index "debugging information" in a |
example, it is not useful to index “debugging information” in a |
124 |
chapter on reporting bugs. Someone who wants to know about debugging |
chapter on reporting bugs. Someone who wants to know about debugging |
125 |
information will certainly not find it in that chapter. |
information will certainly not find it in that chapter. |
126 |
|
|
143 |
a paragraph before that paragraph. |
a paragraph before that paragraph. |
144 |
|
|
145 |
<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 |
146 |
entry for "Leaping": |
entry for “Leaping”: |
147 |
</p> |
</p> |
148 |
<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 |
149 |
@cindex Jumping, in general |
@cindex Jumping, in general |
157 |
</pre></td></tr></table> |
</pre></td></tr></table> |
158 |
|
|
159 |
<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 |
160 |
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 |
161 |
readers can look up the concept in different ways.) |
readers can look up the concept in different ways.) |
162 |
</p></li></ul> |
</p></li></ul> |
163 |
|
|
210 |
|
|
211 |
</li><li> |
</li><li> |
212 |
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 |
213 |
a complete expression. Do not write "You can set:"; instead, write |
a complete expression. Do not write “You can set:”; instead, write |
214 |
"You can set these variables:". The former expression sounds cut off. |
“You can set these variables:”. The former expression sounds cut off. |
215 |
</li></ul> |
</li></ul> |
216 |
|
|
217 |
<a name="SEC282"></a> |
<a name="SEC282"></a> |
251 |
|
|
252 |
<ul> |
<ul> |
253 |
<li> |
<li> |
254 |
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 |
255 |
<samp>`i'</samp> in upper case. |
<samp>`i'</samp> in upper case. |
256 |
|
|
257 |
</li><li> |
</li><li> |
258 |
Capitalize "Info"; it is a name. |
Capitalize “Info”; it is a name. |
259 |
|
|
260 |
</li><li> |
</li><li> |
261 |
Write TeX using the <code>@TeX{}</code> command. Note the uppercase |
Write TeX using the <code>@TeX{}</code> command. Note the uppercase |
339 |
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 |
340 |
understand them from context; or write a definition for the term. |
understand them from context; or write a definition for the term. |
341 |
|
|
342 |
<p>For example, in the following, the terms "check in", "register" and |
<p>For example, in the following, the terms “check in”, “register” and |
343 |
"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 |
344 |
rewritten so they are understandable. |
rewritten so they are understandable. |
345 |
</p> |
</p> |
346 |
<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 |
410 |
|
|
411 |
<p>Here are several examples of bad writing to avoid: |
<p>Here are several examples of bad writing to avoid: |
412 |
</p> |
</p> |
413 |
<p>In this example, say, " … you must <code>@dfn</code>{check |
<p>In this example, say, “ … you must <code>@dfn</code>{check |
414 |
in} the new version." That flows better. |
in} the new version.” That flows better. |
415 |
</p> |
</p> |
416 |
<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 |
417 |
<code>@dfn</code>{check in}. |
<code>@dfn</code>{check in}. |
418 |
</p></blockquote> |
</p></blockquote> |
419 |
|
|
420 |
<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 |
421 |
mode possible." |
mode possible.” |
422 |
</p> |
</p> |
423 |
<blockquote><p>SCCS, RCS and other version-control systems all perform similar |
<blockquote><p>SCCS, RCS and other version-control systems all perform similar |
424 |
functions in broadly similar ways (it is this resemblance which makes |
functions in broadly similar ways (it is this resemblance which makes |
438 |
<li> |
<li> |
439 |
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 |
440 |
sound in the name `Bach'. But pronounce Texinfo as in `speck': |
sound in the name `Bach'. But pronounce Texinfo as in `speck': |
441 |
"teckinfo". |
“teckinfo”. |
442 |
|
|
443 |
</li><li> |
</li><li> |
444 |
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 |