From: Jim Meyering <jim@meyering.net>
Date: Mon, 15 May 1995 04:53:56 +0000 (+0000)
Subject: (usage): Add one- and two-line descriptions to --help output.
X-Git-Tag: textutils-1_12_1~181
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=635b1b5b6e5c7339a295f6a84b972f048f50fec2;p=thirdparty%2Fcoreutils.git

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

diff --git a/src/basename.c b/src/basename.c
index 0bcc2fe295..b16cf3ce46 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 06da60393f..d6980d1e28 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 e8a0547a8c..4386a87447 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 8ba3e83bb6..eeafc723c1 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 3b75ddce2a..6537a3c76b 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 93d240a144..95aba88de1 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 f4ccbd83da..ef89bb370c 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 569b3384b4..1d04944a1e 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 6062581a0d..916a9896e3 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 6f80803343..337c4137b8 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 87f864d413..0d171e8a17 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 c1458f833f..fecd610db7 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 6b248c325b..1786f9f351 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 dc55c41d6a..63e40e5084 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 7af6beb0f7..54c21ad5e0 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 01887c30fb..b590befb9f 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 967e4289d2..abfa34b253 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 5ba724f41a..a41706a308 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 9cd9118cd5..5554d154a9 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 ea2d5c5800..2ba8585d5a 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 66ecb87761..68332a7c2e 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 4e55feebd5..e1e9ed0061 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 659b848ac5..d10d014ea6 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 c2f25f0e84..0b48479937 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 213dd987c8..1293fadb17 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);
 }