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

[Fabian Groffen]

commit:     692759d4e74b958dff78f86a53a3b56f4920a980
Author:     Fabian Groffen <grobian <AT> gentoo <DOT> org>
AuthorDate: Mon Apr  8 08:56:21 2019 +0000
Commit:     Fabian Groffen <grobian <AT> gentoo <DOT> org>
CommitDate: Mon Apr  8 08:56:21 2019 +0000
URL:        https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=692759d4

qdepends: update manpage for rewrite

Signed-off-by: Fabian Groffen <grobian <AT> gentoo.org>

 man/include/qdepends-05-examples.include | 20 +++-----
 man/include/qdepends.desc                | 33 ++++++++++----
 man/include/qdepends.optdesc.yaml        | 11 +++--
 man/qdepends.1                           | 78 ++++++++++++++++----------------
 qdepends.c                               |  6 +--
 5 files changed, 79 insertions(+), 69 deletions(-)

diff --git a/man/include/qdepends-05-examples.include b/man/include/qdepends-05-examples.include
index 04fb92f..d3eac01 100644
--- a/man/include/qdepends-05-examples.include
+++ b/man/include/qdepends-05-examples.include
@@ -1,25 +1,19 @@
 .SH "EXAMPLES"
 For finding out what a particular package depends on for building, you could do:
 .nf
-	$ \fIqdepends nano\fR
+	$ \fIqdepends -d nano\fR
 	app-editors/nano-2.3.2: >=sys-libs/ncurses-5.9-r1[unicode] sys-apps/file ...
 .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:
+.P
+Searching for packages that actually depend on logrotate:
 .nf
-	$ \fIqdepends -rQ nano\fR
-	virtual/editor-0
+	$ \fIqdepends -qQ logrotate\fR
+	sys-apps/portage-2.3.18: !<app-admin/logrotate-3.8.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 \fB-q\fR flag suppresses the entire list of dependencies here, so we
+can quickly see what specific dependency is 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 0143847..070032e 100644
--- a/man/include/qdepends.desc
+++ b/man/include/qdepends.desc
@@ -1,15 +1,30 @@
 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).
-
+applet has two different modes, forward and reverse dependency querying.
+Default operation is forward mode, answering the queries "what does
+package X depend on", while reverse mode answers "what packages depend
+on X".  Both modes can be further specified into build (DEPEND), run
+(RDEPEND), post (PDEPEND) and EAPI7's BDEPEND dependencies.
+.P
+By default, \fIqdepends\fR returns the unique set of atoms that match
+all dependency variables.  To split this out per variable, use \fB-v\fR
+option.
+.P
 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.
+.P
+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 empty output.
+.P
+After version \fB0.74\fR of portage-utils, \fIqdepends\fR was changed
+considerably to be more consistent and more advanced.  Most notably,
+this has changed default output for reverse mode (\fB-Q\fR).  Instead of
+just displaying the package name, like for forward mode, all
+dependencies for the package are shown.  When colours are enabled, the
+matched atom is highlighted in the list.  In addition to just querying
+DEPEND, the default mode changed to query all DEPEND-variables, and
+return the unique atoms found in them.  Automatic regular expression
+match support was removed.

diff --git a/man/include/qdepends.optdesc.yaml b/man/include/qdepends.optdesc.yaml
index 5d786f3..f317227 100644
--- a/man/include/qdepends.optdesc.yaml
+++ b/man/include/qdepends.optdesc.yaml
@@ -16,14 +16,15 @@ 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
+    statement 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.
+    Pretty-print atoms output, per DEPEND-variable.  This is much like
+    the \fB-f\fR option, but uses as input the dependency info from the
+    matches.
+quiet: Suppress DEPEND= output for \fB\-f\fR.  Only print the matching
+    atom for \fB\-Q\fR.

diff --git a/man/qdepends.1 b/man/qdepends.1
index f5c8c01..dcaef0c 100644
--- a/man/qdepends.1
+++ b/man/qdepends.1
@@ -1,5 +1,5 @@
 .\" generated by mkman.py, please do NOT edit!
-.TH qdepends "1" "Feb 2019" "Gentoo Foundation" "qdepends"
+.TH qdepends "1" "Apr 2019" "Gentoo Foundation" "qdepends"
 .SH NAME
 qdepends \- show dependency info
 .SH SYNOPSIS
@@ -8,23 +8,38 @@ qdepends \- show dependency info
 .SH DESCRIPTION
 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).
