Spelling correction. Explain that two spaces come between sentences, not
at the beginning or end of a sentence. Modernize the acronym guidelines.
This commit is contained in:
parent
fae0d73ebe
commit
58d6e8e361
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42368
1 changed files with 20 additions and 24 deletions
|
@ -38,7 +38,7 @@
|
|||
<title>Tips</title>
|
||||
|
||||
<para>Technical documentation can be improved by consistent use of
|
||||
several principes. Most of these can be classified into three
|
||||
several principles. Most of these can be classified into three
|
||||
goals: <emphasis>be clear</emphasis>,
|
||||
<emphasis>be complete</emphasis>, and
|
||||
<emphasis>be concise</emphasis>. These goals can conflict with
|
||||
|
@ -236,20 +236,19 @@
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Two spaces at the end of sentences</term>
|
||||
<term>Two spaces between sentences</term>
|
||||
|
||||
<listitem>
|
||||
<para>Always use two spaces at the end of sentences, as this
|
||||
improves readability, and eases use of tools such as
|
||||
<para>Always use two spaces between sentences, as this
|
||||
improves readability and eases use of tools such as
|
||||
<application>Emacs</application>.</para>
|
||||
|
||||
<para>While it may be argued that a capital letter following
|
||||
a period denotes a new sentence, this is not the case,
|
||||
especially in name usage.
|
||||
<quote>Jordan K. Hubbard</quote> is a good example; it has
|
||||
<para>A period and spaces followed by a capital letter
|
||||
does not always mark a new sentence,
|
||||
especially in names.
|
||||
<quote>Jordan K. Hubbard</quote> is a good example. It has
|
||||
a capital <literal>H</literal> following a period and a
|
||||
space, and there certainly is not a new sentence
|
||||
there.</para>
|
||||
space, and is certainly not a new sentence.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
@ -283,21 +282,18 @@
|
|||
<sect2>
|
||||
<title>Acronyms</title>
|
||||
|
||||
<para>Acronyms should generally be spelled out the first time
|
||||
<para>Acronyms should be spelled out the first time
|
||||
they appear in a document, as in: <quote>Network Time Protocol
|
||||
(<acronym role="Network Time Protocol">NTP</acronym>)</quote>.
|
||||
After the acronym has been defined, you should generally use
|
||||
the acronym only (not the whole term, unless it makes more
|
||||
sense contextually to use the whole term). Usually, acronyms
|
||||
are defined only one per document. But if you prefer, you can
|
||||
also define them the first time they appear in each
|
||||
(<acronym>NTP</acronym>)</quote>.
|
||||
After the acronym has been defined, use
|
||||
the acronym alone unless it makes more
|
||||
sense contextually to use the whole term. Usually, acronyms
|
||||
are defined only one per document. But they can also be
|
||||
defined the first time they appear in a
|
||||
chapter.</para>
|
||||
|
||||
<para>All acronyms should be enclosed in
|
||||
<sgmltag>acronym</sgmltag> tags, with a
|
||||
<literal>role</literal> attribute with the full term defined.
|
||||
This allows a link to the glossary to be created, and for
|
||||
mouseovers to be rendered with the fully expanded term.</para>
|
||||
<sgmltag>acronym</sgmltag> tags.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
|
@ -338,9 +334,9 @@ V
|
|||
</sect1>
|
||||
</chapter>]]></programlisting>
|
||||
|
||||
<para>If you use <application>Emacs</application> or
|
||||
<application>XEmacs</application> to edit the files then
|
||||
<literal>sgml-mode</literal> should be loaded automatically,
|
||||
<para><application>Emacs</application> or
|
||||
<application>XEmacs</application> should load
|
||||
<literal>sgml-mode</literal> automatically,
|
||||
and the <application>Emacs</application> local variables at
|
||||
the bottom of each file should enforce these styles.</para>
|
||||
|
||||
|
|
Loading…
Reference in a new issue