svn commit: r49829 - head/en_US.ISO8859-1/books/handbook/ports

[Mark Linimon]

Author: linimon
Date: Tue Jan 10 23:08:09 2017
New Revision: 49829
URL: https://svnweb.freebsd.org/changeset/doc/49829

Log:
  Add a short section 4.5.3.1, "Tools To Upgrade And Manage Ports".
  This removes the assertion that only portupgrade or portmaster
  are suitable for upgrading ports, and provides a framework for
  discussing more alternatives as they become available.
  
  Synth is mentioned as an alternative.  A subsequent patch will
  be put up for community discussion.
  
  While here, clean up some duplicate and awkward wording.
  
  This commit expands on the rework done in D8838 and D8839.
  
  Submitted by:	linimon
  Reviewed by:	wblock
  Approved by:	wblock (mentor)

Modified:
  head/en_US.ISO8859-1/books/handbook/ports/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Tue Jan 10 22:55:05 2017	(r49828)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Tue Jan 10 23:08:09 2017	(r49829)
@@ -411,7 +411,8 @@ Info:   Lists information about open fil
 
     <para>However, for those sites building from source or using
       their own repositories, a separate
-      <emphasis>port management tool</emphasis> will be needed.</para>
+      <link linkend="ports-upgrading-tools">port management tool</link>
+      will be needed.</para>
 
     <para>Since <application>pkg</application> only works with
       binary packages, it
@@ -1169,9 +1170,30 @@ The deinstallation will free 229 kB
 	  when performing the upgrade.</para>
       </important>
 
-      <para>To perform the actual upgrade, use either
-	<application>Portmaster</application> or
-	<application>Portupgrade</application>.</para>
+      <sect3 xml:id="ports-upgrading-tools">
+	<title>Tools To Upgrade And Manage Ports</title>
+
+	<indexterm>
+	  <primary>ports</primary>
+	  <secondary>upgrading-tools</secondary>
+	</indexterm>
+
+	<para>The Ports Collection contains several utilities to perform
+	  the actual upgrade.  Each has its strengths and weaknesses.</para>
+
+	<para>Historically, most installations used either
+	  <application>Portmaster</application> or
+	  <application>Portupgrade</application>.
+	  <application>Synth</application> is a newer
+	  alternative.</para>
+
+	<note>
+	  <para>The choice of which tool is best for a particular system
+	    is up to the system administrator.  It is recommended practice
+	    to back up your data before using any of these tools.</para>
+	</note>
+
+      </sect3>
 
       <sect3 xml:id="portmaster">
 	<title>Upgrading Ports Using
@@ -1274,6 +1296,9 @@ The deinstallation will free 229 kB
 	  port in the Ports Collection:</para>
 
 	<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>
+
+	<para>More information about <package>ports-mgmt/portmaster</package>
+	  may be found in its <filename>pkg-descr</filename>.</para>
       </sect3>
 
       <sect3 xml:id="portupgrade">
@@ -1283,10 +1308,9 @@ The deinstallation will free 229 kB
 	  <primary>portupgrade</primary>
 	</indexterm>
 
-	<para>Another utility that can be used to upgrade ports is
-	  <application>Portupgrade</application>, which is available
-	  as the <package>ports-mgmt/portupgrade</package> package
-	  or port.  This utility installs a suite of applications
+	<para><package>ports-mgmt/portupgrade</package> is 
+	  another utility that can be used to upgrade ports.  It
+	  installs a suite of applications
 	  which can be used to manage ports.  However, it is dependent
 	  upon Ruby.  To install the port:</para>
 
@@ -1333,7 +1357,11 @@ The deinstallation will free 229 kB
 	  installing anything, use <option>-F</option>.  For further
 	  information on all of the available switches, refer to the
 	  manual page for <command>portupgrade</command>.</para>
+
+	<para>More information about <package>ports-mgmt/portupgrade</package>
+	  may be found in its <filename>pkg-descr</filename>.</para>
       </sect3>
+
     </sect2>
 
     <sect2 xml:id="ports-disk-space">