svn commit: r42368 - head/en_US.ISO8859-1/books/fdp-primer/writing-style

[Warren Block]

Author: wblock
Date: Mon Jul 22 03:57:40 2013
New Revision: 42368
URL: http://svnweb.freebsd.org/changeset/doc/42368

Log:
  Spelling correction.  Explain that two spaces come between sentences, not
  at the beginning or end of a sentence.  Modernize the acronym guidelines.

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml

Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Mon Jul 22 01:45:43 2013	(r42367)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Mon Jul 22 03:57:40 2013	(r42368)
@@ -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>