docs/55458: [patch] add useful content & hints to portupgrade section

[Gary W. Swearingen]

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

From: underway at comcast.net (Gary W. Swearingen)
To: Josef El-Rayes <j.el-rayes at daemon.li>
Cc: FreeBSD-gnats-submit at 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 at 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 ---