man/qdepends: improve manpage

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

4 files changed, 111 insertions, 22 deletions

diff --git a/man/include/qdepends-05-examples.include b/man/include/qdepends-05-examples.include
index d4779ea..04fb92f 100644
--- a/man/include/qdepends-05-examples.include
+++ b/man/include/qdepends-05-examples.include
@@ -6,3 +6,20 @@ For finding out what a particular package depends on for building, you could do:
 .fi
 This tells us that we have \fIapp-editors/nano-2.3.2\fR installed and it depends
 on ncurses (among other things).
+
+Searching for packages that actually have nano in their RDEPEND:
+.nf
+	$ \fIqdepends -rQ nano\fR
+	virtual/editor-0
+.fi
+Tells us that \fIvirtual/editor\fR depends on nano.  However, if we
+wanted to know in what way a package specifically depends on another
+package, one can use \fB\-v\fR.
+.nf
+	$ \fIqdepends -vrQ logrotate\fR
+	sys-apps/portage-2.3.18: >=app-admin/logrotate-3.8.0
+.fi
+This way we can see there is a specific dependency expressed here.  If
+the above had used \fI<logrotate-3\fR, for example, no matches would be
+returned.  Not using any specifiers allows to reveal in what way a
+dependency is expressed.
diff --git a/man/include/qdepends.desc b/man/include/qdepends.desc
index b9713d0..0143847 100644
--- a/man/include/qdepends.desc
+++ b/man/include/qdepends.desc
@@ -1,11 +1,15 @@
-The qdepends applet has a couple different modes.  Normally it is geared towards
+The
+.I qdepends
+applet has a couple different modes.  Normally it is geared towards
 answering the queries "what does package X depend on" and "what packages depend
 on X".  Both can further be classified into build, run, and post dependencies.
 
 By default, it will tell you the build time dependencies only (DEPEND).
 
-Currently, qdepends will only query installed packages.  There is no support for
-querying packages not yet installed (the \fBequery\fR(1) tool can do that).
+Currently,
+.I qdepends
+will only query installed packages.  There is no support for
+querying packages not yet installed (see \fBequery\fR(1) for that).
 
 If there is no answer to your query (i.e. you've asked for a package that is not
 installed, or a version that does not match), then you will get back no output.
diff --git a/man/include/qdepends.optdesc.yaml b/man/include/qdepends.optdesc.yaml
new file mode 100644
index 0000000..51b1cc7
--- /dev/null
+++ b/man/include/qdepends.optdesc.yaml
@@ -0,0 +1,29 @@
+all: |
+    Show *DEPEND, alias for \fB\-drp\fR.
+key: |
+    Advanced option to allow querying the VDB.  This option overrides
+    \fB\-d\fR, \fB\-r\fR, \fB\-p\fR or \fB\-a\fR.  \fI<arg>\fR can be
+    any key from Portage's VDB, e.g.\ any file from
+    var/db/pkg/<cat>/<pkg>/.
+query: |
+    Query reverse deps.  This basically reverses the search to any
+    package that references \fI<arg>\fR in DEPEND, RDEPEND or PDEPEND.
+    This can be useful to find consumers of a given package, e.g.\ to
+    search for packages that have \fIlogwatch\fR in their DEPEND.
+name-only: |
+    Only show category/package, instead of category/package-version.
+format: |
+    Pretty-print DEPEND declaration to be used in an ebuild.  This
+    option initiates a very different mode of operation.  Instead of
+    printing searching through packages, it constructs a multi-line
+    statement in with shell syntax, to be used in an ebuild.  Each
+    argument is turned into a separate DEPEND variable declaration.  You
+    need to quote dependency strings in order for them to be printed as
+    a single dependency declaration.  When used with the \fB\-q\fR
+    option, only the pretty-printed dependency declaration is printed,
+    e.g.\ the DEPEND= part is skipped.
+verbose: |
+    When in reverse dep mode, print the package or packages that matched
+    the query from the dependency line being searched.  This includes
+    specifiers and versions.
+quiet: Suppress DEPEND= output for \fB\-f\fR.
diff --git a/man/qdepends.1 b/man/qdepends.1
index a0cac5b..c51a02d 100644
--- a/man/qdepends.1
+++ b/man/qdepends.1
@@ -1,64 +1,85 @@
-.TH qdepends "1" "Mar 2016" "Gentoo Foundation" "qdepends"
+.\" generated by mkman.py, please do NOT edit!
+.TH qdepends "1" "Apr 2018" "Gentoo Foundation" "qdepends"
 .SH NAME
 qdepends \- show dependency info
 .SH SYNOPSIS
 .B qdepends
 \fI[opts] <pkgname>\fR
 .SH DESCRIPTION
