Increase clarity and reduce redundancy.

svn path=/head/; revision=42063

en_US.ISO8859-1/books/fdp-primer/book.xml

@@ -72,16 +72,16 @@
 
     <abstract>
       <para>Thank you for becoming a part of the FreeBSD Documentation
-	Project.  Your contribution is extremely valuable.</para>
+	Project.  Your contribution is extremely valuable, and we appreciate it.</para>
 
       <para>This primer covers details needed
 	to start contributing to the FreeBSD Documentation
-	Project, from the tools and software (both
+	Project, or <acronym>FDP</acronym>, including tools, software,
-	mandatory and recommended) to the philosophy behind the
+	and the philosophy behind the
 	Documentation Project.</para>
 
-      <para>This document is a work in progress.  Corrections and
+      <para>This is a work in progress.  Corrections and
-	additions are welcomed.</para>
+	additions are always welcome.</para>
     </abstract>
   </bookinfo>
 
@@ -91,10 +91,9 @@
     <sect1 id="preface-prompts">
       <title>Shell Prompts</title>
 
-      <para>The following table shows the default system prompt and
+      <para>This table shows the default system prompt and
-	superuser prompt.  The examples will use this prompt to
+	superuser prompt.  The examples use these prompts to
-	indicate which user you should be running the example
+	indicate which type of user is running the example.</para>
-	as.</para>
 
       <informaltable frame="none" pgwide="1">
 	<tgroup cols="2">
@@ -123,7 +122,7 @@
     <sect1 id="preface-conventions">
       <title>Typographic Conventions</title>
 
-      <para>The following table describes the typographic conventions
+      <para>This table describes the typographic conventions
 	used in this book.</para>
 
       <informaltable frame="none" pgwide="1">
@@ -148,44 +147,44 @@
 	    </row>
 
 	    <row>
-	      <entry>On screen computer output.</entry>
+	      <entry>On-screen computer output.</entry>
 	      <entry><screen>You have mail.</screen></entry>
 	    </row>
 
 	    <row>
-	      <entry>What you type, when contrasted with on-screen
+	      <entry>What the user types, contrasted with on-screen
 		computer output.</entry>
 
-	      <entry><screen>&prompt.user; <userinput>su</userinput>
+	      <entry><screen>&prompt.user; <userinput>date +"The time is %H:%M"</userinput>
-Password:</screen></entry>
+The time is 09:18</screen></entry>
 	    </row>
 
 	    <row>
 	      <entry>Manual page references.</entry>
-	      <entry>Use &man.su.1; to change user names.</entry>
+	      <entry>Use &man.su.1; to change user identity.</entry>
 	    </row>
 
 	    <row>
-	      <entry>User and group names</entry>
+	      <entry>User and group names.</entry>
 	      <entry>Only <username>root</username> can do
 		this.</entry>
 	    </row>
 
 	    <row>
-	      <entry>Emphasis</entry>
+	      <entry>Emphasis.</entry>
-	      <entry>You <emphasis>must</emphasis> do this.</entry>
+	      <entry>The user <emphasis>must</emphasis> do this.</entry>
 	    </row>
 
 	    <row>
-	      <entry>Command line variables; replace with the real
+	      <entry>Text that the user is expected to replace with
-		name or variable.</entry>
+		the actual text.</entry>
-	      <entry>To delete a file, type <command>rm
+	      <entry>To search for a keyword in the manual pages, type <command>man -k
-		  <filename><replaceable>filename</replaceable></filename></command></entry>
+		  <replaceable>keyword</replaceable></command></entry>
 	    </row>
 
 	    <row>
-	      <entry>Environment variables</entry>
+	      <entry>Environment variables.</entry>
-	      <entry><envar>$HOME</envar> is your home
+	      <entry><envar>$HOME</envar> is set to the user's home
 		directory.</entry>
 	    </row>
 	  </tbody>
@@ -197,32 +196,32 @@ Password:</screen></entry>
       <title>Notes, Tips, Important Information, Warnings, and
 	Examples</title>
 
-      <para>Within the text appear notes, warnings, and
+      <para>Notes, warnings, and examples appear within the
-	examples.</para>
+	text.</para>
 
       <note>
 	<para>Notes are represented like this, and contain information
-	  that you should take note of, as it may affect what you
+	  to take note of, as it may affect what the user
-	  do.</para>
+	  does.</para>
       </note>
 
       <tip>
 	<para>Tips are represented like this, and contain information
-	  that you might find useful, or lead to an easier way to do
+	  helpful to the user, like showing an easier way to do
 	  something.</para>
       </tip>
 
       <important>
 	<para>Important information is represented like this.
-	  Typically they flag extra steps you may need to carry
+	  Typically, these show extra steps the user may need to
-	  out.</para>
+	  take.</para>
       </important>
 
       <warning>
 	<para>Warnings are represented like this, and contain
-	  information warning you about possible damage if you do not
+	  information warning about possible damage if the
-	  follow the instructions.  This damage may be physical, to
+	  instructions are not followed.  This damage may be physical, to
-	  your hardware or to you, or it may be non-physical, such as
+	  the hardware or the user, or it may be non-physical, such as
 	  the inadvertent deletion of important files.</para>
       </warning>
 
