Add some details about the usage of portupgrade &

add a man-ent for portupgrade.

Approved by:    simon(mentor)
Submitted by:   josef
PR:             docs/55458

en_US.ISO8859-1/books/handbook/ports/chapter.sgml

@@ -1096,9 +1096,35 @@ Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
 	directory.  Now when you run <command>portupgrade
 	-a</command>, it will read this and the ports
 	<filename>INDEX</filename> file.  Finally,
-	<command>portupgrade</command> will begin to download, build,
+	<application>portupgrade</application> 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 <option>-r</option> if
+	<application>portupgrade</application> should act on all
+	those packages depending on the given package as well, and
+	<option>-R</option> to act on all packages required by
+	the given packages.
+	To use packages instead of ports for installation, provide
+	<option>-P</option> and to just fetch distfiles without
+	building or installing anything, use <option>-F</option>.
+	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 an 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>

share/sgml/man-refs.ent

@@ -477,6 +477,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//">