svn commit: r42383 - head/en_US.ISO8859-1/books/fdp-primer/overview

[Warren Block]

Author: wblock
Date: Mon Jul 22 21:00:03 2013
New Revision: 42383
URL: http://svnweb.freebsd.org/changeset/doc/42383

Log:
  Simplify the quick start a bit more by referring to later sections.  Use
  ~/doc for the working copy to be consistent with later sections.

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

Modified: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml	Mon Jul 22 20:27:54 2013	(r42382)
+++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml	Mon Jul 22 21:00:03 2013	(r42383)
@@ -163,21 +163,14 @@
 
       <step>
 	<para>Install a local working copy of the documentation
-	  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>
+	  from a mirror of the &os; repository (see <xref linkend="working-copy"/>) in <filename class="directory">~/doc</filename>.</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>The editor to be used should be configured as
-	    follows:</para>
+	  <para>Configure the text editor:</para>
 
 	  <itemizedlist>
 	    <listitem>
@@ -195,22 +188,22 @@
 	  </itemizedlist>
 
 	  <para>
-	    Some specific editor configurations
-	    are listed in <xref linkend="writing-style"/>.</para>
+	    Specific editor configurations
+	    are listed in <xref linkend="editor-config"/>.</para>
 	</step>
 
 	<step>
-	  <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>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 text, tags, and entities in the
-	    <acronym>XML</acronym> file.  References to the commonly
-	    used tags and entities can be found in
+	  <para>Update the local working copy:</para>
+
+	  <screen>&prompt.user; <userinput>svn up ~/doc</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Edit the documentation files that require
+	    changes.  If a file needs major changes, consult the
+	    &a.doc; for input.</para>
+
+	  <para>References to tag and entity usage can be found in
 	    <xref linkend="xhtml-markup"/> and
 	    <xref linkend="docbook-markup"/>.</para>
 	</step>
@@ -230,25 +223,24 @@
 
 	<step>
 	  <para><emphasis>Always</emphasis> build-test changes before
-	    submitting them.  By default, typing
+	    submitting them.  Running
 	    <userinput>make</userinput> in the top-level directory of
-	    the type of documentation being edited will generate that
+	    the documentation being edited will generate that
 	    documentation in split HTML format.  For example, to build
 	    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 edits
-	    do not break the build.</para>
+	    directory.</para>
 	</step>
 
 	<step>
-	  <para>After successfully completing the previous steps,
-	    generate a <quote>diff file</quote> of the changes:</para>
+	  <para>When changes are complete and tested,
+	    generate a <quote>diff file</quote>:</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.
+	  <para>Give the diff file a descriptive name.
 	    In the example above, changes have been made to the
 	    <filename class="directory">bsdinstall</filename> portion
 	    of the Handbook.</para>
@@ -258,24 +250,15 @@
 	  <para>Submit the diff file using the web-based <ulink
 	      url="&url.base;/support.html#gnats">Problem
 	      Report</ulink> system or with &man.send-pr.1;.  If using
-	    the web form, input a synopsis of <emphasis>[patch]
+	    the web form, enter a synopsis of <emphasis>[patch]
 	      <replaceable>short description of
 	      problem</replaceable></emphasis>.  Select the category
 	    <literal>docs</literal> and the class
-	    <literal>doc-bug</literal>.  The body of the message
-	    should contain a short description of the edits and any
-	    important discussion points.  Use the
+	    <literal>doc-bug</literal>.  In the body of the message,
+	    enter a short description of the changes and any
+	    important details about them.  Use the
 	    <guibutton>[ Browse... ]</guibutton> button to
 	    attach the <literal>.diff.txt</literal>.</para>
-
-	  <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 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>
 	</step>
       </procedure>
     </sect1>