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

[Josef El-Rayes]

>Number:         55458
>Category:       docs
>Synopsis:       [patch] add useful content & hints to portupgrade section
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Mon Aug 11 03:30:00 PDT 2003
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted: