textual: add a docstring to most of the utilities

This adds a concise description of a tool to its usage text.

A first form of this patch was proposed by Steven Honeyman
(see http://www.spinics.net/lists/util-linux-ng/msg09994.html).

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>

11 files changed, 42 insertions, 1 deletions

diff --git a/text-utils/col.c b/text-utils/col.c
index 1218f251a..53f0556d3 100644
--- a/text-utils/col.c
+++ b/text-utils/col.c
@@ -130,6 +130,9 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 		"\nUsage:\n"
 		" %s [options]\n"), program_invocation_short_name);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Filter out reverse line feeds.\n"), out);
+
 	fprintf(out, _(
 		"\nOptions:\n"
 		" -b, --no-backspaces    do not output backspaces\n"
diff --git a/text-utils/colcrt.c b/text-utils/colcrt.c
index c39c8b6f1..31ce52af9 100644
--- a/text-utils/colcrt.c
+++ b/text-utils/colcrt.c
@@ -313,6 +313,10 @@ static void __attribute__ ((__noreturn__)) usage(FILE * out)
 		_("\nUsage:\n"
 		  " %s [options] [file ...]\n"), program_invocation_short_name);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Filter nroff output for CRT previewing.\n"), out);
+
+	fputs(USAGE_OPTIONS, out);
 	fprintf(out,
 		_(" -,  --no-underlining  suppress all underlining\n"
 		  " -2, --half-lines      print all half-lines\n"
diff --git a/text-utils/colrm.c b/text-utils/colrm.c
index 4264fe6b0..431eae0d2 100644
--- a/text-utils/colrm.c
+++ b/text-utils/colrm.c
@@ -59,6 +59,10 @@ static void __attribute__ ((__noreturn__)) usage(FILE * out)
 	fprintf(out, _("\nUsage:\n"
 		       " %s [startcol [endcol]]\n"),
 		       program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Filter out the specified columns.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
diff --git a/text-utils/column.c b/text-utils/column.c
index e583dbafb..60d123123 100644
--- a/text-utils/column.c
+++ b/text-utils/column.c
@@ -90,6 +90,10 @@ static void __attribute__((__noreturn__)) usage(int rc)
 
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options] [<file>...]\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Columnate lists.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -c, --columns <width>    width of output in number of characters\n"), out);
 	fputs(_(" -t, --table              create a table\n"), out);
diff --git a/text-utils/hexdump.c b/text-utils/hexdump.c
index afae33472..9ee5cb7c9 100644
--- a/text-utils/hexdump.c
+++ b/text-utils/hexdump.c
@@ -153,6 +153,10 @@ void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options] <file>...\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Display file contents in hexadecimal, decimal, octal, or ascii.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -b, --one-byte-octal      one-byte octal display\n"), out);
 	fputs(_(" -c, --one-byte-char       one-byte character display\n"), out);
diff --git a/text-utils/line.c b/text-utils/line.c
index 80daa3476..9384b5c6c 100644
--- a/text-utils/line.c
+++ b/text-utils/line.c
@@ -28,6 +28,10 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options]\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Read one line.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
diff --git a/text-utils/more.c b/text-utils/more.c
index 5c484575b..74148a7ab 100644
--- a/text-utils/more.c
+++ b/text-utils/more.c
@@ -317,6 +317,10 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options] <file>...\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("A file perusal filter for CRT viewing.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -d          display help instead of ringing bell\n"), out);
 	fputs(_(" -f          count logical rather than screen lines\n"), out);
diff --git a/text-utils/pg.c b/text-utils/pg.c
index 9ada00c26..998010ad2 100644
--- a/text-utils/pg.c
+++ b/text-utils/pg.c
@@ -222,6 +222,10 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fprintf(out,
 		_(" %s [options] [+line] [+/pattern/] [files]\n"),
 		program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Browse pagewise through text files.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -number      lines per page\n"), out);
 	fputs(_(" -c           clear screen before displaying\n"), out);
diff --git a/text-utils/rev.c b/text-utils/rev.c
index bda31d2d8..cb3848241 100644
--- a/text-utils/rev.c
+++ b/text-utils/rev.c
@@ -76,6 +76,10 @@ static void __attribute__ ((__noreturn__)) usage(FILE * out)
 {
 	fprintf(out, _("Usage: %s [options] [file ...]\n"),
 		program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Reverse lines characterwise.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
diff --git a/text-utils/tailf.c b/text-utils/tailf.c
index bd38da274..cf22a1e5f 100644
--- a/text-utils/tailf.c
+++ b/text-utils/tailf.c
@@ -198,6 +198,9 @@ static void __attribute__ ((__noreturn__)) usage(FILE *out)
 		  " %s [option] file\n"),
 		program_invocation_short_name);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Follow the growth of a log file.\n"), out);
+
 	fprintf(out, _(
 		"\nOptions:\n"
 		" -n, --lines NUMBER  output the last NUMBER lines\n"
diff --git a/text-utils/ul.c b/text-utils/ul.c
index 20a05514a..30cad791d 100644
--- a/text-utils/ul.c
+++ b/text-utils/ul.c
@@ -134,8 +134,11 @@ usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options] [<file> ...]\n"), program_invocation_short_name);
-	fputs(USAGE_OPTIONS, out);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Do underlining.\n"), out);
+
+	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -t, -T, --terminal TERMINAL  override the TERM environment variable\n"), out);
 	fputs(_(" -i, --indicated              underlining is indicated via a separate line\n"), out);
 	fputs(USAGE_SEPARATOR, out);