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> <title>Tips</title>
<para>Technical documentation can be improved by consistent use of <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>, goals: <emphasis>be clear</emphasis>,
<emphasis>be complete</emphasis>, and <emphasis>be complete</emphasis>, and
<emphasis>be concise</emphasis>. These goals can conflict with <emphasis>be concise</emphasis>. These goals can conflict with
@ -236,20 +236,19 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>Two spaces at the end of sentences</term> <term>Two spaces between sentences</term>
<listitem> <listitem>
<para>Always use two spaces at the end of sentences, as this <para>Always use two spaces between sentences, as this
improves readability, and eases use of tools such as improves readability and eases use of tools such as
<application>Emacs</application>.</para> <application>Emacs</application>.</para>
<para>While it may be argued that a capital letter following <para>A period and spaces followed by a capital letter
a period denotes a new sentence, this is not the case, does not always mark a new sentence,
especially in name usage. especially in names.
<quote>Jordan K. Hubbard</quote> is a good example; it has <quote>Jordan K. Hubbard</quote> is a good example. It has
a capital <literal>H</literal> following a period and a a capital <literal>H</literal> following a period and a
space, and there certainly is not a new sentence space, and is certainly not a new sentence.</para>
there.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
@ -283,21 +282,18 @@
<sect2> <sect2>
<title>Acronyms</title> <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 they appear in a document, as in: <quote>Network Time Protocol
(<acronym role="Network Time Protocol">NTP</acronym>)</quote>. (<acronym>NTP</acronym>)</quote>.
After the acronym has been defined, you should generally use After the acronym has been defined, use
the acronym only (not the whole term, unless it makes more the acronym alone unless it makes more
sense contextually to use the whole term). Usually, acronyms sense contextually to use the whole term. Usually, acronyms
are defined only one per document. But if you prefer, you can are defined only one per document. But they can also be
also define them the first time they appear in each defined the first time they appear in a
chapter.</para> chapter.</para>
<para>All acronyms should be enclosed in <para>All acronyms should be enclosed in
<sgmltag>acronym</sgmltag> tags, with a <sgmltag>acronym</sgmltag> tags.</para>
<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>
</sect2> </sect2>
<sect2> <sect2>
@ -338,9 +334,9 @@ V
</sect1> </sect1>
</chapter>]]></programlisting> </chapter>]]></programlisting>
<para>If you use <application>Emacs</application> or <para><application>Emacs</application> or
<application>XEmacs</application> to edit the files then <application>XEmacs</application> should load
<literal>sgml-mode</literal> should be loaded automatically, <literal>sgml-mode</literal> automatically,
and the <application>Emacs</application> local variables at and the <application>Emacs</application> local variables at
the bottom of each file should enforce these styles.</para> the bottom of each file should enforce these styles.</para>