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>

10 files changed, 33 insertions, 1 deletions

diff --git a/login-utils/chfn.c b/login-utils/chfn.c
index 2f1b70dc7..ac0a3cbde 100644
--- a/login-utils/chfn.c
+++ b/login-utils/chfn.c
@@ -89,6 +89,10 @@ static void __attribute__((__noreturn__)) usage(FILE *fp)
 {
 	fputs(USAGE_HEADER, fp);
 	fprintf(fp, _(" %s [options] [<username>]\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, fp);
+	fputs(_("Change your finger information.\n"), fp);
+
 	fputs(USAGE_OPTIONS, fp);
 	fputs(_(" -f, --full-name <full-name>  real name\n"), fp);
 	fputs(_(" -o, --office <office>        office number\n"), fp);
diff --git a/login-utils/chsh.c b/login-utils/chsh.c
index 51f575d65..f4455d7e2 100644
--- a/login-utils/chsh.c
+++ b/login-utils/chsh.c
@@ -68,6 +68,10 @@ static void __attribute__((__noreturn__)) usage (FILE *fp)
 {
 	fputs(USAGE_HEADER, fp);
 	fprintf(fp, _(" %s [options] [<username>]\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, fp);
+	fputs(_("Change your login shell.\n"), fp);
+
 	fputs(USAGE_OPTIONS, fp);
 	fputs(_(" -s, --shell <shell>  specify login shell\n"), fp);
 	fputs(_(" -l, --list-shells    print list of shells and exit\n"), fp);
diff --git a/login-utils/last.c b/login-utils/last.c
index bf2c2da32..e646cabf5 100644
--- a/login-utils/last.c
+++ b/login-utils/last.c
@@ -555,6 +555,9 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fprintf(out, _(
 		" %s [options] [<username>...] [<tty>...]\n"), program_invocation_short_name);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Show a listing of last logged in users.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -<number>            how many lines to show\n"), out);
 	fputs(_(" -a, --hostlast       display hostnames in the last column\n"), out);
diff --git a/login-utils/login.c b/login-utils/login.c
index f07358fae..8772068c7 100644
--- a/login-utils/login.c
+++ b/login-utils/login.c
@@ -1190,6 +1190,8 @@ int main(int argc, char **argv)
 		case '?':
 		default:
 			fprintf(stderr, _("Usage: login [-p] [-h <host>] [-H] [[-f] <username>]\n"));
+			fputs(USAGE_SEPARATOR, stderr);
+			fputs(_("Begin a session on the system.\n"), stderr);
 			exit(EXIT_FAILURE);
 		}
 	argc -= optind;
diff --git a/login-utils/lslogins.c b/login-utils/lslogins.c
index 0e99529a9..ef7096aec 100644
--- a/login-utils/lslogins.c
+++ b/login-utils/lslogins.c
@@ -1204,6 +1204,9 @@ 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(_("Display information about known users in the system.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -a, --acc-expiration     display info about passwords expiration\n"), out);
 	fputs(_(" -c, --colon-separate     display data in a format similar to /etc/passwd\n"), out);
diff --git a/login-utils/newgrp.c b/login-utils/newgrp.c
index b1134e941..e674a4feb 100644
--- a/login-utils/newgrp.c
+++ b/login-utils/newgrp.c
@@ -164,6 +164,10 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fprintf(out, USAGE_HEADER);
 	fprintf(out, _(" %s <group>\n"), program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Log in to a new group.\n"), out);
+
 	fprintf(out, USAGE_OPTIONS);
 	fprintf(out, USAGE_HELP);
 	fprintf(out, USAGE_VERSION);
diff --git a/login-utils/nologin.c b/login-utils/nologin.c
index a4fb82db6..3be50ca12 100644
--- a/login-utils/nologin.c
+++ b/login-utils/nologin.c
@@ -21,10 +21,12 @@
 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(_("Politely refuse a login.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
diff --git a/login-utils/sulogin.c b/login-utils/sulogin.c
index f0e88a411..f4d68c488 100644
--- a/login-utils/sulogin.c
+++ b/login-utils/sulogin.c
@@ -821,6 +821,9 @@ static void usage(FILE *out)
 	fprintf(out, _(
 		" %s [options] [tty device]\n"), program_invocation_short_name);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Single-user login.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -p, --login-shell        start a login shell\n"
 		" -t, --timeout <seconds>  max time to wait for a password (default: no limit)\n"
diff --git a/login-utils/utmpdump.c b/login-utils/utmpdump.c
index e1fefc63e..79bdf33a8 100644
--- a/login-utils/utmpdump.c
+++ b/login-utils/utmpdump.c
@@ -297,6 +297,9 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fprintf(out,
 		_(" %s [options] [filename]\n"), program_invocation_short_name);
 
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Dump UTMP and WTMP files in raw format.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -f, --follow         output appended data as the file grows\n"), out);
 	fputs(_(" -r, --reverse        write back dumped data into utmp file\n"), out);
diff --git a/login-utils/vipw.c b/login-utils/vipw.c
index ca90f65fc..668f4d8c4 100644
--- a/login-utils/vipw.c
+++ b/login-utils/vipw.c
@@ -297,6 +297,10 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
 	fprintf(out, " %s\n", program_invocation_short_name);
+
+	fputs(USAGE_SEPARATOR, out);
+	fputs(_("Edit the password or group file.\n"), out);
+
 	fputs(USAGE_OPTIONS, out);
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);