Simplify and clarify.

Reviewed by:	dru

1 files changed, 56 insertions, 64 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
index 7694d17704..de0635ddcb 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
@@ -47,7 +47,7 @@
     <acronym>FDP</acronym>.  Willingness to contribute is the only
     membership requirement.</para>
 
-  <para>This primer shows the reader how to:</para>
+  <para>This primer shows how to:</para>
 
   <itemizedlist>
     <listitem>
@@ -64,7 +64,7 @@
     </listitem>
 
     <listitem>
-      <para>Submit changes back for review and eventual inclusion in
+      <para>Submit changes back for review and inclusion in
 	the &os; documentation.</para>
     </listitem>
   </itemizedlist>
@@ -110,22 +110,22 @@
 
     <para>Translation teams are responsible for translating the
       Handbook and web site into different languages.  Manual pages
-      are not translated.</para>
+      are not translated at present.</para>
 
     <para>Documentation source for the &os; web site, Handbook, and
-      <acronym>FAQ</acronym> is available in the Subversion
+      <acronym>FAQ</acronym> is available in the documentation
       repository at
       <literal>https://svn.FreeBSD.org/doc/</literal>.</para>
 
     <para>Source for manual pages is available in a separate
-      Subversion repository located at
+      source repository located at
       <literal>https://svn.FreeBSD.org/base/</literal>.</para>
 
     <para>Documentation commit messages are visible with
-      <application>svn</application>.  Commit messages are also
+      <command>svn log</command>.  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
+    <para>Many people have written tutorials or how-to
       articles about &os;.  Some are stored as part of the
       <acronym>FDP</acronym> files.  In other cases, the author has
       decided to keep the documentation separate.  The
@@ -136,8 +136,8 @@
   <sect1 id="overview-quick-start">
     <title>Quick Start</title>
 
-    <para>Here we describe the steps contributors must take before
-      making changes to the <acronym>FDP</acronym>.  New
+    <para>Some preparatory steps must be taken before
+      editing the &os; documentation.  New
       contributors will interact with other members of the &os;
       Documentation Team, which can assist in learning to use
       <acronym>XML</acronym> and the suggestions in
@@ -148,8 +148,8 @@
 
     <procedure>
       <step>
-	<para>Subscribe to the &a.doc;.  Some members of the mailing
-	  list also interact on the <literal>#bsddocs</literal>
+	<para>Subscribe to the &a.doc;.  Some mailing list
+	  members also interact on the <literal>#bsddocs</literal>
 	  <acronym>IRC</acronym> channel on <ulink
 	    url="http://www.efnet.org/">EFnet</ulink>.</para>
       </step>
@@ -158,26 +158,25 @@
 	<para>Install the
 	  <filename role="package">textproc/docproj</filename>
 	  package or port.  This meta-port installs all of the
-	  utilities needed by the <acronym>FDP</acronym>.</para>
+	  software needed to edit and build &os; documentation.</para>
       </step>
 
       <step>
 	<para>Install a local working copy of the documentation
-	  from a mirror of the &os; repository.  For the fastest
-	  download, pick the nearest mirror from the list of <ulink
-	    url="&url.books.handbook;/subversion-mirrors.html">Subversion
-	    mirror sites</ulink>.  If <filename
+	  from a mirror of the &os; repository.  If <filename
 	    class="directory">/usr/doc</filename> already exists, move
 	  or delete it first to prevent file conflicts.</para>
 
 	<screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen>
+
+	<para>For the fastest download, pick the nearest mirror from
+	  the list of <ulink
+	    url="&url.books.handbook;/subversion-mirrors.html">Subversion
+	    mirror sites</ulink>.</para>
 	</step>
 
 	<step>
-	  <para>Before making any documentation edits, configure your
-	    editor to conform to <acronym>FDP</acronym> standards.
-	    How to do so varies by editor.  Some editor configurations
-	    are listed in <xref linkend="writing-style"/>. The editor
+	  <para>The editor to be used
 	    should be configured as follows:</para>
 
 	  <itemizedlist>
@@ -194,38 +193,43 @@
 		single tab.</para>
 	    </listitem>
 	  </itemizedlist>
