Massive man page updates, fixes #63045.

svn path=/; revision=122

3 files changed, 191 insertions, 47 deletions

diff --git a/trunk/src/equery/ChangeLog b/trunk/src/equery/ChangeLog
index 8645c71..ae3a567 100644
--- a/trunk/src/equery/ChangeLog
+++ b/trunk/src/equery/ChangeLog
@@ -1,3 +1,6 @@
+2004-09-08 Karl Trygve Kalleberg <karltk@gentoo.org>
+	* Added man page rewrites by Katerina Barone-Adesi <katerinab@gmail.com>
+
 2004-08-29 Karl Trygve Kalleberg <karltk@gentoo.org>
 	* Added check for bad regexp in belongs, fixes #58494
 	* Added proper error reporting to stderr, fixes #57580
diff --git a/trunk/src/equery/equery b/trunk/src/equery/equery
index 45a0d4d..e816491 100755
--- a/trunk/src/equery/equery
+++ b/trunk/src/equery/equery
@@ -27,6 +27,7 @@ from output import *
 import gentoolkit
 
 from gentoolkit import print_warn, print_error, print_info, die
+from gentoolkit import pcpv, ppath, pslot, pnumber, pmaskflag, pinstalledflag, puseflag, ppkgquery, pregexpquery
 
 # Auxiliary functions
 
@@ -131,7 +132,7 @@ class CmdListFiles(Command):
 
         (query, opts) = self.parseArgs(args)
 
-        print_info(3, "Searching for packages matching '" + query + "'...")
+        print_info(3, "[ Searching for packages matching " + ppkgquery(query) + "... ]")
             
         pkgs = gentoolkit.find_packages(query, True)
         for x in pkgs:
@@ -139,7 +140,7 @@ class CmdListFiles(Command):
             if not x.is_installed():
                 continue
         
-            print_info(1, "Contents of " + x.get_cpv() + ":")
+            print_info(1, turquoise("* ") + "Contents of " + pcpv(x.get_cpv()) + ":")
 
             cnt = x.get_contents()
 
@@ -223,7 +224,7 @@ class CmdListBelongs(Command):
             else:
                 rx = re.compile("/" + query + "$")
         except:
-            die(2, "The query '" + white(query) + "' does not appear to be a valid regular expression")
+            die(2, "The query '" + regexpquery(query) + "' does not appear to be a valid regular expression")
 
         # Pick out only selected categories
         cat = opts["category"]
@@ -231,7 +232,7 @@ class CmdListBelongs(Command):
         if cat != "*":
             filter_fn = lambda x: x.find(cat+"/")==0
 
-        info(3, "Searching for file '" + query + "' in " + cat + "...")
+        print_info(3, "[ Searching for file " + pregexpquery(query) + " in " + pcpv(cat) + "... ]")
             
         matches = gentoolkit.find_all_installed_packages(filter_fn)
 
@@ -242,9 +243,9 @@ class CmdListBelongs(Command):
                 continue
             for file in cnt.keys():
                 if rx.search(file):
-                    s = pkg.get_cpv()
+                    s = pcpv(pkg.get_cpv())
                     if not Config["piping"]:
-                        s += " (" + fileAsStr(file, cnt[file]) + ")"
+                        s += " (" + ppath(fileAsStr(file, cnt[file])) + ")"
                     print_info(0, s)
                     if opts["earlyOut"]:
                         found = 1
@@ -328,7 +329,7 @@ class CmdDisplayUSEs(Command):
                 if len(fields) == 2:
                     usedesc[fields[0].strip()] = fields[1].strip()
         except IOError:
-            print_warn(5, "Could not load USE flag descriptions from " + white(gentoolkit.settings["PORTDIR"] + "/profiles/use.desc"))
+            print_warn(5, "Could not load USE flag descriptions from " + ppath(gentoolkit.settings["PORTDIR"] + "/profiles/use.desc"))
 
         # Load local USE flag descriptions
         try:
@@ -345,7 +346,7 @@ class CmdDisplayUSEs(Command):
                         else:
                             uselocaldesc[catpkguse.group(1).strip()][catpkguse.group(2).strip()] = fields[1].strip()
         except IOError:
