From 5bc9b0c3cac34864d479c099283793ec4ae5565e Mon Sep 17 00:00:00 2001
From: Ori Bernstein <ori@eigenstate.org>
Date: Tue, 10 Mar 2020 10:09:34 -0700
Subject: [PATCH] improve usage messages (thanks henesy)

Fix inconsistencies between programs and their usage
messages,  correct instances where information seems
to be missing or lost. This  includes missing arguments,
making usage consistent with manuals, and so on.
---
 rc/bin/approx                   | 2 +-
 rc/bin/doc2txt                  | 2 +-
 rc/bin/doctype                  | 5 +++++
 rc/bin/juke                     | 2 +-
 rc/bin/lookman                  | 2 +-
 rc/bin/lp                       | 2 +-
 rc/bin/man                      | 4 ++--
 rc/bin/psfax                    | 4 ++--
 rc/bin/psu                      | 2 +-
 rc/bin/sig                      | 4 ++--
 rc/bin/ssam                     | 3 ++-
 rc/bin/tap                      | 2 +-
 sys/man/1/mothra                | 5 ++++-
 sys/src/cmd/aan.c               | 2 +-
 sys/src/cmd/auth/httpauth.c     | 2 +-
 sys/src/cmd/awk/main.c          | 2 +-
 sys/src/cmd/bc.y                | 2 +-
 sys/src/cmd/colors.c            | 2 +-
 sys/src/cmd/compress/compress.c | 4 ++--
 sys/src/cmd/db/main.c           | 2 +-
 sys/src/cmd/dict/canonind.awk   | 4 ++--
 sys/src/cmd/dict/dict.c         | 2 +-
 sys/src/cmd/getmap.c            | 2 +-
 sys/src/cmd/mk/main.c           | 2 +-
 sys/src/cmd/mothra/mothra.c     | 2 +-
 sys/src/cmd/ratrace.c           | 2 +-
 sys/src/cmd/sum.c               | 2 +-
 sys/src/cmd/swap.c              | 2 +-
 sys/src/cmd/tcs/font/main.c     | 2 +-
 sys/src/cmd/tcs/font/merge.c    | 2 +-
 sys/src/cmd/tcs/tcs.c           | 2 +-
 sys/src/cmd/trace.c             | 2 +-
 sys/src/cmd/urlencode.c         | 2 +-
 sys/src/cmd/wc.c                | 2 +-
 34 files changed, 47 insertions(+), 38 deletions(-)

diff --git a/rc/bin/approx b/rc/bin/approx
index b790da532..98dc89a5a 100755
--- a/rc/bin/approx
+++ b/rc/bin/approx
@@ -1,6 +1,6 @@
 #!/bin/rc
 if(! ~ $#* 3){
-	echo usage: approx ratio min max
+	echo usage: approx ratio min max >[1=2]
 	exit usage
 }
 echo $1 $2 $3 | awk '
diff --git a/rc/bin/doc2txt b/rc/bin/doc2txt
index 65b68b48e..f01147ebc 100755
--- a/rc/bin/doc2txt
+++ b/rc/bin/doc2txt
@@ -3,7 +3,7 @@
 rfork en
 
 if(! ~ $#* 0 1) {
-	echo 'Usage: doc2txt [file.doc]' >[1=2]
+	echo 'usage: doc2txt [file.doc]' >[1=2]
 	exit usage
 }
 
diff --git a/rc/bin/doctype b/rc/bin/doctype
index 0f04f91ef..5aa6cc300 100755
--- a/rc/bin/doctype
+++ b/rc/bin/doctype
@@ -1,6 +1,11 @@
 #!/bin/rc
 # doctype:  synthesize proper command line for troff
 
+if(~ $#* 0){
+	echo 'usage: doctype [ -n ] [ -T dev ] [ file ] ...' >[1=2]
+	exit usage
+}
+
 troff=troff
 eqn=eqn
 prefer=prefer
diff --git a/rc/bin/juke b/rc/bin/juke
index a661c7f79..6a523d847 100755
--- a/rc/bin/juke
+++ b/rc/bin/juke
@@ -26,7 +26,7 @@ while(! ~ $#* 0) {
 		sname=$2
 		shift
 	case -*
-		echo Usage: classical [-d level] [-t] [-h srvhost]
+		echo usage: juke [-d level] [-tw] [-s srv] [-h srvhost] >[1=2]
 		exit usage
 	}
 	shift
diff --git a/rc/bin/lookman b/rc/bin/lookman
index 5854e9528..e38d16695 100755
--- a/rc/bin/lookman
+++ b/rc/bin/lookman
@@ -16,7 +16,7 @@ fn sigint sighup sigterm {
 
 *=`{echo $*|tr A-Z a-z|tr -dc 'a-z0-9_. \012'}	# fold case, delete funny chars
 if(~ $#* 0){
-	echo Usage: lookman key ... >/fd/2
+	echo usage: lookman key ... >/fd/2
 	exit usage
 }
 look $1 $index | sed 's/.*	//' | sort -u >$t1
diff --git a/rc/bin/lp b/rc/bin/lp
index a06848811..e7eba4e5e 100755
--- a/rc/bin/lp
+++ b/rc/bin/lp
@@ -93,7 +93,7 @@ flagfmt='D,H,L,Q,R,r,q,M mach,c copies,d printer,f font.size,i src,k jobnos,l li
 argv0=lp
 
 if(! ifs=() eval `{aux/getflags $*}) {
-	echo $USAGE
+	echo $USAGE >[1=2]
 	exit usage
 }
 if(~ $flagd '?'){
diff --git a/rc/bin/man b/rc/bin/man
index 042fb1cca..f002c2121 100755
--- a/rc/bin/man
+++ b/rc/bin/man
@@ -59,8 +59,8 @@ fn page {
 search=yes
 while(~ $d 0) {
 	if(~ $#* 0) {
-		echo 'Usage: man [-bntpPSw] [0-9] [0-9] ... name1 name2 ...' >[1=2]
-		exit
+		echo 'usage: man [-bntpPSw] [0-9] [0-9] ... name1 name2 ...' >[1=2]
+		exit usage
 	}
 	if(test -d $S/$1){
 		sec=($sec $1)
diff --git a/rc/bin/psfax b/rc/bin/psfax
index 654f53bfe..d9d197b4a 100755
--- a/rc/bin/psfax
+++ b/rc/bin/psfax
@@ -10,8 +10,8 @@ case -v
 
 switch($#*){
 case 0 1
-	echo usage: $0 telephone-number recipient '[files]'
-	exit 0
+	echo usage: $0 telephone-number recipient '[files]' >[1=2]
+	exit usage
 case 2
 	stdin=yes
 }
diff --git a/rc/bin/psu b/rc/bin/psu
index d9f63fef8..0755a1817 100755
--- a/rc/bin/psu
+++ b/rc/bin/psu
@@ -15,6 +15,6 @@ case 0
 case 1
 	ps $flags | sed -n '/^'$1' /p'
 case *
-	echo Usage: psu '[ps-flags] [ user ]' >[1=2]
+	echo usage: psu '[ps-flags] [ user ]' >[1=2]
 	exit usage
 }
diff --git a/rc/bin/sig b/rc/bin/sig
index 56125ab17..918161641 100755
--- a/rc/bin/sig
+++ b/rc/bin/sig
@@ -5,8 +5,8 @@
 
 *=`{echo $*|tr A-Z a-z|tr -dc 'a-z0-9_ \012'}	# fold case, delete funny chars
 if(~ $#* 0){
-	echo Usage: sig function ... >/fd/2
-	exit 1
+	echo usage: sig function ... >/fd/2
+	exit usage
 }
 
 for (i) {
diff --git a/rc/bin/ssam b/rc/bin/ssam
index dd931893d..a9e32b14e 100755
--- a/rc/bin/ssam
+++ b/rc/bin/ssam
@@ -4,7 +4,8 @@ rfork e
 
 flagfmt='n,e script,f sfile'
 args='[ file ... ]'
-fn usage { echo $0 '[ -n ] [ -e script ] [ -f sfile ] [ file ... ]' >[1=2] }
+argv0=$0
+fn usage { echo usage: $argv0 '[ -n ] [ -e script ] [ -f sfile ] [ file ... ]' >[1=2] }
 if(! ifs=() eval `{aux/getflags $*}){
 	usage
 	exit usage
diff --git a/rc/bin/tap b/rc/bin/tap
index 0cc0d40af..ee40f0b95 100755
--- a/rc/bin/tap
+++ b/rc/bin/tap
@@ -2,7 +2,7 @@
 rfork e
 
 if(~ $#* 0){
-	echo 'Usage: ' $0 '[ pid ... ]' >[1=2]
+	echo 'usage:' $0 '[ pid ... ]' >[1=2]
 	exit usage
 }
 
diff --git a/sys/man/1/mothra b/sys/man/1/mothra
index d9f5c480c..278a42f79 100644
--- a/sys/man/1/mothra
+++ b/sys/man/1/mothra
@@ -4,7 +4,7 @@ mothra \- retrieve and display World-Wide Web files
 .SH SYNOPSIS
 .B mothra
 [
-.B -va
+.B -dvak
 ]
 [
 .B -m
@@ -71,6 +71,9 @@ The default is
 .B -v
 Verbose mode. Causes HTML errors to be printed
 on file-descriptor 2.
+.TP
+.B -d
+Enables debug mode.
 .PP
 The display contains the last message from
 .I mothra,
diff --git a/sys/src/cmd/aan.c b/sys/src/cmd/aan.c
index 7508720f8..2c5bdbe20 100644
--- a/sys/src/cmd/aan.c
+++ b/sys/src/cmd/aan.c
@@ -65,7 +65,7 @@ static void		timerproc(void *);
 static void
 usage(void)
 {
-	fprint(2, "Usage: %s [-cd] [-m maxto] dialstring|netdir\n", argv0);
+	fprint(2, "usage: %s [-cd] [-m maxto] dialstring|netdir\n", argv0);
 	exits("usage");
 }
 
diff --git a/sys/src/cmd/auth/httpauth.c b/sys/src/cmd/auth/httpauth.c
index fc333de93..7d1747bfb 100644
--- a/sys/src/cmd/auth/httpauth.c
+++ b/sys/src/cmd/auth/httpauth.c
@@ -5,7 +5,7 @@
 void
 usage(void)
 {
-	fprint(2, "Usage:\n\t%s user pass\n\t%s authorization\n", argv0, argv0);
+	fprint(2, "usage:\n\t%s user pass\n\t%s authorization\n", argv0, argv0);
 	exits("usage");
 }
 
diff --git a/sys/src/cmd/awk/main.c b/sys/src/cmd/awk/main.c
index e4244e333..74e6401c2 100644
--- a/sys/src/cmd/awk/main.c
+++ b/sys/src/cmd/awk/main.c
@@ -62,7 +62,7 @@ void main(int argc, char *argv[])
 
 	cmdname = argv[0];
 	if (argc == 1) {
-		Bprint(&stderr, "Usage: %s [-F fieldsep] [-mf n] [-mr n] [-v var=value] [-f programfile | 'program'] [file ...]\n", cmdname);
+		Bprint(&stderr, "usage: %s [-F fieldsep] [-d] [-mf n] [-mr n] [-safe] [-v var=value] [-f programfile | 'program'] [file ...]\n", cmdname);
 		exits("usage");
 	}
 
diff --git a/sys/src/cmd/bc.y b/sys/src/cmd/bc.y
index fbbdd15f6..a33e06e7a 100644
--- a/sys/src/cmd/bc.y
+++ b/sys/src/cmd/bc.y
@@ -956,7 +956,7 @@ main(int argc, char **argv)
 			sflag++;
 			break;
 		default:
-			fprint(2, "Usage: bc [-cdls] [file ...]\n");
+			fprint(2, "usage: bc [-cdls] [file ...]\n");
 			exits("usage");
 		}
 		argc--;
diff --git a/sys/src/cmd/colors.c b/sys/src/cmd/colors.c
index d623f4e8c..3267130f5 100644
--- a/sys/src/cmd/colors.c
+++ b/sys/src/cmd/colors.c
@@ -102,7 +102,7 @@ main(int argc, char *argv[])
 
 	if(argc){
 	Usage:
-		fprint(2, "Usage: %s [-rx]\n", argv0);
+		fprint(2, "usage: %s [-rx]\n", argv0);
 		exits("usage");
 	}
 
diff --git a/sys/src/cmd/compress/compress.c b/sys/src/cmd/compress/compress.c
index 2e6e58e44..7db0dfb39 100644
--- a/sys/src/cmd/compress/compress.c
+++ b/sys/src/cmd/compress/compress.c
@@ -112,9 +112,9 @@ code_int getcode();
 Usage()
 {
 #ifdef DEBUG
-	fprintf(stderr,"Usage: compress [-cdfDV] [-b maxbits] [file ...]\n");
+	fprintf(stderr,"usage: compress [-cdfDV] [-b maxbits] [file ...]\n");
 #else
-	fprintf(stderr,"Usage: compress [-cdfvV] [-b maxbits] [file ...]\n");
+	fprintf(stderr,"usage: compress [-cdfvV] [-b maxbits] [file ...]\n");
 #endif /* DEBUG */
 }
 
diff --git a/sys/src/cmd/db/main.c b/sys/src/cmd/db/main.c
index 4c9eb4287..19c01c836 100644
--- a/sys/src/cmd/db/main.c
+++ b/sys/src/cmd/db/main.c
@@ -93,7 +93,7 @@ main(int argc, char **argv)
 		sprint(b2, "/proc/%s/mem", argv[0]);
 		corfil = b2;
 	} else if (argc > 0) {
-		fprint(2, "Usage: db [-kw] [-m machine] [-I dir] [symfile] [pid]\n");
+		fprint(2, "usage: db [-kw] [-m machine] [-I dir] [symfile] [pid]\n");
 		exits("usage");
 	}
 	if (!symfil)
diff --git a/sys/src/cmd/dict/canonind.awk b/sys/src/cmd/dict/canonind.awk
index 41c6ee75f..a10b0810a 100644
--- a/sys/src/cmd/dict/canonind.awk
+++ b/sys/src/cmd/dict/canonind.awk
@@ -1,8 +1,8 @@
 # turn output of mkindex into form needed by dict
 BEGIN {
 	if(ARGC != 2) {
-		print "Usage: awk -F'	' -f canonind.awk rawindex > index"
-		exit 1
+		print "usage: awk -F'	' -f canonind.awk rawindex > index"
+		exit usage
 	}
 	file = ARGV[1]
 	ARGV[1] = ""
diff --git a/sys/src/cmd/dict/dict.c b/sys/src/cmd/dict/dict.c
index d0d8494d9..c689004ef 100644
--- a/sys/src/cmd/dict/dict.c
+++ b/sys/src/cmd/dict/dict.c
@@ -160,7 +160,7 @@ usage(void)
 	int i;
 	char *a, *b;
 
-	Bprint(bout, "Usage: %s [-d dict] [-k] [-c cmd] [word]\n", argv0);
+	Bprint(bout, "usage: %s [-k] [-d dict] [-c cmd] [pattern]\n", argv0);
 	Bprint(bout, "dictionaries (brackets mark dictionaries not present on this system):\n");
 	for(i = 0; dicts[i].name; i++){
 		a = b = "";
diff --git a/sys/src/cmd/getmap.c b/sys/src/cmd/getmap.c
index 3db180160..ad3ad0205 100644
--- a/sys/src/cmd/getmap.c
+++ b/sys/src/cmd/getmap.c
@@ -131,7 +131,7 @@ main(int argc, char *argv[])
 	int fd, id;
 
 	if(argc>2){
-		fprint(2, "Usage: %s colormap\n", argv[0]);
+		fprint(2, "usage: %s colormap\n", argv[0]);
 		exits("usage");
 	}
 	map = "rgbv";
diff --git a/sys/src/cmd/mk/main.c b/sys/src/cmd/mk/main.c
index a81e83753..8997545f2 100644
--- a/sys/src/cmd/mk/main.c
+++ b/sys/src/cmd/mk/main.c
@@ -236,7 +236,7 @@ void
 badusage(void)
 {
 
-	fprint(2, "Usage: mk [-f file] [-n] [-a] [-e] [-t] [-k] [-i] [-d[egp]] [targets ...]\n");
+	fprint(2, "usage: mk [-f file] [-n] [-a] [-e] [-t] [-k] [-i] [-d[egp]] [targets ...]\n");
 	Exit();
 }
 
diff --git a/sys/src/cmd/mothra/mothra.c b/sys/src/cmd/mothra/mothra.c
index 165e65620..9e30836e9 100644
--- a/sys/src/cmd/mothra/mothra.c
+++ b/sys/src/cmd/mothra/mothra.c
@@ -331,7 +331,7 @@ void main(int argc, char *argv[]){
 	switch(argc){
 	default:
 	Usage:
-		fprint(2, "Usage: %s [-dvak] [-m mtpt] [url]\n", argv0);
+		fprint(2, "usage: %s [-dvak] [-m mtpt] [url]\n", argv0);
 		exits("usage");
 	case 0:
 		url=getenv("url");
diff --git a/sys/src/cmd/ratrace.c b/sys/src/cmd/ratrace.c
index 81b2437b1..ae5bfdc5c 100644
--- a/sys/src/cmd/ratrace.c
+++ b/sys/src/cmd/ratrace.c
@@ -156,7 +156,7 @@ writer(int lastpid)
 void
 usage(void)
 {
-	fprint(2, "Usage: ratrace [-c cmd [arg...]] | [pid]\n");
+	fprint(2, "usage: ratrace [-c cmd [arg...]] | [pid]\n");
 	threadexits("usage");
 }
 
diff --git a/sys/src/cmd/sum.c b/sys/src/cmd/sum.c
index 05fb85eb4..396c135ca 100644
--- a/sys/src/cmd/sum.c
+++ b/sys/src/cmd/sum.c
@@ -10,7 +10,7 @@ static char exitstr[ERRMAX];
 void
 usage(void)
 {
-	fprint(2, "Usage: %s [-r5] [files]\n", argv0);
+	fprint(2, "usage: %s [-5r] [file ...]\n", argv0);
 	exits("usage");
 }
 
diff --git a/sys/src/cmd/swap.c b/sys/src/cmd/swap.c
index 8c3211626..8e54b5b21 100644
--- a/sys/src/cmd/swap.c
+++ b/sys/src/cmd/swap.c
@@ -12,7 +12,7 @@ main(int argc, char **argv)
 	} ARGEND;
 
 	if(argc != 1){
-		fprint(2, "Usage: swap file\n");
+		fprint(2, "usage: swap file\n");
 		exits("usage");
 	}
 
diff --git a/sys/src/cmd/tcs/font/main.c b/sys/src/cmd/tcs/font/main.c
index acc3ea3f2..faa208521 100644
--- a/sys/src/cmd/tcs/font/main.c
+++ b/sys/src/cmd/tcs/font/main.c
@@ -82,6 +82,6 @@ main(int argc, char **argv)
 static void
 usage(void)
 {
-	fprint(2, "Usage: %s [-s] from to\n", argv0);
+	fprint(2, "usage: %s [-s] from to\n", argv0);
 	exits("usage");
 }
diff --git a/sys/src/cmd/tcs/font/merge.c b/sys/src/cmd/tcs/font/merge.c
index 35a5db39e..997a22409 100644
--- a/sys/src/cmd/tcs/font/merge.c
+++ b/sys/src/cmd/tcs/font/merge.c
@@ -65,7 +65,7 @@ bitblt(&screen, screen.r.min, b, b->r, S); bflush();sleep(5000);
 static void
 usage(void)
 {
-	fprint(2, "Usage: %s file ...\n", argv0);
+	fprint(2, "usage: %s file ...\n", argv0);
 	exits("usage");
 }
 
diff --git a/sys/src/cmd/tcs/tcs.c b/sys/src/cmd/tcs/tcs.c
index ab6954e78..e3ed46705 100644
--- a/sys/src/cmd/tcs/tcs.c
+++ b/sys/src/cmd/tcs/tcs.c
@@ -96,7 +96,7 @@ main(int argc, char **argv)
 void
 usage(void)
 {
-	fprint(2, "Usage: %s [-slv] [-f cs] [-t cs] [file ...]\n", argv0);
+	fprint(2, "usage: %s [-slcv] [-f ics] [-t ocs] [file ...]\n", argv0);
 	verbose = 1;
 	list();
 	exits("usage");
diff --git a/sys/src/cmd/trace.c b/sys/src/cmd/trace.c
index 4d40db8c5..2678b0ff6 100644
--- a/sys/src/cmd/trace.c
+++ b/sys/src/cmd/trace.c
@@ -124,7 +124,7 @@ char*profdev = "/proc/trace";
 static void
 usage(void)
 {
-	fprint(2, "Usage: %s [-d profdev] [-w] [-v] [-t triggerproc] [processes]\n", argv0);
+	fprint(2, "usage: %s [-d profdev] [-w] [-v] [-t triggerproc] [pid ...]\n", argv0);
 	exits(nil);
 }
 
diff --git a/sys/src/cmd/urlencode.c b/sys/src/cmd/urlencode.c
index 1d10a977f..92488584e 100644
--- a/sys/src/cmd/urlencode.c
+++ b/sys/src/cmd/urlencode.c
@@ -26,7 +26,7 @@ hexdigit(int c)
 void
 usage(void)
 {
-	fprint(2, "Usage: %s [ -d ] [ file ]\n", argv0);
+	fprint(2, "usage: %s [ -d ] [ file ]\n", argv0);
 	exits("usage");
 }
 
diff --git a/sys/src/cmd/wc.c b/sys/src/cmd/wc.c
index c457fe477..7a72e6513 100644
--- a/sys/src/cmd/wc.c
+++ b/sys/src/cmd/wc.c
@@ -28,7 +28,7 @@ main(int argc, char *argv[])
 	case 'b': pbadr++; break;
 	case 'c': pchar++; break;
 	default:
-		fprint(2, "Usage: %s [-lwrbc] [file ...]\n", argv0);
+		fprint(2, "usage: %s [-lwrbc] [file ...]\n", argv0);
 		exits("usage");
 	} ARGEND
 	if(pline+pword+prune+pbadr+pchar == 0) {