From nobody@FreeBSD.org  Tue Mar 18 19:13:21 2008
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 3CC68106567C
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 18 Mar 2008 19:13:21 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 3EE6C8FC2C
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 18 Mar 2008 19:13:21 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.2/8.14.2) with ESMTP id m2IJDKFo078172
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 18 Mar 2008 19:13:20 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.2/8.14.1/Submit) id m2IJDKwR078171;
	Tue, 18 Mar 2008 19:13:20 GMT
	(envelope-from nobody)
Message-Id: <200803181913.m2IJDKwR078171@www.freebsd.org>
Date: Tue, 18 Mar 2008 19:13:20 GMT
From: John Ferrell <jdferrell3@yahoo.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] add portmaster(8) section  to ports chapter of the handbook
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         121838
>Category:       docs
>Synopsis:       [patch] add portmaster(8) section  to ports chapter of the handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    remko
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Mar 18 19:20:01 UTC 2008
>Closed-Date:    Mon Mar 24 18:56:28 UTC 2008
>Last-Modified:  Mon Mar 24 19:00:02 UTC 2008
>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@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:

From: Doug Barton <dougb@FreeBSD.org>
To: John Ferrell <jdferrell3@yahoo.com>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/121838: [patch] add portmaster(8) section to ports chapter
 of	the handbook
Date: Wed, 19 Mar 2008 11:12:52 -0700

 Thank you _very much_ for writing this, it's been on my "list" for a
 long time, and I wasn't going to get to it any time soon. :) I would
 only suggest two very tiny edits. One is to remove the word "yet" in
 the first sentence. The other is to shorten the command line at the
 end, since the -p option is more or less irrelevant with the new
 command line parser from version 2.x. I would say:
 
 <userinput>portmaster <replaceable>shells/bash</replaceable></userinput>
 
 Thanks again!
 
 Doug
 
 -- 
 
     This .signature sanitized for your protection
 

From: John Ferrell <jdferrell3@yahoo.com>
To: bug-followup@FreeBSD.org,  jdferrell3@yahoo.com,  dougb@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">
 
 
Responsible-Changed-From-To: freebsd-doc->remko 
Responsible-Changed-By: remko 
Responsible-Changed-When: Mon Mar 24 10:54:45 UTC 2008 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=121838 
State-Changed-From-To: open->closed 
State-Changed-By: remko 
State-Changed-When: Mon Mar 24 18:56:27 UTC 2008 
State-Changed-Why:  
Committed. Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=121838 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/121838: commit references a PR
Date: Mon, 24 Mar 2008 18:56:19 +0000 (UTC)

 remko       2008-03-24 18:56:12 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/handbook/ports chapter.sgml 
     share/sgml           man-refs.ent 
   Log:
   Add a section about portmaster.
   
   PR:             docs/121838
   Submitted by:   John Ferrel
   
   Revision  Changes    Path
   1.275     +91 -0     doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
   1.454     +1 -0      doc/share/sgml/man-refs.ent
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
