docs/121838: [patch] add portmaster(8) section to ports chapter of the handbook

[John Ferrell]

>Number:         121838
>Category:       docs
>Synopsis:       [patch] add portmaster(8) section  to ports chapter of the handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Mar 18 19:20:01 UTC 2008
>Closed-Date:
>Last-Modified:
>Originator:     John Ferrell
>Release:        7.0
>Organization:
>Environment:
FreeBSD fbsd.local 7.0-RELEASE FreeBSD 7.0-RELEASE #0: Mon Mar 10 18:30:02 EDT 2008     root at fbsd.local:/usr/obj/usr/src/sys/JDF  i386

>Description:
Patch to add a section on portmaster(8) to the ports chapter of the handbook.  

Note:  I submitted a patch, 'docs/121648: [patch] add portmaster(8) to man-refs.ent', that this patch relies on.
>How-To-Repeat:

>Fix:
--- chapter.sgml.orig	2008-03-11 12:46:26.000000000 -0400
+++ chapter.sgml	2008-03-18 14:07:22.000000000 -0400
@@ -1293,6 +1293,97 @@
 
 	<para>For further information see &man.portmanager.1;.</para>
       </sect3>
+
+      <sect3 id="portmaster">
+	<title>Upgrading Ports using Portmaster</title>
+
+	<indexterm>
+	  <primary>portmaster</primary>
+	</indexterm>
+
+	<para><application>Portmaster</application> is yet another utility for
+	  upgrading installed ports.  <application>Portmaster</application> 
+          was designed make use of the tools found in the <quote>base</quote> 
+          system (it does not depend upon any other ports) and uses the 
+          information in <filename class="directory">/var/db/pkg/</filename> 
+          to determine which ports to upgrade.  It is available from the
+	  <filename role="package">ports-mgmt/portmaster</filename> port:</para>
+
+	<screen>&prompt.root; <userinput>cd <filename role="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+        <para><application>Portmaster</application> groups ports into four 
+          categories:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>Root ports (no dependencies, not depended on)</para>
+            </listitem>
+          <listitem>
+            <para>Trunk ports (no dependencies, are depended on)</para>
+            </listitem>
+          <listitem>
+            <para>Branch ports (have dependencies, are depended on)</para>
+            </listitem>
+          <listitem>
+            <para>Leaf ports (have dependencies, not depended on)</para>
+            </listitem>
+        </itemizedlist>
+
+        <para>You can list all the installed ports and search 
+          for updates using the <option>-L</option> option:</para>
+
+<screen>&prompt.root; <userinput>portmaster -L</userinput>
+===>>> Root ports (No dependencies, not depended on)
+===>>> ispell-3.2.06_18
+===>>> screen-4.0.3
+        ===>>> New version available: screen-4.0.3_1
+===>>> tcpflow-0.21_1
+===>>> 7 root ports
+...
+===>>> Branch ports (Have dependencies, are depended on)
+===>>> apache-2.2.3
+        ===>>> New version available: apache-2.2.8
+...
+===>>> Leaf ports (Have dependencies, not depended on)
+===>>> automake-1.9.6_2
+===>>> bash-3.1.17
+        ===>>> New version available: bash-3.2.33
+...
+===>>> 32 leaf ports
+
+===>>> 137 total installed ports
+        ===>>> 83 have new versions available
+</screen>
+
+	<para>All the installed ports can be upgraded using this simple
+	  command:</para>
+
+	<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>
+
+	<note><para>By default, <application>Portmaster</application>
+          will make a backup package before deleting the existing port.  If 
+          the installation of the new version is successful, 
+          <application>Portmaster</application> will delete the backup.  
+          Using the <option>-b</option> will instruct 
+          <application>Portmaster</application> not to automatically delete 
+         the backup.  Also, adding the <option>-i</option> option will start 
+          <application>Portmaster</application> in interactive mode, prompting 
+          you before upgrading each port.</para></note>
+
+        <para>If you encounter errors during the upgrade process, you can use 
+          the <option>-f</option> option to upgrade/rebuild all ports:</para>
+
+	<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
+
+        <para>You can also use <application>Portmaster</application> to 
+          install new ports on the system, upgrading all dependencies 
+          before building and installing the new port:</para>
+
+	<screen>&prompt.root; <userinput>portmaster -p <replaceable>/usr/ports/shells/bash</replaceable></userinput></screen>
+
+	<para>Please see &man.portmaster.8; from more information.</para>
+      </sect3>
     </sect2>
 
     <sect2 id="ports-disk-space">


>Release-Note:
>Audit-Trail:
>Unformatted: