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

[John Ferrell]

The following reply was made to PR docs/121838; it has been noted by GNATS.

From: John Ferrell <jdferrell3 at yahoo.com>
To: bug-followup at FreeBSD.org,  jdferrell3 at yahoo.com,  dougb at FreeBSD.org
Cc:  
Subject: Re: docs/121838: [patch] add portmaster(8) section  to ports chapter
 of the handbook
Date: Sat, 22 Mar 2008 22:25:01 -0400

 Doug,
 
 Thanks for reviewing the portmaster section.  I have revised the diff 
 based on your comments.  And thanks for developing a great utility!
 
 John
 
 --- chapter.sgml.orig	2008-03-11 12:46:26.000000000 -0400
 +++ chapter.sgml	2008-03-22 11:48:15.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 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 <replaceable>shells/bash</replaceable></userinput></screen>
 +
 +	<para>Please see &man.portmaster.8; from more information.</para>
 +      </sect3>
      </sect2>
  
      <sect2 id="ports-disk-space">