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:
Warren Block 2013-07-22 03:57:40 +00:00
parent fae0d73ebe
commit 58d6e8e361
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42368

View file

@ -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>