-The qdepends applet has a couple different modes.  Normally it is geared towards
+The
+.I qdepends
+applet has a couple different modes.  Normally it is geared towards
 answering the queries "what does package X depend on" and "what packages depend
 on X".  Both can further be classified into build, run, and post dependencies.
 
 By default, it will tell you the build time dependencies only (DEPEND).
 
-Currently, qdepends will only query installed packages.  There is no support for
-querying packages not yet installed (the \fBequery\fR(1) tool can do that).
+Currently,
+.I qdepends
+will only query installed packages.  There is no support for
+querying packages not yet installed (see \fBequery\fR(1) for that).
 
 If there is no answer to your query (i.e. you've asked for a package that is not
 installed, or a version that does not match), then you will get back no output.
 .SH OPTIONS
 .TP
 \fB\-d\fR, \fB\-\-depend\fR
-Show DEPEND info (default)
+Show DEPEND info (default).
 .TP
 \fB\-r\fR, \fB\-\-rdepend\fR
-Show RDEPEND info
+Show RDEPEND info.
 .TP
 \fB\-p\fR, \fB\-\-pdepend\fR
-Show PDEPEND info
+Show PDEPEND info.
 .TP
 \fB\-k\fR \fI<arg>\fR, \fB\-\-key\fR \fI<arg>\fR
-User defined vdb key
+Advanced option to allow querying the VDB.  This option overrides
+\fB\-d\fR, \fB\-r\fR, \fB\-p\fR or \fB\-a\fR.  \fI<arg>\fR can be
+any key from Portage's VDB, e.g.\ any file from
+var/db/pkg/<cat>/<pkg>/.
 .TP
 \fB\-Q\fR \fI<arg>\fR, \fB\-\-query\fR \fI<arg>\fR
-Query reverse deps
+Query reverse deps.  This basically reverses the search to any
+package that references \fI<arg>\fR in DEPEND, RDEPEND or PDEPEND.
+This can be useful to find consumers of a given package, e.g.\ to
+search for packages that have \fIlogwatch\fR in their DEPEND.
 .TP
 \fB\-N\fR, \fB\-\-name\-only\fR
-Only show package name
+Only show category/package, instead of category/package-version.
 .TP
 \fB\-a\fR, \fB\-\-all\fR
-Show all DEPEND info
+Show *DEPEND, alias for \fB\-drp\fR.
 .TP
 \fB\-f\fR, \fB\-\-format\fR
-Pretty format specified depend strings
+Pretty-print DEPEND declaration to be used in an ebuild.  This
+option initiates a very different mode of operation.  Instead of
+printing searching through packages, it constructs a multi-line
+statement in with shell syntax, to be used in an ebuild.  Each
+argument is turned into a separate DEPEND variable declaration.  You
+need to quote dependency strings in order for them to be printed as
+a single dependency declaration.  When used with the \fB\-q\fR
+option, only the pretty-printed dependency declaration is printed,
+e.g.\ the DEPEND= part is skipped.
 .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 in reverse dep mode, print the package or packages that matched
+the query from the dependency line being searched.  This includes
+specifiers and versions.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Tighter output; suppress warnings
+Suppress DEPEND= output for \fB\-f\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 "EXAMPLES"
 For finding out what a particular package depends on for building, you could do:
 .nf
@@ -67,10 +88,28 @@ For finding out what a particular package depends on for building, you could do:
 .fi
 This tells us that we have \fIapp-editors/nano-2.3.2\fR installed and it depends
 on ncurses (among other things).
+
+Searching for packages that actually have nano in their RDEPEND:
+.nf
+	$ \fIqdepends -rQ nano\fR
+	virtual/editor-0
+.fi
+Tells us that \fIvirtual/editor\fR depends on nano.  However, if we
+wanted to know in what way a package specifically depends on another
+package, one can use \fB\-v\fR.
+.nf
+	$ \fIqdepends -vrQ logrotate\fR
+	sys-apps/portage-2.3.18: >=app-admin/logrotate-3.8.0
+.fi
+This way we can see there is a specific dependency expressed here.  If
+the above had used \fI<logrotate-3\fR, for example, no matches would be
+returned.  Not using any specifiers allows to reveal in what way a
+dependency is expressed.
 .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@gentoo.org
 .SH AUTHORS
 .nf
 Ned Ludd <solar@gentoo.org>