[pacman-dev] [PATCH] Query documentation updates

[Nagy Gabor]

>From 8f675582f8f0098ec524fa702c38058c687e53fd Mon Sep 17 00:00:00 2001
From: Nagy Gabor <ngaba at bibl.u-szeged.hu>
Date: Thu, 14 May 2009 16:15:20 +0200
Subject: [PATCH] Query documentation updates

The old documentation didn't emphasize our filtering options at all, and it
was a bit misleading. ("List ALL...")

I also clarified the description of -Qu.

Signed-off-by: Nagy Gabor <ngaba at bibl.u-szeged.hu>
---
 doc/pacman.8.txt    |   28 +++++++++++++++++-----------
 src/pacman/pacman.c |   10 +++++-----
 2 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/doc/pacman.8.txt b/doc/pacman.8.txt
index 37680be..4582be5 100644
--- a/doc/pacman.8.txt
+++ b/doc/pacman.8.txt
@@ -33,7 +33,10 @@ Operations
 	packages and their files, as well as meta-information about individual
 	packages (dependencies, conflicts, install date, build date, size). This
 	can be run against the local package database or can be used on
-	individual '.tar.gz' packages. See <<QO,Query Options>> below.
+	individual '.tar.gz' packages. In the first case, if no package names
+	are provided in the command line, all installed packages will be
+	queried. Additionally, various filters can be applied on the package
+	list. See <<QO,Query Options>> below.
 
 *-R, \--remove*::
 	Remove a package from the system. Groups can also be specified to be
@@ -164,16 +167,17 @@ Query Options[[QO]]
 	it will be shown if available.
 
 *-d, \--deps*::
-	List all packages installed as dependencies. This option can be combined
-	with '-t' for listing real orphans- packages that were installed as
-	dependencies but are no longer required by any installed package. ('-Qdt'
-	is equivalent to the pacman 3.0.X '-Qe' option.)
+	Restrict or filter output to packages installed as dependencies. This
+	option can be combined with '-t' for listing real orphans- packages that
+	were installed as dependencies but are no longer required by any
+	installed package. ('-Qdt' is equivalent to the pacman 3.0.X '-Qe'
+	option.)
 
 *-e, \--explicit*::
-	List all packages explicitly installed. This option can be combined with
-	'-t' to list top-level packages- those packages that were explicitly
-	installed but are not required by any other package. ('-Qet' is equivalent
-	to the pacman 2.9.X '-Qe' option.)
+	Restrict or filter output to packages explicitly installed. This option
+	can be combined with '-t' to list top-level packages- those packages
+	that were explicitly installed but are not required by any other
+	package. ('-Qet' is equivalent to the pacman 2.9.X '-Qe' option.)
 
 *-g, \--groups*::
 	Display all packages that are members of a named group. If a name is not
@@ -221,8 +225,10 @@ Query Options[[QO]]
 	installed package.
 
 *-u, \--upgrades*::
-	Lists all packages that are out of date on the local system. This option
-	works best if the sync database is refreshed using '-Sy'.
+	Restrict or filter output to packages that are out of date on the local
+	system. (Only package versions are used to find outdated packages,
+	replacements are not checked here.) This option works best if the sync
+	database is refreshed using '-Sy'.
 
 
 Remove Options[[RO]]
diff --git a/src/pacman/pacman.c b/src/pacman/pacman.c
index 14cfdfa..72a72ba 100644
--- a/src/pacman/pacman.c
+++ b/src/pacman/pacman.c
@@ -103,17 +103,17 @@ static void usage(int op, const char * const myname)
 			printf("%s:  %s {-Q --query} [%s] [%s]\n", str_usg, myname, str_opt, str_pkg);
 			printf("%s:\n", str_opt);
 			printf(_("  -c, --changelog      view the changelog of a package\n"));
-			printf(_("  -d, --deps           list all packages installed as dependencies\n"));
-			printf(_("  -e, --explicit       list all packages explicitly installed\n"));
+			printf(_("  -d, --deps           list packages installed as dependencies [filter]\n"));
+			printf(_("  -e, --explicit       list packages explicitly installed [filter]\n"));
 			printf(_("  -g, --groups         view all members of a package group\n"));
 			printf(_("  -i, --info           view package information (-ii for backup files)\n"));
 			printf(_("  -l, --list           list the contents of the queried package\n"));
-			printf(_("  -m, --foreign        list installed packages not found in sync db(s)\n"));
+			printf(_("  -m, --foreign        list installed packages not found in sync db(s) [filter]\n"));
 			printf(_("  -o, --owns <file>    query the package that owns <file>\n"));
 			printf(_("  -p, --file <package> query a package file instead of the database\n"));
 			printf(_("  -s, --search <regex> search locally-installed packages for matching strings\n"));
-			printf(_("  -t, --unrequired     list all packages not required by any package\n"));
-			printf(_("  -u, --upgrades       list all outdated packages\n"));
+			printf(_("  -t, --unrequired     list packages not required by any package [filter]\n"));
+			printf(_("  -u, --upgrades       list outdated packages [filter]\n"));
 			printf(_("  -q, --quiet          show less information for query and search\n"));
 		} else if(op == PM_OP_SYNC) {
 			printf("%s:  %s {-S --sync} [%s] [%s]\n", str_usg, myname, str_opt, str_pkg);
-- 
1.6.0.3