NetBSD Problem Report #47328

From bughunting@xs4all.nl  Fri Dec 14 16:36:26 2012
Return-Path: <bughunting@xs4all.nl>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	by www.NetBSD.org (Postfix) with ESMTP id 2AD5F63EB69
	for <gnats-bugs@gnats.NetBSD.org>; Fri, 14 Dec 2012 16:36:26 +0000 (UTC)
Message-Id: <20121214163655.GA5847@frohike.homeunix.org>
Date: Fri, 14 Dec 2012 17:36:55 +0100
From: Bug Hunting <bughunting@xs4all.nl>
To: NetBSD GNATS <gnats-bugs@gnats.NetBSD.org>
Subject: pkgsrc' pkgtools/pkg_install package documentation can use update
 [patch included]
X-Send-Pr-Version: 3.95

>Number:         47328
>Category:       pkg
>Synopsis:       pkgsrc' pkgtools/pkg_install package documentation can use update [patch included]
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    agc
>State:          closed
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Dec 14 16:40:01 +0000 2012
>Closed-Date:    Mon Dec 17 04:34:41 +0000 2012
>Last-Modified:  Mon Dec 17 04:35:02 +0000 2012
>Originator:     Bug Hunting
>Release:        
>Organization:

>Environment:

>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--

>Release-Note:

>Audit-Trail:

Responsible-Changed-From-To: pkg-manager->agc
Responsible-Changed-By: hauke@NetBSD.org
Responsible-Changed-When: Sun, 16 Dec 2012 19:54:40 +0000
Responsible-Changed-Why:
Over to maintainer.


State-Changed-From-To: open->closed
State-Changed-By: agc@NetBSD.org
State-Changed-When: Mon, 17 Dec 2012 04:34:41 +0000
State-Changed-Why:
agc applied the changes provided in the PR

Thanks!


From: "Alistair G. Crooks" <agc@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/47328 CVS commit: pkgsrc/pkgtools/pkg_install/files
Date: Mon, 17 Dec 2012 04:34:03 +0000

 Module Name:	pkgsrc
 Committed By:	agc
 Date:		Mon Dec 17 04:34:02 UTC 2012

 Modified Files:
 	pkgsrc/pkgtools/pkg_install/files/admin: pkg_admin.1
 	pkgsrc/pkgtools/pkg_install/files/info: main.c pkg_info.1
 	pkgsrc/pkgtools/pkg_install/files/lib: pkg_install.conf.5.in

 Log Message:
 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.


 To generate a diff of this commit:
 cvs rdiff -u -r1.32 -r1.33 \
     pkgsrc/pkgtools/pkg_install/files/admin/pkg_admin.1
 cvs rdiff -u -r1.30 -r1.31 pkgsrc/pkgtools/pkg_install/files/info/main.c
 cvs rdiff -u -r1.31 -r1.32 pkgsrc/pkgtools/pkg_install/files/info/pkg_info.1
 cvs rdiff -u -r1.16 -r1.17 \
     pkgsrc/pkgtools/pkg_install/files/lib/pkg_install.conf.5.in

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

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

NetBSD Home
NetBSD PR Database Search

(Contact us) $NetBSD: query-full-pr,v 1.51 2026/08/10 02:28:17 riastradh Exp $
$NetBSD: gnats_config.sh,v 1.10 2026/05/13 22:00:09 riastradh Exp $
Copyright © 1994-2026 The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.