+
+	  <para>
+	    Some specific editor configurations
+	    are listed in <xref linkend="writing-style"/>.</para>
 	</step>
 
 	<step>
-	  <para>Locate the file to edit.  Run
-	    <command>svn up</command> within the local working copy to
-	    make sure that it is up to date.  Before making major
-	    changes to a file, discuss the proposed changes with the
+	  <para>Run
+	    <command>svn up</command> to update the local working copy.
+	    Edit the documentation files that need changes.
+	    Before making major
+	    changes to a file, ask for input on the
 	    &a.doc;.</para>
 
-	  <para>When making edits, determine which tags and entities
-	    are needed to achieve the desired formatting.  One way to
-	    learn is to compare some text in the
+	  <para>To learn which tags and entities
+	    are needed to achieve the desired formatting,
+	    compare some text in the
 	    <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.
+	    to the text, tags, and entities
+	    in the <acronym>XML</acronym> file.
 	    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>After edits are complete, check for problems by
+	  <para>After editing, check for problems by
 	    running:</para>
 
 	  <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
 
-	  <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 that you deem
-	    fixable are resolved.  If you get stuck trying to fix
-	    errors, ask for assistance on the &a.doc;.</para>
+	  <para>Review the output and edit the file to fix any
+	    problems shown, then
+	    rerun the command to find any remaining
+	    problems.  Repeat until all of the errors that are
+	    fixable are resolved.  If an error seems unsolvable,
+	    ask for assistance on the &a.doc;.</para>
 	</step>
 
 	<step>
@@ -234,34 +238,24 @@
 	    <userinput>make</userinput> in the top-level directory of
 	    the type of documentation being edited will generate that
 	    documentation in split HTML format.  For example, to build
-	    the English version of the Handbook, type
+	    the English version of the Handbook in <acronym>HTML</acronym>, type
 	    <command>make</command> in the
 	    <filename>en_US.ISO8859-1/books/handbook/</filename>
-	    directory.  This step is necessary to make sure that the
+	    directory.  This step is necessary to make sure that
 	    edits do not break the build.</para>
 	</step>
 
 	<step>
-	  <para>In order to build the output in other formats, other
-	    <application>make</application> targets are defined in
-	    <filename>head/share/mk/doc.docbook.mk</filename>.  Use
-	    quotes around the list of formats when building more than
-	    one format with a single command.</para>
-
-	  <para>For example, to convert the document to both
-	    <literal>.html</literal> and <literal>.txt</literal>, use
-	    this command:</para>
-
-	  <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
-
-	  <para>Once these steps are successfully completed, generate
-	    a <quote>diff file</quote> of the changes.  While in
-	    <filename class="directory">/usr/doc</filename>, run this
-	    command, replacing <replaceable>bsdinstall</replaceable>
-	    with the name of the directory containing the
-	    edits:</para>
-
-	  <screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
+	  <para>After successfully completing the previous steps, generate
+	    a <quote>diff file</quote> of the changes:</para>
+
+	  <screen>&prompt.user; <userinput>cd /usr/doc</userinput>
+&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
+
+	  <para>Give the diff file a name that describes the contents.
+	    In the example above, changes have been made to the
+	    <filename class="directory">bsdinstall</filename> portion
+	    of the Handbook.</para>
 	</step>
 
 	<step>
@@ -276,15 +270,13 @@
 	    should contain a short description of the edits and any
 	    important discussion points.  Use the
 	    <guibutton>[&nbsp;Browse...&nbsp;]</guibutton> button to
-	    attach the <literal>.diff.txt</literal> file and enter
-	    the captcha phrase.</para>
+	    attach the <literal>.diff.txt</literal>.</para>
 
-	  <para>It is important to remember that the
+	  <para>Remember that the
 	    <acronym>FDP</acronym> is comprised of volunteers who
 	    review edits in their spare time and who live in different
-	    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
+	    time zones around the globe.  It can take some time to review
+	    changes.  If a response is not received in a
 	    reasonable amount of time, send a follow-up email to the
 	    &a.doc; and ask if anyone has had a chance to review the
 	    patch or if additional information is required.</para>