This patch:

- clarifies that this is an alternative to pkgng

- updates the listing version numbers and removes the example for manually fetching a pkg

- removes .tgz format

- does some word-smithing to make what is demonstrated clearer and to refer the reader to man pages for further usage examples

- comments out the author info so that it doesn't render in the print version

Approved by:  gjb (mentor)

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

@@ -341,33 +341,40 @@ Info:   Lists information about open files (similar to fstat(1))</screen>
     </itemizedlist>
   </sect1>
 
+
   <sect1 id="packages-using">
     <sect1info>
-      <authorgroup>
+      <!--<authorgroup>
 	<author>
 	  <firstname>Chern</firstname>
 	  <surname>Lee</surname>
 	  <contrib>Contributed by </contrib>
 	</author>
-      </authorgroup>
+      </authorgroup>-->
-    <!-- 30 Mar 2001 -->
     </sect1info>
 
     <title>Using Binary Packages</title>
 
     <para>At the present time, &os; is transitioning toward a new
-      method of package management.  Users of the latest releases
+      method of package management.  Users
       may wish to investigate the benefits of using
-      <link linkend="pkgng-intro">PKGng</link> to manage third
+      <link linkend="pkgng-intro">PKGng</link> to manage third-party
-      party software on &os;.  For those not yet migrated to the
+      software on &os;.  This section describes the traditional method
-      <application>pkgng</application> tool, the tools discussed
+      for managing binary packages and only applies to those users who have not yet migrated to the
-      here may be used for managing the package database.  For
+      <application>pkgng</application> format.</para>
-      simplicity, the <command>sysinstall</command> utility is
-      also available post-install for package management.</para>
 
-    <para>All package installation files are stored in the
+    <para>This method of package management uses a
       package database directory,
-      <filename class="directory">/var/db/pkg</filename>.</para>
+      <filename class="directory">/var/db/pkg</filename>, to track
+      installed software versions and the files installed with each
+      application.  Several utilities interact with the database
+      directory and are used to manage binary packages.  These
+      commands begin with <literal>pkg_</literal>.  This section
+      provides an overview of the commands which are used to install,
+      delete, and gather information about binary packages.  Each
+      command provides many switches to customize its operation.
+      Refer to the listed man pages for more details and further usage
+      examples.</para>
 
     <sect2>
       <title>Installing a Package</title>
@@ -380,43 +387,16 @@ Info:   Lists information about open files (similar to fstat(1))</screen>
       <indexterm>
 	<primary><command>pkg_add</command></primary>
       </indexterm>
-      <para>Use &man.pkg.add.1; to install a &os; binary package from
+      <para>To install a binary package from
-	a local file or from a server on the network.</para>
+	a local &os; media or a remote &os; package server, use &man.pkg.add.1;.
-
+	While a &os; media can provide a source of local packages
-      <example>
+	without requiring a network connection, it may not contain
-	<title>Downloading a Package Manually and Installing It
+	the latest versions of binary packages as new versions are
-	  Locally</title>
+	always being rebuilt for the &os; package servers.  To install
-
+	from a package server, always include <option>-r</option> (for remote) with
-        <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput>
-Connected to ftp2.FreeBSD.org.
-220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
-331 Guest login ok, send your email address as password.
-230-
-230-     This machine is in Vienna, VA, USA, hosted by Verio.
-230-         Questions? E-mail freebsd@vienna.verio.net.
-230-
-230-
-230 Guest login ok, access restrictions apply.
-Remote system type is UNIX.
-Using binary mode to transfer files.
-<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput>
-250 CWD command successful.
-<prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput>
-local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
-200 PORT command successful.
-150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
-100% |**************************************************| 92375       00:00 ETA
-226 Transfer complete.
-92375 bytes received in 5.60 seconds (16.11 KB/s)
-<prompt>ftp></prompt> <userinput>exit</userinput>
-&prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen>
-      </example>
-
-      <para>If you do not have a source of local packages, such as a
-	&os; CD-ROM set, include <option>-r</option> with
 	&man.pkg.add.1;.  This automatically determines the correct
 	object format and release, and then fetches and installs the
-	package from an FTP site without any further user
+	package from a package server without any further user
 	intervention.</para>
 
       <indexterm>
@@ -424,18 +404,16 @@ local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
       </indexterm>
       <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
 