-                print_warn(5, "Could not load USE flag descriptions from " + white(gentoolkit.settings["PORTDIR"] + "/profiles/use.desc"))
+                print_warn(5, "Could not load USE flag descriptions from " + path(gentoolkit.settings["PORTDIR"] + "/profiles/use.desc"))
 
         if not Config["piping"]: 
             print_info(3, "[ Colour Code : " + green("set") + " " + red("unset") + " ]")
@@ -397,7 +398,7 @@ class CmdDisplayUSEs(Command):
             # pretty print
             if output:
                 if not Config["piping"]:
-                    print_info(0, "[ Found these USE variables for : " + white(bestver) + " ]")
+                    print_info(0, "[ Found these USE variables for " + pcpv(bestver) + " ]")
                     print_info(3, white(" U I"))
                 maxflag_len = 0
                 for inuse, inused, u, desc in output:
@@ -421,18 +422,18 @@ class CmdDisplayUSEs(Command):
                         if desc:
                             print_info(0, " : " + desc)
                         else:
-                            print_info(0, ": unknown")
+                            print_info(0, " : <unknown>")
                 printed_matches += 1
             else:
                 if not Config["piping"]:
-                    print_info(1, "[ No USE flags found for :", white(p.get_cpv()), "]")
+                    print_info(1, "[ No USE flags found for " + pcpv(p.get_cpv()) + "]")
 
         if Config["verbosityLevel"] >= 2:
             if printed_matches == 0:
                 s = ""
                 if opts["installedOnly"]:
                     s = "installed "
-                die("No " + s + "packages found for \"") + white(query) + "\""
+                die(3, "No " + s + "packages found for " + pkgquery(query))
                 
                     
     def shortHelp(self):
@@ -496,13 +497,13 @@ class CmdDisplayDepGraph(Command):
             if Config["piping"]:
                 print_info(0, pkg.get_cpv() + ":")
             else:
-                print_info(3, "[ Dependencies for " + white(pkg.get_cpv()) + " ]")
+                print_info(3, "[ Dependencies for " + pcpv(pkg.get_cpv()) + " ]")
 
             if not pkg.is_installed():
                 continue
             stats = { "maxdepth": 0, "packages": 0 }
             self._graph(pkg, opts, stats)
-            print_info(0, "[ " + white(pkg.get_cpv()) + " stats: packages (" + green(str(stats["packages"])) + "), max depth (" + green(str(stats["maxdepth"])) + ") ]")
+            print_info(0, "[ " + white(pkg.get_cpv()) + " stats: packages (" + number(str(stats["packages"])) + "), max depth (" + number(str(stats["maxdepth"])) + ") ]")
         
     def _graph(self, pkg, opts, stats, level=0, pkgtbl=[], suffix=""):
     
@@ -534,7 +535,7 @@ class CmdDisplayDepGraph(Command):
         return pkgtbl
 
     def shortHelp(self):
-        return yellow("<local-opts> ") + turquoise("pkgspec") + " - display a dependency tree for " + turquoise("pkgspec")
+        return yellow("<local-opts> ") + pkgquery("pkgspec") + " - display a dependency tree for " + turquoise("pkgspec")
     def longHelp(self):
         return "Display a dependency tree for a given package\n" + \
                "\n" + \
@@ -595,21 +596,21 @@ class CmdDisplaySize(Command):
                 print_info(0, pkg.get_cpv() + ": total(" + str(files) + "), inaccessible(" + str(uncounted) + \
                     "), size(" + str(size) + ")")
             else:
-                print_info(0, "[ Size of " + white(pkg.get_cpv()) + " ]")
-                print_info(0, string.rjust(" Total files : ",25) + str(files))
+                print_info(0, "[ Size of " + pcpv(pkg.get_cpv()) + " ]")
+                print_info(0, string.rjust(" Total files : ",25) + number(str(files)))
     
                 if uncounted:
-                    print_info(0, string.rjust(" Inaccessible files : ",25) + str(uncounted))
+                    print_info(0, string.rjust(" Inaccessible files : ",25) + number(str(uncounted)))
     
                 sz = "%.2f KiB" % (size/1024.0)                
                 if opts["reportSizeInBytes"]:
-                    sz = str(size) + " bytes"
+                    sz = number(str(size)) + " bytes"
                 
-                print_info(0, string.rjust("Total size  : ",25) + sz)
+                print_info(0, string.rjust("Total size  : ",25) + number(sz))
 
                     
     def shortHelp(self):
