(usage): Add one- and two-line descriptions to --help output.

From Karl.

25 files changed, 45 insertions, 36 deletions

diff --git a/src/basename.c b/src/basename.c
index 0bcc2fe29..b16cf3ce4 100644
--- a/src/basename.c
+++ b/src/basename.c
@@ -52,11 +52,13 @@ usage (status)
   else
     {
       printf ("\
-Usage: %s PATH [SUFFIX]\n\
+Usage: %s NAME [SUFFIX]\n\
   or:  %s OPTION\n\
 ",
 	      program_name, program_name);
       printf ("\
+Print NAME with any leading directory components removed.\n\
+If specified, also remove a trailing SUFFIX.\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/date.c b/src/date.c
index 06da60393..d6980d1e2 100644
--- a/src/date.c
+++ b/src/date.c
@@ -333,6 +333,7 @@ Usage: %s [OPTION]... [+FORMAT]\n\
 ",
 	      program_name, program_name);
       printf ("\
+Display the current time in the given FORMAT, or set the system date.\n\
 \n\
   -d, --date=STRING        display time described by STRING, not `now'\n\
   -f, --file=DATEFILE      like --date once for each line of DATEFILE\n\
diff --git a/src/dirname.c b/src/dirname.c
index e8a0547a8..4386a8744 100644
--- a/src/dirname.c
+++ b/src/dirname.c
@@ -41,11 +41,13 @@ usage (status)
   else
     {
       printf ("\
-Usage: %s PATH\n\
+Usage: %s NAME\n\
   or:  %s OPTION\n\
 ",
 	      program_name, program_name);
       printf ("\
+Print NAME with its trailing /component removed; if NAME contains no /'s,\n\
+output `.' (meaning the current directory).\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/echo.c b/src/echo.c
index 8ba3e83bb..eeafc723c 100644
--- a/src/echo.c
+++ b/src/echo.c
@@ -74,6 +74,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [STRING]...\n", program_name);
       printf ("\
+Echo the STRING(s) to standard output.\n\
 \n\
   -n              do not output the trailing newline\n\
   -e              (unused)\n\
diff --git a/src/env.c b/src/env.c
index 3b75ddce2..6537a3c76 100644
--- a/src/env.c
+++ b/src/env.c
@@ -193,6 +193,7 @@ usage (status)
       printf ("Usage: %s [OPTION]... [-] [NAME=VALUE]... [COMMAND [ARG]...]\n",
 	      program_name);
       printf ("\
+Set each NAME to VALUE in the environment and run COMMAND.\n\
 \n\
   -u, --unset=NAME           remove variable from the environment\n\
   -i, --ignore-environment   start with an empty environment\n\
diff --git a/src/expr.c b/src/expr.c
index 93d240a14..95aba88de 100644
--- a/src/expr.c
+++ b/src/expr.c
@@ -109,7 +109,7 @@ Usage: %s EXPRESSION\n\
 \n\
 ");
       printf ("\
-EXPRESSION value is written on standard output.  A white line\n\
+Print the value of EXPRESSION to standard output.  A blank line below\n\
 separates increasing precedence groups.  EXPRESSION may be:\n\
 \n\
   ARG1 | ARG2       ARG1 if it is neither null nor 0, otherwise ARG2\n\
@@ -141,7 +141,7 @@ separates increasing precedence groups.  EXPRESSION may be:\n\
 ");
       printf ("\
 \n\
-Beware that some operators need to be escaped by backslashes for shells.\n\
+Beware that many operators need to be escaped or quoted for shells.\n\
 Comparisons are arithmetic if both ARGs are numbers, else lexicographical.\n\
 Pattern matches return the string matched between \\( and \\) or null; if\n\
 \\( and \\) are not used, they return the number of characters matched or 0.\n\
diff --git a/src/hostname.c b/src/hostname.c
index f4ccbd83d..ef89bb370 100644
--- a/src/hostname.c
+++ b/src/hostname.c
@@ -64,6 +64,7 @@ usage (status)
       printf ("\
 Usage: %s [NAME]\n\
   or:  %s OPTION\n\
+Print the hostname of the current system.\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/id.c b/src/id.c
index 569b3384b..1d04944a1 100644
--- a/src/id.c
+++ b/src/id.c
@@ -361,6 +361,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [USERNAME]\n", program_name);
       printf ("\
+Print information for USERNAME, or the current user.\n\
 \n\
   -g, --group     print only the group ID\n\
   -G, --groups    print only the supplementary groups\n\
diff --git a/src/logname.c b/src/logname.c
index 6062581a0..916a9896e 100644
--- a/src/logname.c
+++ b/src/logname.c
@@ -50,6 +50,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]...\n", program_name);
       printf ("\
+Print the name of the current user.\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/nice.c b/src/nice.c
index 6f8080334..337c4137b 100644
--- a/src/nice.c
+++ b/src/nice.c
@@ -191,15 +191,14 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [COMMAND [ARG]...]\n", program_name);
       printf ("\
+Run COMMAND with an adjusted scheduling priority.\n\
+With no COMMAND, print the current scheduling priority.  ADJUST is 10\n\
+by default.  Range goes from -20 (highest priority) to 19 (lowest).\n\
 \n\
   -ADJUST                   increment priority by ADJUST first\n\
   -n, --adjustment=ADJUST   same as -ADJUST\n\
       --help                display this help and exit\n\
-      --version             output version information and exit\n\
-\n\
-With no COMMAND, print the current scheduling priority.  ADJUST is 10\n\
-by default.  Range goes from -20 (highest priority) to 19 (lowest).\n\
-");
+      --version             output version information and exit\n");
     }
   exit (status);
 }
diff --git a/src/nohup.sh b/src/nohup.sh
index 87f864d41..0d171e8a1 100755
--- a/src/nohup.sh
+++ b/src/nohup.sh
@@ -28,7 +28,8 @@ usage="Usage: $0 COMMAND [ARG]...
 usage_try="
 Try \`$0 --help' for more information."
 
-usage_help="
+usage_help="Run COMMAND, ignoring hangup signals.
+
   --help      display this help and exit
   --version   output version information and exit"
 
diff --git a/src/pathchk.c b/src/pathchk.c
index c1458f833..fecd610db 100644
--- a/src/pathchk.c
+++ b/src/pathchk.c
@@ -364,8 +364,9 @@ usage (status)
 	     program_name);
   else
     {
-      printf ("Usage: %s [OPTION]... PATH...\n", program_name);
+      printf ("Usage: %s [OPTION]... NAME...\n", program_name);
       printf ("\
+Diagnose unportable constructs in NAME.\n\
 \n\
   -p, --portability   check for all POSIX systems, not only this one\n\
       --help          display this help and exit\n\
diff --git a/src/printenv.c b/src/printenv.c
index 6b248c325..1786f9f35 100644
--- a/src/printenv.c
+++ b/src/printenv.c
@@ -65,12 +65,10 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [VARIABLE]...\n", program_name);
       printf ("\
+If no environment VARIABLE specified, print them all.\n\
 \n\
   --help      display this help and exit\n\
-  --version   output version information and exit\n\
-\n\
-If no VARIABLE, print them all.\n\
-");
+  --version   output version information and exit\n");
     }
   exit (status);
 }
diff --git a/src/printf.c b/src/printf.c
index dc55c41d6..63e40e508 100644
--- a/src/printf.c
+++ b/src/printf.c
@@ -96,6 +96,7 @@ Usage: %s FORMAT [ARGUMENT]...\n\
 ",
 	      program_name, program_name);
       printf ("\
+Print ARGUMENT(s) according to FORMAT.\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/pwd.c b/src/pwd.c
index 7af6beb0f..54c21ad5e 100644
--- a/src/pwd.c
+++ b/src/pwd.c
@@ -42,6 +42,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]\n", program_name);
       printf ("\
+Print the full filename of the current working directory.\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/sleep.c b/src/sleep.c
index 01887c30f..b590befb9 100644
--- a/src/sleep.c
+++ b/src/sleep.c
@@ -53,12 +53,11 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... NUMBER[SUFFIX]\n", program_name);
       printf ("\
+Pause for NUMBER seconds.\n\
+SUFFIX may be s to keep seconds, m for minutes, h for hours or d for days.\n\
 \n\
   --help      display this help and exit\n\
-  --version   output version information and exit\n\
-\n\
-SUFFIX may be s for seconds, m for minutes, h for hours or d for days.\n\
-");
+  --version   output version information and exit\n");
     }
   exit (status);
 }
diff --git a/src/stty.c b/src/stty.c
index 967e4289d..abfa34b25 100644
--- a/src/stty.c
+++ b/src/stty.c
@@ -466,6 +466,7 @@ Usage: %s [SETTING]...\n\
 ",
 	      program_name, program_name);
       printf ("\
+Print or change terminal characteristics.\n\
 \n\
   -a, --all       print all current settings in human-readable form\n\
   -g, --save      print all current settings in a stty-readable form\n\
diff --git a/src/su.c b/src/su.c
index 5ba724f41..a41706a30 100644
--- a/src/su.c
+++ b/src/su.c
@@ -575,8 +575,9 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [-] [USER [ARG]...]\n", program_name);
       printf ("\
+Change the effective user id and group id to that of USER.\n\
 \n\
-  -l, --login                  make the shell a login shell\n\
+  -, -l, --login               make the shell a login shell\n\
   -c, --commmand=COMMAND       pass a single COMMAND to the shell with -c\n\
   -f, --fast                   pass -f to the shell (for csh or tcsh)\n\
   -m, --preserve-environment   do not reset environment variables\n\
diff --git a/src/tee.c b/src/tee.c
index 9cd9118cd..5554d154a 100644
--- a/src/tee.c
+++ b/src/tee.c
@@ -67,6 +67,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [FILE]...\n", program_name);
       printf ("\
+Copy standard input to each FILE, and also to standard output.\n\
 \n\
   -a, --append              append to the given FILEs, do not overwrite\n\
   -i, --ignore-interrupts   ignore interrupt signals\n\
diff --git a/src/test.c b/src/test.c
index ea2d5c580..2ba8585d5 100644
--- a/src/test.c
+++ b/src/test.c
@@ -992,6 +992,7 @@ Usage: %s EXPRESSION\n\
 ",
 	      program_name, program_name);
       printf ("\
+Exit with the status determined by EXPRESSION.\n\
 \n\
   --help      display this help and exit\n\
   --version   output version information and exit\n\
diff --git a/src/tty.c b/src/tty.c
index 66ecb8776..68332a7c2 100644
--- a/src/tty.c
+++ b/src/tty.c
@@ -119,6 +119,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]...\n", program_name);
       printf ("\
+Print the file name of the terminal connected to standard input.\n\
 \n\
   -s, --silent, --quiet   print nothing, only return an exit status\n\
       --help              display this help and exit\n\
diff --git a/src/uname.c b/src/uname.c
index 4e55feebd..e1e9ed006 100644
--- a/src/uname.c
+++ b/src/uname.c
@@ -184,6 +184,7 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]...\n", program_name);
       printf ("\
+Print certain system information.  With no OPTION, same as -s.\n\
 \n\
   -a, --all        print all information\n\
   -m, --machine    print the machine (hardware) type\n\
@@ -192,10 +193,7 @@ usage (status)
   -s, --sysname    print the operating system name\n\
   -v               print the operating system version\n\
       --help       display this help and exit\n\
-      --version    output version information and exit\n\
-\n\
-Without any OPTION, assume -s.\n\
-");
+      --version    output version information and exit\n");
     }
   exit (status);
 }
diff --git a/src/who.c b/src/who.c
index 659b848ac..d10d014ea 100644
--- a/src/who.c
+++ b/src/who.c
@@ -544,12 +544,11 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [ FILE ]\n", program_name);
       printf ("\
+Output who is currently logged in according to FILE.\n\
+If FILE not given, uses /etc/utmp.  /etc/wtmp as FILE is common.\n\
 \n\
       --help        display this help and exit\n\
-      --version     output version information and exit\n\
-\n\
-If FILE not given, uses /etc/utmp.  /etc/wtmp as FILE is common.\n\
-");
+      --version     output version information and exit\n");
     }
   exit (status);
 }
diff --git a/src/whoami.c b/src/whoami.c
index c2f25f0e8..0b4847993 100644
--- a/src/whoami.c
+++ b/src/whoami.c
@@ -54,12 +54,11 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]...\n", program_name);
       printf ("\
+Print the user name associated with the current effective user id.\n\
+Same as id -un.\n\
 \n\
   --help      display this help and exit\n\
-  --version   output version information and exit\n\
-\n\
-Same as id -un.\n\
-");
+  --version   output version information and exit\n");
     }
   exit (status);
 }
diff --git a/src/yes.c b/src/yes.c
index 213dd987c..1293fadb1 100644
--- a/src/yes.c
+++ b/src/yes.c
@@ -38,12 +38,10 @@ usage (status)
     {
       printf ("Usage: %s [OPTION]... [STRING]...\n", program_name);
       printf ("\
+Repeatedly output a line with all specified STRING(s), or `y'.\n\
 \n\
   --help      display this help and exit\n\
-  --version   output version information and exit\n\
-\n\
-Without any STRING, assume `y'.\n\
-");
+  --version   output version information and exit\n");
     }
   exit (status);
 }