pkg/47328: pkgsrc' pkgtools/pkg_install package documentation can use update [patch included]

[Bug Hunting <bughunting%xs4all.nl@localhost>]

>Number:         47328
>Category:       pkg
>Synopsis:       pkgsrc' pkgtools/pkg_install package documentation can use 
>update [patch included]
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    pkg-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Dec 14 16:40:01 +0000 2012
>Originator:     Bug Hunting
>Release:        
>Description:

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.

Additionally, even though they _do_ give some information about it
(search for, e.g., the strings ``return'', ``exit'', and ``status''
in them), none of the man pages from the package contain an `EXIT
STATUS' section.  It would be good to add such section in all of
these man pags (be sure to use the `.Ex' macro).  This isn't included
in the patch attached though.



>How-To-Repeat:

"man -s 1 pkg_info pkg_admin"

and

"man -s 5 pkg_install.conf"



>Fix:

Apply the patch attached.  The top lines of the patch provide a
proposed commit message, to which a reference to this PR should be
added though.

Additionally, add `EXIT STATUS' sections to all man pages (not
included in the patch).

Don't forget to regenerate any pre-formatted man page counterparts,
e.g., files files/info/pkg_info.cat, files/admin/pkg_admin.cat,
and files/lib/pkg_install.conf.cat.in for the man pages altered by
the patch.

--BXVAT5kNtrzKuDFl
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="pkg_install.patch"

Many, many documentation (man page) improvements, and one for
pkg_info(1)'s main.c.

Full list of changes:

pkgsrc/pkgtools/pkg_install/files/info/pkg_info.1:
- sort options;
- synchronize / add argument names;
- general punctuation fixes, rewordings, and improvements;
- augment option descriptions;
- correct and improve macro usage;
- add `-h' option description;
- augment description of  `-F', and provide more / better examples of it;
- re-order and improve `PACKAGE WILDCARDS' section;
- capitalization fix;
- bump date. 

pkgsrc/pkgtools/pkg_install/files/info/main.c:
- order option list in `usage' message.

pkgsrc/pkgtools/pkg_install/files/admin/pkg_admin.1:
- augment `rebuild' command description;
- bump date. 

pkgsrc/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in:
- add punctuation;
- remove trailing white space;
- add missing comma in `SEE ALSO' list.

From Bug Hunting.

---

Index: pkgsrc/pkgtools/pkg_install/files/info/pkg_info.1
===================================================================
RCS file: /cvsroot/pkgsrc/pkgtools/pkg_install/files/info/pkg_info.1,v
retrieving revision 1.31
diff -u -r1.31 pkg_info.1
--- pkgsrc/pkgtools/pkg_install/files/info/pkg_info.1   6 Jul 2012 08:15:57 
-0000       1.31
+++ pkgsrc/pkgtools/pkg_install/files/info/pkg_info.1   14 Dec 2012 16:23:28 
-0000
@@ -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 @@
 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 @@
 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 @@
 .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 @@
 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 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 .It "Hubert Feyrer"
 .Nx
 wildcard dependency processing, pkgdb, depends displaying,
-pkg size display etc.
+pkg size display, and more.
 .El
Index: pkgsrc/pkgtools/pkg_install/files/info/main.c
===================================================================
RCS file: /cvsroot/pkgsrc/pkgtools/pkg_install/files/info/main.c,v
retrieving revision 1.30
diff -u -r1.30 main.c
--- pkgsrc/pkgtools/pkg_install/files/info/main.c       22 Jan 2010 13:30:42 
-0000      1.30
+++ pkgsrc/pkgtools/pkg_install/files/info/main.c       14 Dec 2012 16:23:28 
-0000
@@ -55,7 +55,7 @@
 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 ...");
Index: pkgsrc/pkgtools/pkg_install/files/admin/pkg_admin.1
===================================================================
RCS file: /cvsroot/pkgsrc/pkgtools/pkg_install/files/admin/pkg_admin.1,v
retrieving revision 1.32
diff -u -r1.32 pkg_admin.1
--- pkgsrc/pkgtools/pkg_install/files/admin/pkg_admin.1 16 Jun 2010 23:02:48 
-0000      1.32
+++ pkgsrc/pkgtools/pkg_install/files/admin/pkg_admin.1 14 Dec 2012 16:23:28 
-0000
@@ -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 @@
 .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
Index: pkgsrc/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in
===================================================================
RCS file: /cvsroot/pkgsrc/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in,v
retrieving revision 1.16
diff -u -r1.16 pkg_install.conf.5.in
--- pkgsrc/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in 22 Feb 2012 
23:56:03 -0000      1.16
+++ pkgsrc/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in 14 Dec 2012 
16:23:28 -0000
@@ -107,10 +107,10 @@
 .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 @@
 .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

--BXVAT5kNtrzKuDFl--

>Unformatted:
 --BXVAT5kNtrzKuDFl
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline