From shammer@satanii.enemy.org  Mon Aug 11 03:28:52 2003
Return-Path: <shammer@satanii.enemy.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 852B537B401
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 11 Aug 2003 03:28:52 -0700 (PDT)
Received: from lyra.enemy.org (lyra.enemy.org [62.116.11.42])
	by mx1.FreeBSD.org (Postfix) with SMTP id 07EB543F85
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 11 Aug 2003 03:28:51 -0700 (PDT)
	(envelope-from shammer@satanii.enemy.org)
Received: (qmail 6811 invoked from network); 11 Aug 2003 10:27:55 -0000
Received: from unknown (HELO satanii.enemy.org) (62.116.11.3)
  by lyra.enemy.org with SMTP; 11 Aug 2003 10:27:55 -0000
Received: from satanii.enemy.org (shammer@localhost [IPv6:::1])
	by satanii.enemy.org (8.12.6p2/8.12.6) with ESMTP id h7BASo52037108
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 11 Aug 2003 12:28:50 +0200 (CEST)
	(envelope-from shammer@satanii.enemy.org)
Received: (from shammer@localhost)
	by satanii.enemy.org (8.12.6p2/8.12.6/Submit) id h7BASnCK037107;
	Mon, 11 Aug 2003 12:28:49 +0200 (CEST)
Message-Id: <200308111028.h7BASnCK037107@satanii.enemy.org>
Date: Mon, 11 Aug 2003 12:28:49 +0200 (CEST)
From: Josef El-Rayes <j.el-rayes@daemon.li>
Reply-To: Josef El-Rayes <j.el-rayes@daemon.li>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] add useful content & hints to portupgrade section
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         55458
>Category:       docs
>Synopsis:       [patch] add useful content & hints to portupgrade section
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    josef
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Mon Aug 11 03:30:00 PDT 2003
>Closed-Date:    Sun Jan 18 14:21:43 PST 2004
>Last-Modified:  Sun Jan 18 14:21:43 PST 2004
>Originator:     Josef El-Rayes
>Release:        FreeBSD 4.7-RELEASE alpha
>Organization:
>Environment:
System: FreeBSD satanii.enemy.org 4.7-RELEASE FreeBSD 4.7-RELEASE #3: Sun Oct 13 23:53:31 CEST 2002 root@satanii.enemy.org:/usr/src/sys/compile/S2 alpha


	
>Description:
		doc/en_US.ISO8859-1/books/handbook/ports/chapter.sgml:
		this patch adds some explanation on how to use portupgrade
		and gives some important hints to avoid inconsistencies.
		portupgrade(1) gets added to man-references
	
>How-To-Repeat:
	
>Fix:

	

--- chapter.sgml.diff begins here ---
--- chapter.sgml.orig	Sun Aug 10 20:47:29 2003
+++ chapter.sgml	Sun Aug 10 22:54:35 2003
@@ -1094,7 +1094,26 @@
 	<filename>INDEX</filename> file.  Finally,
 	<command>portupgrade</command> will begin to download, build,
 	backup, install, and clean the ports which have been updated.
-	Other utilities exist which will do this, check out the
+	<application>portupgrade</application> comes with a lot of options for different
+	use cases, the most important ones will be presented below:</para>
+
+	<para>If you want to upgrade only a certain application, not the complete database,
+	use <command>portupgrade <replaceable>pkgname</replaceable></command>, 
+	include the flags <parameter>-r</parameter>
+	if <application>portupgrade</application> should act on all those packages 
+	depending on the given package as well, and <parameter>-R</parameter> to act on
+	all packages required by the given packages as well.
+	To use packages instead of ports for installation, provide <parameter>-P</parameter>
+	and to just fetch distfiles without building or installing anything, use
+	<parameter>-F</parameter>. For further information see &man.portupgrade.1;</para>
+	
+      <note><para>It is important to regularly update the package database using
+      <command>pkgdb -F</command> to fix inconsistencies, especially when 
+      <application>portupgrade</application> asks you to. Do not abort
+      <application>portupgrade</application> while it is updating the package database,
+      this will leave you a inconsistent database.</para></note>
+	
+      <para>Other utilities exist which will do this, check out the
 	<filename>ports/sysutils</filename> directory and see what you
 	come up with.</para>
     </sect2>
--- chapter.sgml.diff ends here ---

--- man-refs.ent.diff begins here ---
--- man-refs.ent.orig	Fri Aug  8 17:57:30 2003
+++ man-refs.ent	Sun Aug 10 22:58:01 2003
@@ -476,6 +476,7 @@
 <!ENTITY man.pod2man.1 "<citerefentry/<refentrytitle/pod2man/<manvolnum/1//">
 <!ENTITY man.popd.1 "<citerefentry/<refentrytitle/popd/<manvolnum/1//">
 <!ENTITY man.portlint.1 "<citerefentry vendor='ports'/<refentrytitle/portlint/<manvolnum/1//">
