Clarify the Using SVN section. Change the example mirror used, modify

the checkout example to point to the SVN mirrors section.  Modify
terms to be more consistent.

Reviewed by:	simon (earlier version), pgj

en_US.ISO8859-1/books/handbook/mirrors/chapter.xml

@@ -596,7 +596,9 @@
       <title>Running <application>Subversion</application></title>
 
       <para>The <command>svn</command> command is used to fetch a
-	clean copy of the sources into a local directory.</para>
+	clean copy of the sources into a local directory.  The files
+	in this directory are called a <emphasis>local working
+	copy</emphasis>.</para>
       <warning>
 	<para>If the local directory already exists but was not
 	  created by <command>svn</command>, rename or delete it
@@ -606,13 +608,20 @@
 	  repository.</para>
       </warning>
 
-      <para>Check out from a given repository by typing:</para>
+      <para>A checkout from a given repository is performed with a
+	command like this:</para>
 
-      <screen>&prompt.root; <userinput>svn checkout <literal>svn://svn.FreeBSD.org/<replaceable>repository</replaceable>/<replaceable>branch</replaceable></literal> <replaceable>root</replaceable></userinput></screen>
+      <screen>&prompt.root; <userinput>svn checkout <replaceable>svn-mirror</replaceable>/<replaceable>repository</replaceable>/<replaceable>branch</replaceable> <replaceable>lwcdir</replaceable></userinput></screen>
 
       <para>where:</para>
 
       <itemizedlist>
+	<listitem>
+	  <para><replaceable>svn-mirror</replaceable> is a URL for one
+	    of the <link linkend="svn-mirrors">Subversion mirror
+	    sites</link>.</para>
+	</listitem>
+
 	<listitem>
 	  <para><replaceable>repository</replaceable> is one of the
 	    Project repositories, i.e., <literal>base</literal>,
@@ -634,7 +643,7 @@
 	</listitem>
 
 	<listitem>
-	  <para><replaceable>root</replaceable> is the target directory
+	  <para><replaceable>lwcdir</replaceable> is the target directory
 	    where the contents of the specified branch should be placed.
 	    This is usually <filename
 	    class="directory">/usr/ports</filename> for
@@ -646,21 +655,45 @@
 	</listitem>
       </itemizedlist>
 
-      <para>Note that the initial download of the sources may take a
+      <para>This example checks out the Ports Collection from the
-	while.  Let it run until it completes.</para>
+	western US repository using the HTTPS protocol, placing the
+	local working copy in
+	<filename class="directory">/usr/ports</filename>.  If
+	<filename class="directory">/usr/ports</filename> is already
+	present but was not created by <command>svn</command>,
+	remember to rename or delete it before the checkout.</para>
 
-      <para>Future updates of the downloaded sources may be fetched by
+      <screen>&prompt.root; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/head/ports /usr/ports</userinput></screen>
-	running:</para>
 
-      <screen>&prompt.root; <userinput>svn update <replaceable>root</replaceable></userinput></screen>
+      <para>Because the initial checkout has to download the full
+	branch of the remote repository, it can take a while.  Please
+	be patient.</para>
 
-      <para>After checking out the sources, an alternative way of
+      <para>After the initial checkout, the local working copy can be
-	updating the documentation is supported by the
+	updated by running:</para>
-	<filename>Makefile</filename> of the <filename
-	class="directory"><replaceable>root</replaceable></filename>
-	directory by running:</para>
 
-      <screen>&prompt.root; <userinput>cd <replaceable>root</replaceable></userinput>
+      <screen>&prompt.root; <userinput>svn update <replaceable>lwcdir</replaceable></userinput></screen>
+
+      <para>To update
+	<filename class="directory">/usr/ports</filename> created in
+	the example above, use:</para>
+
+      <screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
+
+      <para>The update is much quicker than a checkout, only
+	transferring files that have changed.</para>
+
+      <para>An alternate way of
+	updating the local working copy after checkout is provided by the
+	<filename>Makefile</filename> in the <filename
+	class="directory">/usr/ports</filename>,
+	<filename class="directory">/usr/src</filename>, and
+	<filename class="directory">/usr/doc</filename> directories.
+	Set <makevar>SVN_UPDATE</makevar> and use the
+	<maketarget>update</maketarget> target.  For example, to
+	update <filename class="directory">/usr/src</filename>:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make update SVN_UPDATE=yes</userinput></screen>
     </sect2>