Update ports chapter to reflect CVSup deprecation, add svn information.

PR:		docs/172210
Submitted by:	Beat Gaetzi <beat@FreeBSD.org>

1 files changed, 120 insertions, 43 deletions

diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
index 05fe018a4b..b32c7bc8c5 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
@@ -616,24 +616,135 @@ docbook                     =
       system.  The detailed description of available <command>make</command>
       targets and environment variables is available in &man.ports.7;.</para>
 
+    <warning>
+      <para>As of late 2012, the FreeBSD Ports Project is in the
+	process of migrating revision control systems from CVS to
+	Subversion.  As a result, these instructions are in a state of
+	change.  The preferred mechanism for general ports use is
+	<application>Portsnap</application>.  Users requiring local
+	customization of ports (that is, maintaining additional local
+	patches) will probably prefer to use Subversion directly.  The
+	<application>CVSup</application> service is being phased out
+	as of February 28, 2013, and further use is
+	discouraged.</para>
+    </warning>
+
     <sect2 id="ports-tree">
       <title>Obtaining the Ports Collection</title>
 
-      <para>Before you can install ports, you must first obtain the
-	Ports Collection&mdash;which is essentially a set of
+      <para>The Ports Collection is a set of
 	<filename>Makefiles</filename>, patches, and description files
-	placed in <filename>/usr/ports</filename>.
-      </para>
+	stored in <filename>/usr/ports</filename>.  This set of files
+	is used for building and installing applications &os;.  The
+	instructions below show several methods of obtaining the Ports
+	Collection if it was not installed during initial &os;
+	setup.</para>
+
+      <procedure>
+	<title>Portsnap Method</title>
+
+	<para><application>Portsnap</application> is a fast and
+	  user-friendly tool for retrieving the Ports Collection, the
+	  preferred choice for most users.  See
+	  <link linkend="updating-upgrading-portsnap">Using
+	    Portsnap</link> for a detailed description of
+	  <application>Portsnap</application>.</para>
 
-      <para>When installing your FreeBSD system,
-	<application>sysinstall</application> asked if you would like
-	to install the Ports Collection.  If you chose no, you can
-	follow these instructions to obtain the ports
-	collection:</para>
+	<step>
+	  <para>Download a compressed snapshot of the Ports Collection
+	    into <filename
+	      class="directory">/var/db/portsnap</filename>.</para>
+
+	  <screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
+	</step>
+
+	<step>
+	  <para>When running <application>Portsnap</application>
+	    for the first time, extract the snapshot into
+	    <filename class="directory">/usr/ports</filename>:</para>
+
+	  <screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
+
+	  <para>After the first use of
+	    <application>Portsnap</application> has been completed as
+	    shown above,
+	    <filename class="directory">/usr/ports</filename> can be
+	    updated with:</para>
+
+	  <screen>&prompt.root; <userinput>portsnap update</userinput></screen>
+	</step>
+      </procedure>
+
+      <procedure>
+	<title>Subversion Method</title>
+
+	<para>If more control over the ports tree is needed (for
+	  example, for maintaining local changes)
+	  <application>Subversion</application> can be used to
+	  obtain the Ports Collection.  Refer to <ulink
+	    url="&url.articles.committers-guide;/subversion-primer.html">the
+	    Subversion Primer</ulink> for a detailed description of
+	  <application>Subversion</application>.</para>
+
+	<step>
+	  <para><application>Subversion</application> must be
+	    installed before it can be used to check out the ports
+	    tree.  If a copy of the ports tree is already present,
+	    install <application>Subversion</application> like
+	    this:</para>
+
+	  <screen>&prompt.root; <userinput>cd /usr/ports/devel/subversion</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+	  <para>If the ports tree is not available,
+	    <application>Subversion</application> can be installed as
+	    a package:</para>
+
+	  <screen>&prompt.root; <userinput>pkg_add -r subversion</userinput></screen>
+
+	  <para>If <application>pkgng</application> is being used to
+	    manage packages, <application>Subversion</application> can 
+	    be installed with it instead:</para>
+
+	  <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Check out a copy of the ports tree.  Use a specific
+	    <ulink
+	      url="&url.books.handbook;/mirrors-svn.html">Subversion
+	      mirror</ulink> close to your geographic location instead
+	    of <replaceable>svn.FreeBSD.org</replaceable> in the
+	    command below for better performance.  Committers should
+	    read the <ulink
+	      url="&url.articles.committers-guide;/subversion-primer.html">Subversion
+	      Primer</ulink> first to be sure the correct protocol is
+	    chosen.</para>
+
+	  <screen>&prompt.root; <userinput>svn checkout svn://<replaceable>svn.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>
+	</step>
+
+	<step>
+	  <para>To update
+	    <filename class="directory">/usr/ports</filename> after
+	    the initial <application>Subversion</application>
+	    checkout:</para>
+
+	  <screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen>
+	</step>
+      </procedure>
 
       <procedure>
 	<title>CVSup Method</title>
 
+	<warning>
+	  <para>The CVSup method of retrieving and synchronizing the
+	    ports collection is being deprecated as part of a
+	    migration to Subversion.  While it remains supported, the
+	    service will be discontinued as of 28 February
+	    2013.</para>
+	</warning>
+
 	<para>This is a quick method for getting and keeping your copy of the
 	  Ports Collection up to date using <application>CVSup</application>
 	  protocol.  If you want to learn more about
@@ -710,40 +821,6 @@ docbook                     =
       </procedure>
 
       <procedure>
-	<title>Portsnap Method</title>
-
-	<para><application>Portsnap</application> is an alternative system for
-	  distributing the Ports Collection.
-	  Please refer to <link linkend="updating-upgrading-portsnap">Using Portsnap</link>
-	  for a detailed description of all <application>Portsnap</application>
-	  features.</para>
-
-	<step>
-	  <para>Download a compressed snapshot of the Ports Collection into
-	    <filename class="directory">/var/db/portsnap</filename>.  You can
-	    disconnect from the Internet after this step, if you wish.</para>
-
-	  <screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
-	</step>
-
-	<step>
-	  <para>If you are running <application>Portsnap</application> for the
-	    first time, extract the snapshot into <filename
-	    class="directory">/usr/ports</filename>:
-	  </para>
-
-	  <screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
-
-	  <para>If you already have a populated <filename
-	    class="directory">/usr/ports</filename> and you are just updating,
-	    run the following command instead:</para>
-
-	  <screen>&prompt.root; <userinput>portsnap update</userinput></screen>
-	</step>
-
-      </procedure>
-
-      <procedure>
 	<title>Sysinstall Method</title>
 
 	<para>This method involves using <application>sysinstall</application>