[gentoo-commits] proj/portage-utils:master commit in: man/, man/include/, /

[Fabian Groffen]

commit:     1def9d468742c0d6d6b24aa1f1d76243be6e24cd
Author:     Fabian Groffen <grobian <AT> gentoo <DOT> org>
AuthorDate: Tue Apr  3 11:49:41 2018 +0000
Commit:     Fabian Groffen <grobian <AT> gentoo <DOT> org>
CommitDate: Tue Apr  3 11:49:41 2018 +0000
URL:        https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=1def9d46

qlist: improve documentation

Bug: https://bugs.gentoo.org/645554

 man/include/qlist.desc         |  6 +++++
 man/include/qlist.optdesc.yaml | 24 ++++++++++++++++++
 man/qlist.1                    | 56 +++++++++++++++++++++++++++---------------
 qlist.c                        |  2 +-
 4 files changed, 67 insertions(+), 21 deletions(-)

diff --git a/man/include/qlist.desc b/man/include/qlist.desc
new file mode 100644
index 0000000..e02d971
--- /dev/null
+++ b/man/include/qlist.desc
@@ -0,0 +1,6 @@
+\fIqlist\fR shows the contents, or a subset thereof, of an installed
+package.  Alternatively, lists whether a package is installed,
+optionally with version, USE-flag, SLOT or REPO information.  The
+\fIpkgname\fR to query for does not have to be an exact match, it may be
+part of it, e.g.\ an entire category, or any package with some string in
+its name.

diff --git a/man/include/qlist.optdesc.yaml b/man/include/qlist.optdesc.yaml
new file mode 100644
index 0000000..a60ef0d
--- /dev/null
+++ b/man/include/qlist.optdesc.yaml
@@ -0,0 +1,24 @@
+installed: |
+    Instead of listing the contents of a package, just print the package
+    name if the package is currently installed.
+umap: |
+    List USE-flags enabled when the package was installed.  This flag
+    implies \fB\-I\fR.
+slot: |
+    Display installed packages with slots (use twice for subslots).
+    This flag implies \fB\-I\fR.
+repo: |
+    Display installed packages with repository the ebuild originated from.
+    This flag implies \fB\-I\fR.
+columns: |
+    Like \fB\-Iv\fR, but package name and version are separated by a
+    space for easy consumption by e.g.\ shell scripts which can read
+    space-separated columns.
+verbose: |
+    When used with \fB\-I\fR, print the package version next to name.
+    When listing the package contents, a single \fB\-v\fR displays
+    symlinks with an arrow (\->) to their target.  Two or more \fB\-v\fR
+    adds colour to the entries and prints like \fB\-I\fR before the
+    listing.
+quiet: |
+    Suppresses the parenthesis around the USE-flags when used with \fB\-U\fR.

diff --git a/man/qlist.1 b/man/qlist.1
index 05e9326..f7dd847 100644
--- a/man/qlist.1
+++ b/man/qlist.1
@@ -1,68 +1,84 @@
-.TH qlist "1" "Mar 2016" "Gentoo Foundation" "qlist"
+.\" generated by mkman.py, please do NOT edit!
+.TH qlist "1" "Apr 2018" "Gentoo Foundation" "qlist"
 .SH NAME
 qlist \- list files owned by pkgname
 .SH SYNOPSIS
 .B qlist
 \fI[opts] <pkgname>\fR
 .SH DESCRIPTION
-
+\fIqlist\fR shows the contents, or a subset thereof, of an installed
+package.  Alternatively, lists whether a package is installed,
+optionally with version, USE-flag, SLOT or REPO information.  The
+\fIpkgname\fR to query for does not have to be an exact match, it may be
+part of it, e.g.\ an entire category, or any package with some string in
+its name.
 .SH OPTIONS
 .TP
 \fB\-I\fR, \fB\-\-installed\fR
-Just show installed packages
+Instead of listing the contents of a package, just print the package
+name if the package is currently installed.
 .TP
 \fB\-S\fR, \fB\-\-slots\fR
-Display installed packages with slots (use twice for subslots)
+Display installed packages with slots (use twice for subslots).
 .TP
 \fB\-R\fR, \fB\-\-repo\fR
-Display installed packages with repository
+Display installed packages with repository the ebuild originated from.
+This flag implies \fB\-I\fR.
 .TP
 \fB\-U\fR, \fB\-\-umap\fR
-Display installed packages with flags used
+List USE-flags enabled when the package was installed.  This flag
+implies \fB\-I\fR.
 .TP
 \fB\-c\fR, \fB\-\-columns\fR
-Display column view
+Like \fB\-Iv\fR, but package name and version are separated by a
+space for easy consumption by e.g.\ shell scripts which can read
+space-separated columns.
 .TP
 \fB\-\-showdebug\fR
-Show /usr/lib/debug files
+Show /usr/lib/debug and /usr/src/debug files.
 .TP
 \fB\-e\fR, \fB\-\-exact\fR
-Exact match (only CAT/PN or PN without PV)
+Exact match (only CAT/PN or PN without PV).
 .TP
 \fB\-a\fR, \fB\-\-all\fR
-Show every installed package
+Show every installed package.
 .TP
 \fB\-d\fR, \fB\-\-dir\fR
-Only show directories
+Only show directories.
 .TP
 \fB\-o\fR, \fB\-\-obj\fR
-Only show objects
+Only show objects.
 .TP
 \fB\-s\fR, \fB\-\-sym\fR
-Only show symlinks
+Only show symlinks.
 .TP
 \fB\-\-root\fR \fI<arg>\fR
-Set the ROOT env var
+Set the ROOT env var.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Make a lot of noise
+When used with \fB\-I\fR, print the package version next to name.
+When listing the package contents, a single \fB\-v\fR displays
+symlinks with an arrow (\->) to their target.  Two or more \fB\-v\fR
+adds colour to the entries and prints like \fB\-I\fR before the
+listing.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Tighter output; suppress warnings
+Suppresses the parenthesis around the USE-flags when used with \fB\-U\fR.
 .TP
 \fB\-C\fR, \fB\-\-nocolor\fR
-Don't output color
+Don't output color.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Print this help and exit
+Print this help and exit.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
-Print version and exit
+Print version and exit.
 
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .br
-Product: Portage Development; Component: Tools
+Product: Portage Development; Component: Tools, Assignee:
+portage-utils@g.o
 .SH AUTHORS
 .nf
 Ned Ludd <solar@g.o>

diff --git a/qlist.c b/qlist.c
index 1f8757c..6b5eb0a 100644
--- a/qlist.c
+++ b/qlist.c
@@ -31,7 +31,7 @@ static const char * const qlist_opts_help[] = {
 	"Display installed packages with repository",
 	"Display installed packages with flags used",
 	"Display column view",
-	"Show /usr/lib/debug files",
+	"Show /usr/lib/debug and /usr/src/debug files",
 	"Exact match (only CAT/PN or PN without PV)",
 	"Show every installed package",
 	"Only show directories",