diff options
author | agc <agc@pkgsrc.org> | 2012-12-17 04:34:02 +0000 |
---|---|---|
committer | agc <agc@pkgsrc.org> | 2012-12-17 04:34:02 +0000 |
commit | 3e78c61e20fad67639cc439ed7e45478205be1a8 (patch) | |
tree | fa3ba6bfab5392e963881c0ba9ecdeb1319b2c65 /pkgtools | |
parent | ad7a76c54dd85c92eb103f3987693b73eb1e7c49 (diff) | |
download | pkgsrc-3e78c61e20fad67639cc439ed7e45478205be1a8.tar.gz |
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.
Diffstat (limited to 'pkgtools')
-rw-r--r-- | pkgtools/pkg_install/files/admin/pkg_admin.1 | 8 | ||||
-rw-r--r-- | pkgtools/pkg_install/files/info/main.c | 6 | ||||
-rw-r--r-- | pkgtools/pkg_install/files/info/pkg_info.1 | 155 | ||||
-rw-r--r-- | pkgtools/pkg_install/files/lib/pkg_install.conf.5.in | 10 |
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 |