-      <para>To specify an alternative &os; FTP mirror, specify the
+      <para>In this example, <literal>lsof</literal> is used without
+	specifying a version number as the version is not included  when the remote
+	fetching feature is used.  To specify an alternative &os; FTP mirror, specify the
 	mirror in the <envar>PACKAGESITE</envar> environment variable.
 	&man.pkg.add.1; uses &man.fetch.3; to download files, which
 	uses various environment variables, including
 	<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
 	<envar>FTP_PASSWORD</envar>.  You may need to set one or more
 	of these if you are behind a firewall, or need to use an
-	FTP/HTTP proxy.  See &man.fetch.3; for the complete list of variables.
+	FTP/HTTP proxy.  See &man.fetch.3; for the complete list of FTP-related variables.</para>
-	Note that in the example above <literal>lsof</literal> is used
-	instead of <literal>lsof-4.56.4</literal>.  When the remote
-	fetching feature is used, the version number of the package
-	must be removed.</para>
 
       <note>
 	<para>&man.pkg.add.1; will automatically download the latest
@@ -444,23 +422,23 @@ local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
 	  installs the version of the package that was built with that
 	  release.  It is possible to change this behavior by
 	  overriding <envar>PACKAGESITE</envar>.  For example, on a
-	  &os;&nbsp;8.1-RELEASE system, by default &man.pkg.add.1;
+	  &os;&nbsp;9.1-RELEASE system, by default &man.pkg.add.1;
 	  will try to fetch packages from
-	  <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>.
+	  <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-9.1-release/Latest/</literal>.
-	  To force &man.pkg.add.1; to download &os;&nbsp;8-STABLE
+	  To force &man.pkg.add.1; to download &os;&nbsp;9-STABLE
 	  packages, set <envar>PACKAGESITE</envar> to
-	  <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>.</para>
+	  <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-9-stable/Latest/</literal>.</para>
       </note>
 
-      <para>Package files are distributed in <filename>.tgz</filename>
+      <para>Package files are distributed in the
-	and <filename>.tbz</filename> formats.  Packages are
+	<filename>.tbz</filename> format.  Packages are
 	available from <ulink
-	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
+	url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>
 	or the <filename>/packages</filename> directory of the &os;
 	DVD distribution.  The layout of the packages directory is similar to
-	that of the <filename>/usr/ports</filename> tree.  Each
+	that of the <filename class="directory">/usr/ports</filename> tree.  Each
 	category has its own directory, and every package can be found
-	within the <filename>All</filename> directory.</para>
+	within the <filename class="directory">All</filename> directory.</para>
     </sect2>
 
     <sect2>
@@ -471,21 +449,21 @@ local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
 	<secondary>managing</secondary>
       </indexterm>
 
-      <para>&man.pkg.info.1; can be used to list and describe
+      <para>To list and describe
-	installed packages:</para>
+	installed packages, use &man.pkg.info.1;:</para>
 
       <indexterm>
 	<primary><command>pkg_info</command></primary>
       </indexterm>
 
       <screen>&prompt.root; <userinput>pkg_info</userinput>
-colordiff-1.0.13    A tool to colorize diff output
+colordiff-1.0.13    Tool to colorize diff output
-docbook-1.2         Meta-port for the different versions of the DocBook DTD
+docbook-1.4         Meta-port for the different versions of the DocBook DTD
 ...</screen>
 
-      <para>&man.pkg.version.1; summarizes the versions of all
+      <para>To receive a summary of the versions of all
-	installed packages and compares the package version to the
+	installed packages and a comparison of the installed package versions to the
-	current version found in the ports tree.</para>
+	current versions found in the locally installed ports tree, use &man.pkg.version.1;:</para>
 
       <indexterm>
 	<primary><command>pkg_version</command></primary>
@@ -546,7 +524,7 @@ docbook                     =
 	      <entry>!</entry>
 
 	      <entry>The installed package exists in the index but for
-		some reason, <command>pkg_version</command> was unable
+		some reason <command>pkg_version</command> was unable
 		to compare the version number of the installed package
 		with the corresponding entry in the index.</entry>
 	    </row>
@@ -570,12 +548,12 @@ docbook                     =
       <para>To remove a previously installed software package, use
 	&man.pkg.delete.1;:</para>
 
-      <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
+      <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-2.8.8_1</replaceable></userinput></screen>
 
       <para>Note that &man.pkg.delete.1; requires the full package
-	name and number; the above command would not work if
+	name and number and that the above command would not work if
 	<replaceable>xchat</replaceable> was given instead of
-	<replaceable>xchat-1.7.1</replaceable>.  Use
+	<replaceable>xchat-2.8.8_1</replaceable>.  Use
 	&man.pkg.version.1; to find the version of the
 	installed package, or use a wildcard:</para>