@@ -230,8 +229,8 @@ Password:</screen></entry>
 	<title>A Sample Example</title>
 
 	<para>Examples are represented like this, and typically
-	  contain examples you should walk through, or show you what
+	  contain examples showing a walkthrough, or
-	  the results of a particular action should be.</para>
+	  the results of a particular action.</para>
       </example>
     </sect1>
 

en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml

@@ -35,21 +35,20 @@
   <title>Overview</title>
 
   <para>Welcome to the &os; Documentation Project
-    (<acronym>FDP</acronym>).  Quality documentation is very important
+    (<acronym>FDP</acronym>).  Quality documentation is crucial
-    to the success of &os;.  Your contributions are very
+    to the success of &os;, and we value your contributions very
-    valuable.</para>
+    highly.</para>
 
-  <para>This document's main purpose is to explain how the
+  <para>This document describes how the
     <acronym>FDP</acronym> is organized, how to write and submit
     documentation, and how to effectively use the available
     tools.</para>
 
   <para>Everyone is welcome to contribute to the
-    <acronym>FDP</acronym>.  There is no membership requirement or
+    <acronym>FDP</acronym>.  Willingness to contribute is the only membership requirement.</para>
-    minimum quota of documentation that needs to be produced.</para>
 
-  <para>After you have finished reading this document you will be
+  <para>This Primer shows the reader how
-    able to:</para>
+    to:</para>
 
   <itemizedlist>
     <listitem>
@@ -58,7 +57,7 @@
     </listitem>
 
     <listitem>
-      <para>Install the required tools and files.</para>
+      <para>Install the required documentation tools and files.</para>
     </listitem>
 
     <listitem>
@@ -124,27 +123,27 @@
       Subversion repository located at
       <literal>https://svn.FreeBSD.org/base/</literal>.</para>
 
-    <para>The commit messages to the <acronym>FDP</acronym>
+    <para>Documentation commit messages
-      are visible to anyone usingv<application>svn</application>.
+      are visible with <application>svn</application>.
-      They are also archived at &a.svn-doc-all.url;.</para>
+      Commit messages are also archived at <ulink url="&a.svn-doc-all.url;"></ulink>.</para>
 
     <para>In addition, many people have written tutorials or how-to
-      articles about &os;.  Some are stored in the
+      articles about &os;.  Some are stored as part of the
-      <acronym>FDP</acronym>.  In other cases, the author has decided
+      <acronym>FDP</acronym> files.  In other cases, the author has decided
-      to keep the documentation separate from the
+      to keep the documentation separate.
-      <acronym>FDP</acronym>.  The <acronym>FDP</acronym> endeavors to
+      The <acronym>FDP</acronym> endeavors to
-      provide links to as much of this documentation as
+      provide links to as much of this external documentation as
       possible.</para>
   </sect1>
 
   <sect1 id="overview-quick-start">
     <title>Quick Start</title>
 
-    <para>This section outlines the steps which new contributors need
+    <para>Here we describe the steps contributors must
-      to follow before they can make changes to the
+      follow before they can make changes to the
       <acronym>FDP</acronym>.  New contributors will interact with
-      other members of the &os; Documentation Team which can assist in
+      other members of the &os; Documentation Team, which can assist in
-      learning how to use <acronym>XML</acronym> and the <xref
+      learning to use <acronym>XML</acronym> and the suggestions in <xref
 	linkend="writing-style-guide"/>.  If a new user contributes
       regularly, a Documentation Team member may be assigned as a
       mentor to guide the user through the process from contributor
@@ -198,10 +197,10 @@
 	</step>
 
 	<step>
-	  <para>Determine which file to edit.  Run
+	  <para>Locate the file to edit.  Run
 	    <command>svn up</command> within the local working copy
-	    to make sure that it is current.  Before making major
+	    to make sure that it is up to date.  Before making major
-	    changes to a file, discuss the proposed changes first with
+	    changes to a file, discuss the proposed changes with
 	    the &a.doc;.</para>
 
 	  <para>When making edits, determine which tags and entities
@@ -210,18 +209,18 @@
 	    <acronym>HTML</acronym> formatted version of the document
 	    to the tags which surround the text or the entities that
 	    represent that text in the <acronym>XML</acronym> file.
-	    A reference to the commonly used tags and entities can be
+	    References to the commonly used tags and entities can be
 	    found in <xref linkend="xhtml-markup"/> and
 	    <xref linkend="docbook-markup"/>.</para>
 	</step>
 
 	<step>
-	  <para>Once the edits are complete, check for problems by
+	  <para>After edits are complete, check for problems by
 	    running:</para>
 
 	  <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
 
-	  <para>While reviewing the output, edit the file to fix the
+	  <para>Review the output and edit the file to fix any
 	    listed tab errors, spelling mistakes, and improper
 	    grammar.  Save the changes and rerun this command to find
 	    any remaining problems.  Repeat until all of the errors
@@ -283,7 +282,7 @@
 	  <para>It is important to remember that the
 	    <acronym>FDP</acronym> is comprised of volunteers who
 	    review edits in their spare time and who live in different
-	    time zones across the globe.  It takes time to review
+	    time zones around the globe.  It takes time to review
 	    edits and to either commit them or respond if additional
 	    edits are required.  If you do not receive a response in a
 	    reasonable amount of time, send a follow-up email to the