+<!ENTITY man.portupgrade.1 "<citerefentry vendor='ports'/<refentrytitle/portupgrade/<manvolnum/1//">
 <!ENTITY man.pr.1 "<citerefentry/<refentrytitle/pr/<manvolnum/1//">
 <!ENTITY man.printenv.1 "<citerefentry/<refentrytitle/printenv/<manvolnum/1//">
 <!ENTITY man.printf.1 "<citerefentry/<refentrytitle/printf/<manvolnum/1//">
--- man-refs.ent.diff ends here ---


>Release-Note:
>Audit-Trail:

From: underway@comcast.net (Gary W. Swearingen)
To: Josef El-Rayes <j.el-rayes@daemon.li>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/55458: [patch] add useful content & hints to portupgrade
 section
Date: Mon, 11 Aug 2003 09:50:51 -0700

 Just some kibitzing here.  If it's not welcome, let me know so I can
 better decide how to entertain myself.
 
 Josef El-Rayes <j.el-rayes@daemon.li> writes:
 
 > --- chapter.sgml.diff begins here ---
 > --- chapter.sgml.orig	Sun Aug 10 20:47:29 2003
 > +++ chapter.sgml	Sun Aug 10 22:54:35 2003
 > @@ -1094,7 +1094,26 @@
 >  	<filename>INDEX</filename> file.  Finally,
 
   	<filename>INDEX</filename> file and then
 
 >  	<command>portupgrade</command> will begin to download, build,
 
   	download, build,
 
         COMMENT: If using "portupgrade" there, it looks more like an
         <application>, if I understand the fine distinction.
 
 >  	backup, install, and clean the ports which have been updated.
 > -	Other utilities exist which will do this, check out the
 > +	<application>portupgrade</application> comes with a lot of options for different
 
         The utility comes with many options for different
 
 > +	use cases, the most important ones will be presented below:</para>
 
 	uses.  Two important ones follow.</para>
 > +
 > +	<para>If you want to upgrade only a certain application, not the complete database,
 
 	<para>To upgrade only one package, and not the complete database,
 
         OR:
 
 	<para>To upgrade only one package,
 
 > +	use <command>portupgrade <replaceable>pkgname</replaceable></command>, 
 
 	use <command>portupgrade <replaceable>pkgname</replaceable></command>.
 
 > +	include the flags <parameter>-r</parameter>
 
 	Include the flag <parameter>-r</parameter>
 
 > +	if <application>portupgrade</application> should act on all those packages 
 
 	to also act on the packages 
 
 > +	depending on the given package as well, and <parameter>-R</parameter> to act on
 
 	that depend on the given package, and include <parameter>-R</parameter> to also act on
 
 > +	all packages required by the given packages as well.
 
 	the packages that are required by the given package.
 
 > +	To use packages instead of ports for installation, provide <parameter>-P</parameter>
 
 	<para>To use packages instead of ports for installation, include <parameter>-P</parameter>.
 
 > +	and to just fetch distfiles without building or installing anything, use
 
 	To only fetch the distfiles, without building or installing anything, include
 
         COMMENT: I'm guessing that "distfiles" should have some markup
         like <freebsd-jargon>, but I don't know.
 
 > +	<parameter>-F</parameter>. For further information see &man.portupgrade.1;</para>
 > +	
 > +      <note><para>It is important to regularly update the package database using
 
          COMMENT: If it's really important, then "regularly" should be
          defined.  I doubt if anyone can do so.  It would be better,
          IMO, to leave the advice out until complaints get the software
          fixed.  We probably cannot remove the fuzzy advice from the
          utility's manpage, but we needn't propagate it in the FDP.
 
 > +      <command>pkgdb -F</command> to fix inconsistencies, especially when 
 > +      <application>portupgrade</application> asks you to. Do not abort
 
          COMMENT: That advice is OK, of course.
 
 > +      <application>portupgrade</application> while it is updating the package database,
 
        <application>portupgrade</application> while it is updating the package database;
 
 > +      this will leave you a inconsistent database.</para></note>
 
        this will leave you a inconsistent database.</para></note>
 > +	
 > +      <para>Other utilities exist which will do this, check out the
 
       <para>There are more package and ports utilities; check out the
 
 >  	<filename>ports/sysutils</filename> directory and see what you
 
   	<filename>ports/sysutils</filename> directory. </para>
 
 >      </sect2>
 > --- chapter.sgml.diff ends here ---
Responsible-Changed-From-To: freebsd-doc->josef 
Responsible-Changed-By: josef 
Responsible-Changed-When: Thu Jan 15 14:13:03 PST 2004 
Responsible-Changed-Why:  
I'll take this one, as I am the originator. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=55458 
State-Changed-From-To: open->closed 
State-Changed-By: josef 
State-Changed-When: Sun Jan 18 14:21:28 PST 2004 
State-Changed-Why:  
Committed, thanks josef! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=55458 
>Unformatted:
