usage: add an extended text sectionv0.63

Many applets now are so complicated that a single line of text isn't
sufficient to describe all of its capabilities/nuances.  Allow them
to pass in an arbitrary string of data to contain examples.

34 files changed, 62 insertions, 52 deletions

diff --git a/main.c b/main.c
index 0834756..a50b451 100644
--- a/main.c
+++ b/main.c
@@ -115,7 +115,7 @@ void no_colors(void)
 
 /* display usage and exit */
 static void usage(int status, const char *flags, struct option const opts[],
-                  const char * const help[], int blabber)
+                  const char * const help[], const char *desc, int blabber)
 {
 	const char opt_arg[] = "[arg]";
 	const char a_arg[] = "<arg>";
@@ -136,10 +136,13 @@ static void usage(int status, const char *flags, struct option const opts[],
 					DKBLUE, applets[i].opts, NORM,
 					RED, NORM, _(applets[i].desc));
 	} else if (blabber > 0) {
-			printf("%sUsage:%s %s%s%s <opts> %s%s%s %s:%s %s\n", GREEN, NORM,
-				YELLOW, applets[blabber].name, NORM,
-				DKBLUE, applets[blabber].opts, NORM,
-				RED, NORM, _(applets[blabber].desc));
+		printf("%sUsage:%s %s%s%s [opts] %s%s%s %s:%s %s\n",
+			GREEN, NORM,
+			YELLOW, applets[blabber].name, NORM,
+			DKBLUE, applets[blabber].opts, NORM,
+			RED, NORM, _(applets[blabber].desc));
+		if (desc)
+			printf("\n%s\n", desc);
 	}
 	if (module_name != NULL)
 		printf("%sLoaded module:%s\n%s%8s%s %s<args>%s\n", GREEN, NORM, YELLOW, module_name, NORM, DKBLUE, NORM);
diff --git a/man/qatom.1 b/man/qatom.1
index 42991a5..4a30343 100644
--- a/man/qatom.1
+++ b/man/qatom.1
@@ -1,9 +1,9 @@
-.TH qatom "1" "Feb 2016" "Gentoo Foundation" "qatom"
+.TH qatom "1" "Mar 2016" "Gentoo Foundation" "qatom"
 .SH NAME
 qatom \- split atom strings
 .SH SYNOPSIS
 .B qatom
-\fI<opts> <pkg>\fR
+\fI[opts] <pkg>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qcache.1 b/man/qcache.1
index 1f46e4b..81ae2fa 100644
--- a/man/qcache.1
+++ b/man/qcache.1
@@ -1,9 +1,9 @@
-.TH qcache "1" "Mar 2014" "Gentoo Foundation" "qcache"
+.TH qcache "1" "Mar 2016" "Gentoo Foundation" "qcache"
 .SH NAME
 qcache \- search the metadata cache
 .SH SYNOPSIS
 .B qcache
-\fI<opts> <action> <args>\fR
+\fI[opts] <action> <args>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qcheck.1 b/man/qcheck.1
index b686662..ed90c86 100644
--- a/man/qcheck.1
+++ b/man/qcheck.1
@@ -1,9 +1,9 @@
-.TH qcheck "1" "Feb 2016" "Gentoo Foundation" "qcheck"
+.TH qcheck "1" "Mar 2016" "Gentoo Foundation" "qcheck"
 .SH NAME
 qcheck \- verify integrity of installed packages
 .SH SYNOPSIS
 .B qcheck
-\fI<opts> <pkgname>\fR
+\fI[opts] <pkgname>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qdepends.1 b/man/qdepends.1
index 3b316a0..a0cac5b 100644
--- a/man/qdepends.1
+++ b/man/qdepends.1
@@ -1,9 +1,9 @@
-.TH qdepends "1" "Mar 2014" "Gentoo Foundation" "qdepends"
+.TH qdepends "1" "Mar 2016" "Gentoo Foundation" "qdepends"
 .SH NAME
 qdepends \- show dependency info
 .SH SYNOPSIS
 .B qdepends
-\fI<opts> <pkgname>\fR
+\fI[opts] <pkgname>\fR
 .SH DESCRIPTION
 The 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
diff --git a/man/qfile.1 b/man/qfile.1
index 54823cd..e57e8e3 100644
--- a/man/qfile.1
+++ b/man/qfile.1
@@ -1,9 +1,9 @@
-.TH qfile "1" "Feb 2016" "Gentoo Foundation" "qfile"
+.TH qfile "1" "Mar 2016" "Gentoo Foundation" "qfile"
 .SH NAME
 qfile \- list all pkgs owning files
 .SH SYNOPSIS
 .B qfile
-\fI<opts> <filename>\fR
+\fI[opts] <filename>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qgrep.1 b/man/qgrep.1
index 1ff4797..e31e45a 100644
--- a/man/qgrep.1
+++ b/man/qgrep.1
@@ -1,9 +1,9 @@
-.TH qgrep "1" "Mar 2014" "Gentoo Foundation" "qgrep"
+.TH qgrep "1" "Mar 2016" "Gentoo Foundation" "qgrep"
 .SH NAME
 qgrep \- grep in ebuilds
 .SH SYNOPSIS
 .B qgrep
-\fI<opts> <misc args>\fR
+\fI[opts] <misc args>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qlist.1 b/man/qlist.1
index eedc2cd..05e9326 100644
--- a/man/qlist.1
+++ b/man/qlist.1
@@ -1,9 +1,9 @@
-.TH qlist "1" "Feb 2016" "Gentoo Foundation" "qlist"
+.TH qlist "1" "Mar 2016" "Gentoo Foundation" "qlist"
 .SH NAME
 qlist \- list files owned by pkgname
 .SH SYNOPSIS
 .B qlist
-\fI<opts> <pkgname>\fR
+\fI[opts] <pkgname>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qlop.1 b/man/qlop.1
index 77cf5ef..f8f0cdd 100644
--- a/man/qlop.1
+++ b/man/qlop.1
@@ -3,7 +3,7 @@
 qlop \- emerge log analyzer
 .SH SYNOPSIS
 .B qlop
-\fI<opts> <pkgname>\fR
+\fI[opts] <pkgname>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qmerge.1 b/man/qmerge.1
index df928f1..f3d80db 100644
--- a/man/qmerge.1
+++ b/man/qmerge.1
@@ -1,9 +1,9 @@
-.TH qmerge "1" "Feb 2016" "Gentoo Foundation" "qmerge"
+.TH qmerge "1" "Mar 2016" "Gentoo Foundation" "qmerge"
 .SH NAME
 qmerge \- fetch and merge binary package
 .SH SYNOPSIS
 .B qmerge
-\fI<opts> <pkgnames>\fR
+\fI[opts] <pkgnames>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qpkg.1 b/man/qpkg.1
index ac99736..8bb098a 100644
--- a/man/qpkg.1
+++ b/man/qpkg.1
@@ -1,9 +1,9 @@
-.TH qpkg "1" "Mar 2014" "Gentoo Foundation" "qpkg"
+.TH qpkg "1" "Mar 2016" "Gentoo Foundation" "qpkg"
 .SH NAME
 qpkg \- manipulate Gentoo binpkgs
 .SH SYNOPSIS
 .B qpkg
-\fI<opts> <misc args>\fR
+\fI[opts] <misc args>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qsearch.1 b/man/qsearch.1
index 7d88c50..5f888ba 100644
--- a/man/qsearch.1
+++ b/man/qsearch.1
@@ -1,9 +1,9 @@
-.TH qsearch "1" "Mar 2014" "Gentoo Foundation" "qsearch"
+.TH qsearch "1" "Mar 2016" "Gentoo Foundation" "qsearch"
 .SH NAME
 qsearch \- search pkgname/desc
 .SH SYNOPSIS
 .B qsearch
-\fI<opts> <regex>\fR
+\fI[opts] <regex>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qsize.1 b/man/qsize.1
index af32869..aa613f8 100644
--- a/man/qsize.1
+++ b/man/qsize.1
@@ -1,9 +1,9 @@
-.TH qsize "1" "Feb 2016" "Gentoo Foundation" "qsize"
+.TH qsize "1" "Mar 2016" "Gentoo Foundation" "qsize"
 .SH NAME
 qsize \- calculate size usage
 .SH SYNOPSIS
 .B qsize
-\fI<opts> <pkgname>\fR
+\fI[opts] <pkgname>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qtbz2.1 b/man/qtbz2.1
index 2ecd77f..b22c70c 100644
--- a/man/qtbz2.1
+++ b/man/qtbz2.1
@@ -1,9 +1,9 @@
-.TH qtbz2 "1" "Mar 2014" "Gentoo Foundation" "qtbz2"
+.TH qtbz2 "1" "Mar 2016" "Gentoo Foundation" "qtbz2"
 .SH NAME
 qtbz2 \- manipulate tbz2 packages
 .SH SYNOPSIS
 .B qtbz2
-\fI<opts> <misc args>\fR
+\fI[opts] <misc args>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/quse.1 b/man/quse.1
index 78f4b5c..e1e6db9 100644
--- a/man/quse.1
+++ b/man/quse.1
@@ -1,9 +1,9 @@
-.TH quse "1" "Mar 2014" "Gentoo Foundation" "quse"
+.TH quse "1" "Mar 2016" "Gentoo Foundation" "quse"
 .SH NAME
 quse \- find pkgs using useflags
 .SH SYNOPSIS
 .B quse
-\fI<opts> <useflag>\fR
+\fI[opts] <useflag>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/man/qxpak.1 b/man/qxpak.1
index 733cad2..dbf36f6 100644
--- a/man/qxpak.1
+++ b/man/qxpak.1
@@ -1,9 +1,9 @@
-.TH qxpak "1" "Mar 2014" "Gentoo Foundation" "qxpak"
+.TH qxpak "1" "Mar 2016" "Gentoo Foundation" "qxpak"
 .SH NAME
 qxpak \- manipulate xpak archives
 .SH SYNOPSIS
 .B qxpak
-\fI<opts> <misc args>\fR
+\fI[opts] <misc args>\fR
 .SH DESCRIPTION
 
 .SH OPTIONS
diff --git a/q.c b/q.c
index 1475f99..6ee9aef 100644
--- a/q.c
+++ b/q.c
@@ -21,7 +21,7 @@ static const char * const q_opts_help[] = {
 	"Module path",
 	COMMON_OPTS_HELP
 };
-#define q_usage(ret) usage(ret, Q_FLAGS, q_long_opts, q_opts_help, lookup_applet_idx("q"))
+#define q_usage(ret) usage(ret, Q_FLAGS, q_long_opts, q_opts_help, NULL, lookup_applet_idx("q"))
 
 static APPLET lookup_applet(const char *applet)
 {
diff --git a/qatom.c b/qatom.c
index acf9fd6..8cdffb1 100644
--- a/qatom.c
+++ b/qatom.c
@@ -21,7 +21,7 @@ static const char * const qatom_opts_help[] = {
 	"Compare two atoms",
 	COMMON_OPTS_HELP
 };
-#define qatom_usage(ret) usage(ret, QATOM_FLAGS, qatom_long_opts, qatom_opts_help, lookup_applet_idx("qatom"))
+#define qatom_usage(ret) usage(ret, QATOM_FLAGS, qatom_long_opts, qatom_opts_help, NULL, lookup_applet_idx("qatom"))
 
 /* Run printf on an atom!  The format field takes the form:
  *  %{keyword}: Always display the field that matches "keyword"
diff --git a/qcache.c b/qcache.c
index 759e50a..222c8ae 100644
--- a/qcache.c
+++ b/qcache.c
@@ -44,7 +44,7 @@ static const char * const qcache_opts_help[] = {
 	"list packages that aren't keyworded on a given arch.",
 	COMMON_OPTS_HELP
 };
-#define qcache_usage(ret) usage(ret, QCACHE_FLAGS, qcache_long_opts, qcache_opts_help, lookup_applet_idx("qcache"))
+#define qcache_usage(ret) usage(ret, QCACHE_FLAGS, qcache_long_opts, qcache_opts_help, NULL, lookup_applet_idx("qcache"))
 
 /********************************************************************/
 /* Structs                                                          */
diff --git a/qcheck.c b/qcheck.c
index 7f8031e..79f52a9 100644
--- a/qcheck.c
+++ b/qcheck.c
@@ -31,7 +31,7 @@ static const char * const qcheck_opts_help[] = {
 	"Undo prelink when calculating checksums",
 	COMMON_OPTS_HELP
 };
-#define qcheck_usage(ret) usage(ret, QCHECK_FLAGS, qcheck_long_opts, qcheck_opts_help, lookup_applet_idx("qcheck"))
+#define qcheck_usage(ret) usage(ret, QCHECK_FLAGS, qcheck_long_opts, qcheck_opts_help, NULL, lookup_applet_idx("qcheck"))
 
 #define qcprintf(fmt, args...) do { if (!state->bad_only) printf(_(fmt), ## args); } while (0)
 
diff --git a/qdepends.c b/qdepends.c
index f5867f8..7337c61 100644
--- a/qdepends.c
+++ b/qdepends.c
@@ -31,7 +31,7 @@ static const char * const qdepends_opts_help[] = {
 	"Pretty format specified depend strings",
 	COMMON_OPTS_HELP
 };
-#define qdepends_usage(ret) usage(ret, QDEPENDS_FLAGS, qdepends_long_opts, qdepends_opts_help, lookup_applet_idx("qdepends"))
+#define qdepends_usage(ret) usage(ret, QDEPENDS_FLAGS, qdepends_long_opts, qdepends_opts_help, NULL, lookup_applet_idx("qdepends"))
 
 static char qdep_name_only = 0;
 
diff --git a/qfile.c b/qfile.c
index 2848129..c6c3664 100644
--- a/qfile.c
+++ b/qfile.c
@@ -27,7 +27,7 @@ static const char * const qfile_opts_help[] = {
 	"Exact match (used with --exclude)",
 	COMMON_OPTS_HELP
 };
-#define qfile_usage(ret) usage(ret, QFILE_FLAGS, qfile_long_opts, qfile_opts_help, lookup_applet_idx("qfile"))
+#define qfile_usage(ret) usage(ret, QFILE_FLAGS, qfile_long_opts, qfile_opts_help, NULL, lookup_applet_idx("qfile"))
 
 #define qfile_is_prefix(path, prefix, prefix_length) \
 	(!prefix_length \
diff --git a/qglsa.c b/qglsa.c
index 885ce1e..6670093 100644
--- a/qglsa.c
+++ b/qglsa.c
@@ -27,7 +27,7 @@ static const char * const qglsa_opts_help[] = {
 	"Mark specified GLSAs as fixed",
 	COMMON_OPTS_HELP
 };
-#define qglsa_usage(ret) usage(ret, QGLSA_FLAGS, qglsa_long_opts, qglsa_opts_help, lookup_applet_idx("qglsa"))
+#define qglsa_usage(ret) usage(ret, QGLSA_FLAGS, qglsa_long_opts, qglsa_opts_help, NULL, lookup_applet_idx("qglsa"))
 
 typedef enum {
 	GLSA_FUNKYTOWN, GLSA_LIST, GLSA_DUMP, GLSA_TEST, GLSA_FIX, GLSA_INJECT
diff --git a/qgrep.c b/qgrep.c
index 7551ebb..73556ee 100644
--- a/qgrep.c
+++ b/qgrep.c
@@ -46,7 +46,7 @@ static const char * const qgrep_opts_help[] = {
 	"Print <arg> lines of trailing context",
 	COMMON_OPTS_HELP
 };
-#define qgrep_usage(ret) usage(ret, QGREP_FLAGS, qgrep_long_opts, qgrep_opts_help, lookup_applet_idx("qgrep"))
+#define qgrep_usage(ret) usage(ret, QGREP_FLAGS, qgrep_long_opts, qgrep_opts_help, NULL, lookup_applet_idx("qgrep"))
 
 char qgrep_name_match(const char*, const int, depend_atom**);
 char qgrep_name_match(const char* name, const int argc, depend_atom** argv)
diff --git a/qlist.c b/qlist.c
index cd52bf0..a5b17af 100644
--- a/qlist.c
+++ b/qlist.c
@@ -40,7 +40,7 @@ static const char * const qlist_opts_help[] = {
 	/* "query filename for pkgname", */
 	COMMON_OPTS_HELP
 };
-#define qlist_usage(ret) usage(ret, QLIST_FLAGS, qlist_long_opts, qlist_opts_help, lookup_applet_idx("qlist"))
+#define qlist_usage(ret) usage(ret, QLIST_FLAGS, qlist_long_opts, qlist_opts_help, NULL, lookup_applet_idx("qlist"))
 
 static char *grab_pkg_umap(q_vdb_pkg_ctx *pkg_ctx)
 {
diff --git a/qlop.c b/qlop.c
index 0da636a..30e9f2f 100644
--- a/qlop.c
+++ b/qlop.c
@@ -35,7 +35,14 @@ static const char * const qlop_opts_help[] = {
 	"Read emerge logfile instead of $EMERGE_LOG_DIR/" QLOP_DEFAULT_LOGFILE,
 	COMMON_OPTS_HELP
 };
-#define qlop_usage(ret) usage(ret, QLOP_FLAGS, qlop_long_opts, qlop_opts_help, lookup_applet_idx("qlop"))
+static const char qlop_desc[] =
+	"The --date option can take a few forms:\n"
+	"  -d '# <day|week|month|year>[s] [ago]'  (e.g. '3 days ago')\n"
+	"Or using strptime(3) formats:\n"
+	"  -d '2015-12-25'           (detected as %F)\n"
+	"  -d '1459101740'           (detected as %s)\n"
+	"  -d '%d.%m.%Y|25.12.2015'  (format is specified)";
+#define qlop_usage(ret) usage(ret, QLOP_FLAGS, qlop_long_opts, qlop_opts_help, qlop_desc, lookup_applet_idx("qlop"))
 
 #define QLOP_LIST    0x01
 #define QLOP_UNLIST  0x02
diff --git a/qmerge.c b/qmerge.c
index 297f939..b734a87 100644
--- a/qmerge.c
+++ b/qmerge.c
@@ -62,7 +62,7 @@ static const char * const qmerge_opts_help[] = {
 	"Run shell funcs with `set -x`",
 	COMMON_OPTS_HELP
 };
-#define qmerge_usage(ret) usage(ret, QMERGE_FLAGS, qmerge_long_opts, qmerge_opts_help, lookup_applet_idx("qmerge"))
+#define qmerge_usage(ret) usage(ret, QMERGE_FLAGS, qmerge_long_opts, qmerge_opts_help, NULL, lookup_applet_idx("qmerge"))
 
 char search_pkgs = 0;
 char interactive = 1;
diff --git a/qpkg.c b/qpkg.c
index 996efcd..2cc658e 100644
--- a/qpkg.c
+++ b/qpkg.c
@@ -25,7 +25,7 @@ static const char * const qpkg_opts_help[] = {
 	"alternate package directory",
 	COMMON_OPTS_HELP
 };
-#define qpkg_usage(ret) usage(ret, QPKG_FLAGS, qpkg_long_opts, qpkg_opts_help, lookup_applet_idx("qpkg"))
+#define qpkg_usage(ret) usage(ret, QPKG_FLAGS, qpkg_long_opts, qpkg_opts_help, NULL, lookup_applet_idx("qpkg"))
 
 extern char pretend;
 
diff --git a/qsearch.c b/qsearch.c
index 2ba2d39..e23642b 100644
--- a/qsearch.c
+++ b/qsearch.c
@@ -29,7 +29,7 @@ static const char * const qsearch_opts_help[] = {
 	"Show homepage info",
 	COMMON_OPTS_HELP
 };
-#define qsearch_usage(ret) usage(ret, QSEARCH_FLAGS, qsearch_long_opts, qsearch_opts_help, lookup_applet_idx("qsearch"))
+#define qsearch_usage(ret) usage(ret, QSEARCH_FLAGS, qsearch_long_opts, qsearch_opts_help, NULL, lookup_applet_idx("qsearch"))
 
 #define LAST_BUF_SIZE 256
 
diff --git a/qsize.c b/qsize.c
index db00247..376a772 100644
--- a/qsize.c
+++ b/qsize.c
@@ -29,7 +29,7 @@ static const char * const qsize_opts_help[] = {
 	"Ignore regexp string",
 	COMMON_OPTS_HELP
 };
-#define qsize_usage(ret) usage(ret, QSIZE_FLAGS, qsize_long_opts, qsize_opts_help, lookup_applet_idx("qsize"))
+#define qsize_usage(ret) usage(ret, QSIZE_FLAGS, qsize_long_opts, qsize_opts_help, NULL, lookup_applet_idx("qsize"))
 
 struct qsize_opt_state {
 	array_t *atoms;
diff --git a/qtbz2.c b/qtbz2.c
index da2e9ab..6e6fff6 100644
--- a/qtbz2.c
+++ b/qtbz2.c
@@ -45,7 +45,7 @@ static const char * const qtbz2_opts_help[] = {
 	"Write files to stdout",
 	COMMON_OPTS_HELP
 };
-#define qtbz2_usage(ret) usage(ret, QTBZ2_FLAGS, qtbz2_long_opts, qtbz2_opts_help, lookup_applet_idx("qtbz2"))
+#define qtbz2_usage(ret) usage(ret, QTBZ2_FLAGS, qtbz2_long_opts, qtbz2_opts_help, NULL, lookup_applet_idx("qtbz2"))
 
 static char tbz2_stdout = 0;
 
diff --git a/quse.c b/quse.c
index 59db37a..81d99d8 100644
--- a/quse.c
+++ b/quse.c
@@ -34,7 +34,7 @@ static const char * const quse_opts_help[] = {
 	"Only show package name",
 	COMMON_OPTS_HELP
 };
-#define quse_usage(ret) usage(ret, QUSE_FLAGS, quse_long_opts, quse_opts_help, lookup_applet_idx("quse"))
+#define quse_usage(ret) usage(ret, QUSE_FLAGS, quse_long_opts, quse_opts_help, NULL, lookup_applet_idx("quse"))
 
 char quse_name_only = 0;
 
diff --git a/qxpak.c b/qxpak.c
index fb19ef9..baceda9 100644
--- a/qxpak.c
+++ b/qxpak.c
@@ -45,7 +45,7 @@ static const char * const qxpak_opts_help[] = {
 	"Write files to stdout",
 	COMMON_OPTS_HELP
 };
-#define qxpak_usage(ret) usage(ret, QXPAK_FLAGS, qxpak_long_opts, qxpak_opts_help, lookup_applet_idx("qxpak"))
+#define qxpak_usage(ret) usage(ret, QXPAK_FLAGS, qxpak_long_opts, qxpak_opts_help, NULL, lookup_applet_idx("qxpak"))
 
 typedef struct {
 	int dir_fd;
diff --git a/template.c b/template.c
index d4b9e98..877a187 100644
--- a/template.c
+++ b/template.c
@@ -15,7 +15,7 @@ static struct option const qtemp_long_opts[] = {
 static const char * const qtemp_opts_help[] = {
 	COMMON_OPTS_HELP
 };
-#define qtemp_usage(ret) usage(ret, QTEMP_FLAGS, qtemp_long_opts, qtemp_opts_help, lookup_applet_idx("qtemp"))
+#define qtemp_usage(ret) usage(ret, QTEMP_FLAGS, qtemp_long_opts, qtemp_opts_help, NULL, lookup_applet_idx("qtemp"))
 
 int qtemp_main(int argc, char **argv)
 {