-        return yellow("<local-opts> ") + turquoise("pkgspec") + " - print size of files contained in package " + turquoise("pkgspec")
+        return yellow("<local-opts> ") + pkgquery("pkgspec") + " - print size of files contained in package " + turquoise("pkgspec")
     def longHelp(self):
         return "Print size total size of files contained in a given package" + \
                "\n" + \
@@ -676,8 +677,8 @@ class CmdCheckIntegrity(Command):
                 continue
             if Config["piping"]:
                 print_info(0, pkg.get_cpv() + ":")
-            elif Config["verbosityLevel"] >= 1:
-                print_info(1, "[ Checking " + white(pkg.get_cpv()) + " ]")
+            else:
+                print_info(1, "[ Checking " + pcpv(pkg.get_cpv()) + " ]")
                 
             files = pkg.get_contents()
             checked_files = 0
@@ -716,12 +717,12 @@ class CmdCheckIntegrity(Command):
                 except CheckException, (e):
                     print_error(e.s)
                 except OSError:
-                    print_error(white(file) + " does not exist")
+                    print_error(path(file) + " does not exist")
                 checked_files += 1
-            print_info(0, yellow(" * ") + green(str(good_files)) + " out of " +  white(str(checked_files)) + " files good")
+            print_info(0, yellow(" * ") + number(str(good_files)) + " out of " +  number(str(checked_files)) + " files good")
                     
     def shortHelp(self):
-        return turquoise("pkgspec") + " - check package's files against recorded MD5 sums and timestamps"
+        return pkgquery("pkgspec") + " - check package's files against recorded MD5 sums and timestamps"
     def longHelp(self):
         return "Check package's files against recorded MD5 sums and timestamps"
 
@@ -770,10 +771,10 @@ class CmdWhich(Command):
         if matches:
             print_info(0, os.path.normpath(matches[-1].get_ebuild_path()))
         else:
-            print_error("No masked or unmasked packages found for " + white(query))
+            print_error("No masked or unmasked packages found for " + pkgquery(query))
                     
     def shortHelp(self):
-        return turquoise("pkgspec") + " - print full path to ebuild for package " + turquoise("pkgspec")
+        return pkgquery("pkgspec") + " - print full path to ebuild for package " + pkgquery("pkgspec")
     def longHelp(self):
         return "Print full path to ebuild for a given package"
 
@@ -877,19 +878,19 @@ class CmdListPackages(Command):
             if name == ".*":
                 sname = "all packages"
             if not Config["piping"]:
-                print_info(1, "Searching for " + white(sname) + " in " + white(scat) + " among:")
+                print_info(1, "Searching for " + pcpv(sname) + " in " + pcpv(scat) + " among:")
                 if opts["includeInstalled"]:
                     print_info(1, turquoise(" *") + " installed packages")
                 if opts["includePortTree"]:
-                    print_info(1, turquoise(" *") + " Portage tree (" + gentoolkit.settings["PORTDIR"] + ")")
+                    print_info(1, turquoise(" *") + " Portage tree (" + path(gentoolkit.settings["PORTDIR"]) + ")")
                 if opts["includeOverlayTree"]:
-                    print_info(1, turquoise(" *") + " overlay tree (" + gentoolkit.settings["PORTDIR_OVERLAY"] + ")")
+                    print_info(1, turquoise(" *") + " overlay tree (" + path(gentoolkit.settings["PORTDIR_OVERLAY"]) + ")")
         
         matches = package_finder(filter_fn)
 
         rx = re.compile(cat + "/" + name + "-" + ver + "(-" + rev + ")?")
-        pfxmodes = [ "[---]", "[" + green("I") + "--]", "[-P-]", "[--O]" ]
-        maskmodes = [ "[  ]", "[ ~]", "[ -]", "[" + red("M") + " ]", "[" + red("M") + "~]", "[" + red("M") + "-]" ]
+        pfxmodes = [ "---", "I--", "-P-", "--O" ]
+        maskmodes = [ "  ", " ~", " -", "M ", "M~", "M-" ]
         for pkg in matches:
             status = 0
             if pkg.is_installed():
@@ -904,9 +905,9 @@ class CmdListPackages(Command):
             if pkg.is_masked():
                 pkgmask = pkgmask + 3
             keywords = pkg.get_env_var("KEYWORDS").split()
-            if "~"+gentoolkit.settings["ARCH"] in keywords:
+            if "~" + gentoolkit.settings["ARCH"] in keywords:
                 pkgmask = pkgmask + 1
-            elif "-*" in keywords or "-"+gentoolkit.settings["ARCH"] in keywords:
+            elif "-*" in keywords or "-" + gentoolkit.settings["ARCH"] in keywords:
                 pkgmask = pkgmask + 2
 
             # Determining SLOT value
@@ -919,7 +920,7 @@ class CmdListPackages(Command):
                     if Config["piping"]:
                         print_info(0, pkg.get_cpv())
                     else:
-                        print_info(0, pfxmodes[status] + " " + maskmodes[pkgmask] + " " + pkg.get_cpv() + " (" + blue(slot) + ")")
+                        print_info(0, "[" + pinstalledflag(pfxmodes[status]) + "] [" + pmaskflag(maskmodes[pkgmask]) + "] " + pcpv(pkg.get_cpv()) + " (" + pslot(slot) + ")")
                     
     def shortHelp(self):
         return yellow("<local-opts> ") + turquoise("pkgspec") + " - list all packages matching " + turquoise("pkgspec")
@@ -1010,19 +1011,19 @@ class CmdFindUSEs(Command):
             if cat == ".*":
                 scat = "all categories"
             if not Config["piping"]:
-                print_info(2, "Searching for USE flag " + white(query)  + " in " + white(scat) + " among:")
+                print_info(2, "Searching for USE flag " + puseflag(query)  + " in " + pcpv(scat) + " among:")
                 if opts["includeInstalled"]:
                     print_info(1, turquoise(" *") + " installed packages")
                 if opts["includePortTree"]:
-                    print_info(1, turquoise(" *") + " Portage tree (" + gentoolkit.settings["PORTDIR"] + ")")
+                    print_info(1, turquoise(" *") + " Portage tree (" + path(gentoolkit.settings["PORTDIR"]) + ")")
                 if opts["includeOverlayTree"]:
-                    print_info(1, turquoise(" *") + " overlay tree (" + gentoolkit.settings["PORTDIR_OVERLAY"] + ")")
+                    print_info(1, turquoise(" *") + " overlay tree (" + path(gentoolkit.settings["PORTDIR_OVERLAY"]) + ")")
         
         matches = package_finder(filter_fn)
 
         rx = re.compile(cat + "/" + name + "-" + ver + "(-" + rev + ")?")
-        pfxmodes = [ "[---]", "[I--]", "[-P-]", "[--O]" ]
-        maskmodes = [ "[  ]", "[ ~]", "[ -]", "[M ]", "[M~]", "[M-]" ]
+        pfxmodes = [ "---", "I--", "-P-", "--O" ]
+        maskmodes = [ "  ", " ~", " -", "M ", "M~", "M-" ]
         for pkg in matches:
             status = 0
             if pkg.is_installed():
@@ -1061,7 +1062,7 @@ class CmdFindUSEs(Command):
                 if Config["piping"]:
                     print_info(0, pkg.get_cpv())
                 else:
-                    print_info(0, pfxmodes[status] + " " + maskmodes[pkgmask] + " " + pkg.get_cpv() + " (" + blue(slot) + ")")
+                    print_info(0, "[" + pinstalledflag(pfxmodes[status]) + "] [" + pmaskflag(maskmodes[pkgmask]) + "] " + pcpv(pkg.get_cpv()) + " (" + pnumber(slot) + ")")
                     
     def shortHelp(self):
         return yellow("<local-opts> ") + turquoise("pkgspec") + " - list all packages with " + turquoise("useflag")
diff --git a/trunk/src/equery/equery.1 b/trunk/src/equery/equery.1
index 6e921af..6c07488 100644
--- a/trunk/src/equery/equery.1
+++ b/trunk/src/equery/equery.1
@@ -2,11 +2,151 @@
 .SH NAME
 equery \- Gentoo: Package Query Tool
 .SH SYNOPSIS
