qdepends: make -qq with -Q just print list of packages

Bug: https://bugs.gentoo.org/683430
Signed-off-by: Fabian Groffen <grobian@gentoo.org>

3 files changed, 37 insertions, 2 deletions

diff --git a/man/include/qdepends-05-examples.include b/man/include/qdepends-05-examples.include
index d3eac01..98ceb3a 100644
--- a/man/include/qdepends-05-examples.include
+++ b/man/include/qdepends-05-examples.include
@@ -17,3 +17,20 @@ 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.
+.P
+Producing a list of packages that need rebuilding after a Perl upgrade:
+.nf
+	$ \fIqdepends -Qqq -F '%[CATEGORY]%[PN]%[SLOT]' ^perl:0/5.30\fR
+	dev-vcs/git:0
+	perl-core/File-Temp:0
+	dev-perl/Text-CSV_XS:0
+	...
+.fi
+With the double \fB-q\fR flag, just the matching packages are returned,
+allowing to use the list for instance as arguments to \fBemerge\fR(1).
+The custom formatter in this case ensures all selected packages will be
+the best matching for the currently installed SLOT.  Finally, the use of
+the antislot matching (\fI^\fR) is returning all packages that depend on
+perl in SLOT \fB0\fR, but in a different SUBSLOT than \fB5.30\fR,
+effectively requesting the list of packages that need rebuilding to use
+the newly installed version of Perl.
diff --git a/man/include/qdepends.optdesc.yaml b/man/include/qdepends.optdesc.yaml
index dc4ce91..f49461c 100644
--- a/man/include/qdepends.optdesc.yaml
+++ b/man/include/qdepends.optdesc.yaml
@@ -32,4 +32,5 @@ verbose: |
     matches.  When used with \fB-t\fR, the atom highlighting matches
     what is used by the installed package, if available.
 quiet: Suppress DEPEND= output for \fB\-f\fR.  Only print the matching
-    atom for \fB\-Q\fR.
+    atom for \fB\-Q\fR.  When given two or more times, suppresses the
+    matching atom for \fB\-Q\fR, e.g.\ producing just a list of packages.
diff --git a/man/qdepends.1 b/man/qdepends.1
index d7c8957..7898e3d 100644
--- a/man/qdepends.1
+++ b/man/qdepends.1
@@ -92,7 +92,7 @@ matches.  When used with \fB-t\fR, the atom highlighting matches
 what is used by the installed package, if available.
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Suppress DEPEND= output for \fB\-f\fR.  Only print the matching atom for \fB\-Q\fR.
+Suppress DEPEND= output for \fB\-f\fR.  Only print the matching atom for \fB\-Q\fR.  When given two or more times, suppresses the matching atom for \fB\-Q\fR, e.g.\ producing just a list of packages.
 .TP
 \fB\-C\fR, \fB\-\-nocolor\fR
 Don't output color.
@@ -121,6 +121,23 @@ 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.
+.P
+Producing a list of packages that need rebuilding after a Perl upgrade:
+.nf
+	$ \fIqdepends -Qqq -F '%[CATEGORY]%[PN]%[SLOT]' ^perl:0/5.30\fR
+	dev-vcs/git:0
+	perl-core/File-Temp:0
+	dev-perl/Text-CSV_XS:0
+	...
+.fi
+With the double \fB-q\fR flag, just the matching packages are returned,
+allowing to use the list for instance as arguments to \fBemerge\fR(1).
+The custom formatter in this case ensures all selected packages will be
+the best matching for the currently installed SLOT.  Finally, the use of
+the antislot matching (\fI^\fR) is returning all packages that depend on
+perl in SLOT \fB0\fR, but in a different SUBSLOT than \fB5.30\fR,
+effectively requesting the list of packages that need rebuilding to use
+the newly installed version of Perl.
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .br