Update manual pages for better wording, and a better usage display for

pkg_info(1) - from Bug Hunting in PR pkg/47328. The following text is
taken from Bug's PR:

	The pkg_info(1), pkg_admin(1), and pkg_install.conf(5) man pages
	from pkgsrc' pkgtools/pkg_install package contain errors, have
	inaccurate / incomplete / illogically ordered descriptions, have
	incorrect macro usages / macro errors, miss an option description
	(`-h', for pkg_info(1)), and / or contain other imperfections.

	In short: these man pages can use a big correction update.

	Additionally, the `usage' message in main.c from pkg_info(1) contains
	an incorrect option order.

4 files changed, 106 insertions, 73 deletions

diff --git a/pkgtools/pkg_install/files/admin/pkg_admin.1 b/pkgtools/pkg_install/files/admin/pkg_admin.1
index 50d88b1cc6f..6b58ebad409 100644
--- a/pkgtools/pkg_install/files/admin/pkg_admin.1
+++ b/pkgtools/pkg_install/files/admin/pkg_admin.1
@@ -1,4 +1,4 @@
-.\"	$NetBSD: pkg_admin.1,v 1.32 2010/06/16 23:02:48 joerg Exp $
+.\"	$NetBSD: pkg_admin.1,v 1.33 2012/12/17 04:34:02 agc Exp $
 .\"
 .\" Copyright (c) 1999-2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 16, 2010
+.Dd December 14, 2012
 .Dt PKG_ADMIN 1
 .Os
 .Sh NAME
@@ -257,7 +257,9 @@ matches
 .Ar pattern ,
 otherwise returns false.
 .It Cm rebuild
-Rebuild the package database mapping from scratch.
+Rebuild the package database mapping from scratch, using the
+.Pa +CONTENTS
+files of the installed packages.
 This option is only intended for recovery after system crashes
 during package installation and removal.
 .It Cm rebuild-tree
diff --git a/pkgtools/pkg_install/files/info/main.c b/pkgtools/pkg_install/files/info/main.c
index e5c605279b6..82b0e1d158b 100644
--- a/pkgtools/pkg_install/files/info/main.c
+++ b/pkgtools/pkg_install/files/info/main.c
@@ -1,4 +1,4 @@
-/*	$NetBSD: main.c,v 1.30 2010/01/22 13:30:42 joerg Exp $	*/
+/*	$NetBSD: main.c,v 1.31 2012/12/17 04:34:02 agc Exp $	*/
 
 #if HAVE_CONFIG_H
 #include "config.h"
@@ -7,7 +7,7 @@
 #if HAVE_SYS_CDEFS_H
 #include <sys/cdefs.h>
 #endif
-__RCSID("$NetBSD: main.c,v 1.30 2010/01/22 13:30:42 joerg Exp $");
+__RCSID("$NetBSD: main.c,v 1.31 2012/12/17 04:34:02 agc Exp $");
 
 /*
  *
@@ -55,7 +55,7 @@ static void
 usage(void)
 {
 	fprintf(stderr, "%s\n%s\n%s\n%s\n",
-	    "usage: pkg_info [-BbcDdFfhIikLmNnpqrRSsVvX] [-e package] [-E package]",
+	    "usage: pkg_info [-BbcDdFfhIikLmNnpqRrSsVvX] [-E pkg-name] [-e pkg-name]",
 	    "                [-K pkg_dbdir] [-l prefix] pkg-name ...",
 	    "       pkg_info [-a | -u] [flags]",
 	    "       pkg_info [-Q variable] pkg-name ...");
diff --git a/pkgtools/pkg_install/files/info/pkg_info.1 b/pkgtools/pkg_install/files/info/pkg_info.1
index d5f6ef16bd6..16f5fd8cb5e 100644
--- a/pkgtools/pkg_install/files/info/pkg_info.1
+++ b/pkgtools/pkg_install/files/info/pkg_info.1
@@ -1,4 +1,4 @@
-.\" $NetBSD: pkg_info.1,v 1.31 2012/07/06 08:15:57 wiz Exp $
+.\" $NetBSD: pkg_info.1,v 1.32 2012/12/17 04:34:02 agc Exp $
 .\"
 .\" FreeBSD install - a package for the installation and maintenance
 .\" of non-core utilities.
@@ -17,7 +17,7 @@
 .\"
 .\"     @(#)pkg_info.1
 .\"
-.Dd July 6, 2012
+.Dd December 14, 2012
 .Dt PKG_INFO 1
 .Os
 .Sh NAME
@@ -26,8 +26,8 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl BbcDdFfhIikLmNnpqRrSsVvX
-.Op Fl e Ar package
-.Op Fl E Ar package
+.Op Fl E Ar pkg-name
+.Op Fl e Ar pkg-name
 .Op Fl K Ar pkg_dbdir
 .Op Fl l Ar prefix
 .Ar pkg-name ...
@@ -53,16 +53,21 @@ pattern matching several installed packages (see the
 section for a description of possible patterns),
 the pathname to a
 binary package, a filename belonging to an installed
-package (if
-.Fl F
-is also given), or a URL to an ftp-available package.
+package (with
+.Fl F ) ,
+or a URL to an FTP-available package.
 .Pp
-The following command-line options are supported:
+The following command line options are available:
 .Bl -tag -width indent
 .It Fl a
 Show information for all currently installed packages.
 See also
 .Fl u .
+When neither
+.Fl a
+nor
+.Fl u
+is given, the former is assumed.
 .It Fl B
 Show some of the important definitions used when building
 the binary package (the
@@ -78,7 +83,9 @@ as a dependency of another package.
 Show the
 .Nx
 RCS Id strings from the files used in the construction
-of the binary package (the "Build version") for each package.
+of the binary package (the
+.Dq Build version )
+for each package.
 These files are the package Makefile, any patch files, any checksum
 files, and the packing list file.
 .It Fl c
@@ -116,17 +123,21 @@ can contain wildcards (see the
 .Sx PACKAGE WILDCARDS
 section below).
 .It Fl F
-Interpret any pkg-name given as filename, and translate it to a
-package name using the package database.
-This can be used to query information on a per-file basis, e.g. in
-conjunction with the
-.Fl e
-flag to find out which package a file belongs to:
-.Dl pkg_info -Fe /path/to/file
+Interpret any
+.Ar pkg-name
+given as filename, and query information on the package that
+file belongs to.
+This can be used to query information on a per-file basis.
+See the
+.Sx TECHNICAL DETAILS
+section below for more information.
 .It Fl f
 Show the packing list instructions for each package.
+.It Fl h
+Print usage message and exit.
 .It Fl I
 Show the index entry for each package.
+This option is assumed when no arguments or relevant flags are specified.
 .It Fl i
 Show the install script (if any) for each package.
 .It Fl K Ar pkg_dbdir
@@ -142,11 +153,11 @@ This is different from just viewing the packing list, since full pathnames
 for everything are generated.
 Files that were created dynamically during installation of the package
 are not listed.
-.It Fl l Ar str
+.It Fl l Ar prefix
 Prefix each information category header (see
 .Fl q )
 shown with
-.Ar str .
+.Ar prefix .
 This is primarily of use to front-end programs that want to request a
 lot of different information fields at once for a package, but don't
 necessary want the output intermingled in such a way that they can't
@@ -160,7 +171,7 @@ Show which packages each package was built with (exact dependencies), if any.
 Show which packages each package needs (depends upon), if any.
 .It Fl p
 Show the installation prefix for each package.
-.It Fl Q
+.It Fl Q Ar variable
 Show the definition of
 .Ar variable
 from the build information for each package.
@@ -183,8 +194,8 @@ in bytes.
 Show the size of this package in bytes.
 The size is calculated by adding up the size of each file of the package.
 .It Fl u
-Show information for all user-installed packages.
-Automatically installed packages (as dependencies
+Show information for all user-installed packages:
+automatically installed packages (as dependencies
 of other packages) are not displayed.
 See also
 .Fl a .
@@ -206,18 +217,24 @@ command line, or from already installed package information
 in
 .Pa \*[Lt]PKG_DBDIR\*[Gt]/\*[Lt]pkg-name\*[Gt] .
 .Pp
-A filename can be given instead of a (installed) package name to query
-information on the package this file belongs to.
-This filename is then resolved to a package name using the package database.
-For this translation to take place, the
+When the
 .Fl F
-flag must be given.
-The filename must be absolute, compare the output of pkg_info
-.Fl aF .
+option is used,
+a filename can be given instead of a package name to query
+information on the (installed) package that file belongs to.
+The filename is resolved to a package name using the package database.
+The filename must be absolute, as in the output of
+.Dl pkg_info -aF .
+For example,
+.Dl pkg_info -eF /path/to/file
+can be used to display the package the given file belongs to, and
+.Dl pkg_info -LF /path/to/file
+can be used to display all files belonging to the package the given
+file belongs to.
 .Sh PACKAGE WILDCARDS
-In the places where a package name/version is expected, e.g. for the
+In the places where a package name/version is expected, e.g., for the
 .Fl e
-switch, several forms can be used.
+option, several forms can be used.
 Either use a package name with or without version, or specify a
 package wildcard that gets matched against all installed packages.
 .Pp
@@ -228,40 +245,52 @@ In addition,
 style {,} alternates have been implemented.
 Package version numbers can also be matched in a relational manner
 using the
-.Pa \*[Ge] , \*[Le] , \*[Gt] ,
+.Dq \*[Ge] ,
+.Dq \*[Le] ,
+.Dq \*[Gt] ,
 and
-.Pa \*[Lt]
+.Dq \*[Lt]
 operators.
 For example,
-.Pa pkg_info -e 'name\*[Ge]1.3'
+.Dl pkg_info -e 'name\*[Ge]1.3'
 will match versions 1.3 and later of the
-.Pa name
+.Dq name
 package.
-Additionally, ranges can be defined by giving a lower bound with
-\*[Gt] or \*[Ge] and an upper bound with \*[Lt] or \*[Le].
+(Make sure to use shell quoting.)
+Additionally, ranges can be defined, by giving both a lower bound
+.Po with
+.Dq \*[Gt]
+or
+.Dq \*[Ge]
+.Pc
+as well as an upper bound
+.Po with
+.Dq \*[Lt]
+or
+. Dq \*[Le]
+.Pc .
 The lower bound has to come first.
 For example,
-.Pa pkg_info -e 'name\*[Ge]1.3\*[Lt]2.0'
-will match versions 1.3 (inclusive) to 2.0 (exclusive)
-of package
-.Pa name .
+.Dl pkg_info -e 'name\*[Ge]1.3\*[Lt]2.0'
+will match versions 1.3 (inclusive) to 2.0 (exclusive) of package
+.Dq name .
 .Pp
 The collating sequence of the various package version numbers is
 unusual, but strives to be consistent.
 The magic string
 .Dq alpha
 equates to
-.Pa alpha version
+.Dq alpha version ,
 and sorts before a beta version.
 The magic string
 .Dq beta
 equates to
-.Pa beta version
+.Dq beta version ,
 and sorts before a release candidate.
 The magic string
 .Dq rc
 equates to
-.Pa release candidate
+.Dq release candidate ,
 and sorts before a release.
 The magic string
 .Dq pre ,
@@ -270,29 +299,31 @@ short for
 is a synonym for
 .Dq rc .
 For example,
-.Pa name-1.3rc3
-will sort before
-.Pa name-1.3
-and after
-.Pa name-1.2.9 .
-Similarly
-.Pa name-1.3alpha2
+.Dq name-1.3alpha2
 will sort before
-.Pa name-1.3beta1
+.Dq name-1.3beta1 ,
 and they both sort before
-.Pa name-1.3rc1 .
-In addition, alphabetic characters sort in the same place as
-their numeric counterparts, so that
-.Pa name-1.2e
-has the same sorting value as
-.Pa name-1.2.5
+.Dq name-1.3rc1 .
+Similarly,
+.Dq name-1.3rc3
+will sort before
+.Dq name-1.3 ,
+and after
+.Dq name-1.2.9 .
 The magic string
 .Dq pl
-equates to a
-.Pa patch level
-and has the same value as a dot in the dewey-decimal ordering schemes,
+equates to
+.Dq patch level ,
+and has the same value as a dot
+.Pq Sq \&.
+in the dewey-decimal ordering schemes,
 as does the underscore
-.Sq _ .
+.Pq Sq _ .
+Additionally, alphabetic characters sort in the same place as
+their numeric counterparts, so that
+.Dq name-1.2e
+has the same sorting value as
+.Dq name-1.2.5 .
 .Sh ENVIRONMENT
 See
 .Xr pkg_install.conf 5
@@ -314,5 +345,5 @@ refined it for
 .It "Hubert Feyrer"
 .Nx
 wildcard dependency processing, pkgdb, depends displaying,
-pkg size display etc.
+pkg size display, and more.
 .El
diff --git a/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in b/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in
index 5141529a1b5..eac94984dbc 100644
--- a/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in
+++ b/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in
@@ -1,4 +1,4 @@
-.\"	$NetBSD: pkg_install.conf.5.in,v 1.16 2012/02/22 23:56:03 wiz Exp $
+.\"	$NetBSD: pkg_install.conf.5.in,v 1.17 2012/12/17 04:34:02 agc Exp $
 .\"
 .\" Copyright (c) 2008, 2009, 2012 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -107,10 +107,10 @@ The user is always asked to confirm installation of vulnerable packages.
 .El
 .It Dv CONFIG_CACHE_CONNECTIONS
 Limit the global connection cache to this value.
-For FTP this is the number of sessions without active command.
-For HTTP this is the number of connections open with keep-alive.
+For FTP, this is the number of sessions without active command.
+For HTTP, this is the number of connections open with keep-alive.
 .It Dv CONFIG_CACHE_CONNECTIONS_HOST
-Like 
+Like
 .Dv CONFIG_CACHE_CONNECTIONS ,
 but limit the number of connections to the host as well.
 See
@@ -210,7 +210,7 @@ Default location for the file described in this manual page.
 .El
 .Sh SEE ALSO
 .Xr pkg_add 1 ,
-.Xr pkg_admin 1
+.Xr pkg_admin 1 ,
 .Xr pkg_create 1 ,
 .Xr pkg_delete 1 ,
 .Xr pkg_info 1