-
+applet has two different modes, forward and reverse dependency querying.
+Default operation is forward mode, answering the queries "what does
+package X depend on", while reverse mode answers "what packages depend
+on X".  Both modes can be further specified into build (DEPEND), run
+(RDEPEND), post (PDEPEND) and EAPI7's BDEPEND dependencies.
+.P
+By default, \fIqdepends\fR returns the unique set of atoms that match
+all dependency variables.  To split this out per variable, use \fB-v\fR
+option.
+.P
 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.
+.P
+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 empty output.
+.P
+After version \fB0.74\fR of portage-utils, \fIqdepends\fR was changed
+considerably to be more consistent and more advanced.  Most notably,
+this has changed default output for reverse mode (\fB-Q\fR).  Instead of
+just displaying the package name, like for forward mode, all
+dependencies for the package are shown.  When colours are enabled, the
+matched atom is highlighted in the list.  In addition to just querying
+DEPEND, the default mode changed to query all DEPEND-variables, and
+return the unique atoms found in them.  Automatic regular expression
+match support was removed.
 .SH OPTIONS
 .TP
 \fB\-d\fR, \fB\-\-depend\fR
-Show DEPEND info (default).
+Show DEPEND info.
 .TP
 \fB\-r\fR, \fB\-\-rdepend\fR
 Show RDEPEND info.
@@ -35,13 +50,7 @@ Show PDEPEND info.
 \fB\-b\fR, \fB\-\-bdepend\fR
 Show BDEPEND info.
 .TP
-\fB\-k\fR \fI<arg>\fR, \fB\-\-key\fR \fI<arg>\fR
-Advanced option to allow querying the VDB.  This option overrides
-\fB\-d\fR, \fB\-r\fR, \fB\-p\fR, \fB\-b\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
+\fB\-Q\fR, \fB\-\-query\fR
 Query reverse deps.  This basically reverses the search to any
 package that references \fI<arg>\fR in DEPEND, RDEPEND, PDEPEND or BDEPEND.
 This can be useful to find consumers of a given package, e.g.\ to
@@ -50,14 +59,11 @@ search for packages that have \fIlogwatch\fR in their DEPEND.
 \fB\-N\fR, \fB\-\-name\-only\fR
 Only show category/package, instead of category/package-version.
 .TP
-\fB\-a\fR, \fB\-\-all\fR
-Show *DEPEND, alias for \fB\-drpb\fR.
-.TP
 \fB\-f\fR, \fB\-\-format\fR
 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
+statement 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
@@ -68,12 +74,12 @@ e.g.\ the DEPEND= part is skipped.
 Set the ROOT env var.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-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.
+Pretty-print atoms output, per DEPEND-variable.  This is much like
+the \fB-f\fR option, but uses as input the dependency info from the
+matches.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Suppress DEPEND= output for \fB\-f\fR.
+Suppress DEPEND= output for \fB\-f\fR.  Only print the matching atom for \fB\-Q\fR.
 .TP
 \fB\-C\fR, \fB\-\-nocolor\fR
 Don't output color.
@@ -86,25 +92,19 @@ Print version and exit.
 .SH "EXAMPLES"
 For finding out what a particular package depends on for building, you could do:
 .nf
-	$ \fIqdepends nano\fR
+	$ \fIqdepends -d nano\fR
 	app-editors/nano-2.3.2: >=sys-libs/ncurses-5.9-r1[unicode] sys-apps/file ...
 .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.
+.P
+Searching for packages that actually depend on logrotate:
 .nf
-	$ \fIqdepends -vrQ logrotate\fR
-	sys-apps/portage-2.3.18: >=app-admin/logrotate-3.8.0
+	$ \fIqdepends -qQ 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 \fB-q\fR flag suppresses the entire list of dependencies here, so we
+can quickly see what specific dependency is 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/qdepends.c b/qdepends.c
index df3434e..09156f6 100644
--- a/qdepends.c
+++ b/qdepends.c
@@ -210,10 +210,10 @@ qdepends_results_cb(q_vdb_pkg_ctx *pkg_ctx, void *priv)
 						ret = 1;
 
 						if (!firstmatch) {
-							printf("%s%s/%s%s%s%s",
+							printf("%s%s/%s%s%s:",
 									BOLD, catname, BLUE,
-									qdep_name_only ? datom->PN : pkgname, NORM,
-									quiet ? "" : ":");
+									qdep_name_only ? datom->PN : pkgname,
+									NORM);
 						}
 						firstmatch = true;