-.B equery
+.B equery  
+.I [global\-opts] command [local\-opts]
+.PP
+
+.SH DESCRIPTION
+
+equery is a flexible utility which may display various information about 
+packages, such as the files they own, their USE flags, the md5sum 
+of each file owned by a given package, and many other things.
+
+.SH OPTIONS
+The 'command' is the only mandatory option to equery.  Most commands require
+a 'pkgspec' option, which is described by <cat/>packagename<\-version>;
+namely, the package name is mandatory, while the category and version are 
+optional.
+
+[global\-opts] may be one of:
+
+.B \-q, \-\-quiet   
+causes minimal output to be emitted
+.PP
+.B \-C, \-\-nocolor 
+turns off colours
+.PP
+.B \-h, \-\-help
+displays a help summary
+.PP
+.B \-V, \-\-version
+displays the equery version
+.PP
+
+Only one command will actually be run, at most.  The possible commands are: 
+.TP
+.B belongs <local\-opts> file
+This command lists all packages owning the specified file.
+.br
+Note: Normally, only one package will own a file. If multiple packages own the
+same file, it usually consitutes a problem, and should be reported.
+.br
+.IP
+<local\-opts> is either or both of:
+.br
+.B \-c, \-\-category cat 
+only search in category cat
+.br
+.B \-e, \-\-earlyout 
+stop when first match found
+
+.PP
+.B check pkgspec
+This command checks the files of the specified package against recorded MD5 
+sums and timestamps.
+.PP
+.TP
+.B depgraph <local\-opts> pkgspec
+This command display a dependency tree for pkgspec, by default indented to reflect
+how dependancies relate to each other.
+.br
+<local\-opts> is either or both of:
+.br
+.B \-U, \-\-no\-useflags 
+do not show USE flags.  Note that this doesn't actually do anything, as USE flags
+are not shown even without this option.
+.br
+.B \-l, \-\-linear    
+do not use fancy formatting 
+.PP
+.TP
+.B files <local\-opts> pkgspec
+This lists files owned by a particular package, optionally with extra
+information specified by <local\-opts>
+.br
+
+<local\-opts> is any combination of:
+.br
+.B \-\-timestamp
+output the timestamp of each file
+.br
+.B \-\-md5sum
+output the md5sum of each file
+.br
+.B \-\-type
+output the type of each file
+.PP
+.TP
+.B list <local\-opts> pkgspec
+This command lists packages matching pkgspec in a user\-specified combination
+of installed packages, packages which are not installed, the portage tree, and
+the portage overlay tree.
+
+<local\-opts> must include not include only \-I;
+if \-I is used, \-p and/or \-o must be also.  By default, only installed
+packages are searched.  \-o searches only the overlay tree [and possibly
+installed packages],
+.I not
+the main portage tree.
+
+.B \-i, \-\-installed
+search installed packages (default)
+.br
+.B \-I, \-\-exclude\-installed
+do not search installed packages
+.br
+.B \-p, \-\-portage\-tree
+also search in portage tree (/usr/portage)
+.br
+.B \-o, \-\-overlay\-tree
+also search in overlay tree (/usr/local/portage)
+.PP
+.TP
+.B size <local\-opts> pkgspec
+This command outputs the number of files in the specified package, as well as
+their total size in an appropriate unit.
+
+The only possible value for <local\-opts>, if specified, is:
+.br
+.B \-b, \-\-bytes 
+report size in bytes
+.PP
+.TP
+.B uses <local\-opts> pkgspec 
+display USE flags for pkgspec.  No local options are actually implemented yet.
+.PP
+.B which pkgspec 
+print full path to ebuild for package pkgspec
+.PP
+
+.SH Unimplemented Options
+.PP
+.B changes
+.PP
+.B depends
+.PP
+.B glsa \fR \- use glsa\-check for the time being.
+.PP
+.B stats
+
+
+
 .SH BUGS
-This tool does not yet have a man page. Feel free to submit a bug about it to
-http://bugs.gentoo.org
+Many options aren't implemented.  Command\-line parsing could use some work. 
+.br
+Submit bug reports to http://bugs.gentoo.org
 .SH AUTHORS
-This informative man page was written by Karl Trygve Kalleberg 
-<karltk@gentoo.org>.
+equery, original man page: Karl Trygve Kalleberg <karltk@gentoo.org>, 2003.
+.br
+Massive man page updates: Katerina Barone\-Adesi <katerinab@gmail.com>, 2004.