From 880ff2a4f8f33fede426b21858dda31b58ffd27a Mon Sep 17 00:00:00 2001
From: David Levine <levinedl@acm.org>
Date: Mon, 26 Sep 2016 12:07:50 -0400
Subject: [PATCH] Reworked BUGS section of nmh(7) man page, and added excerpt
 to end of each -help message and to end of install-mh output.

---
 etc/sendfiles               | 12 ++++++++--
 h/prototypes.h              |  1 +
 man/nmh.man                 | 30 +++++++++++++----------
 sbr/print_help.c            | 47 ++++++++++++++++++++++++++++++++++++-
 test/ali/test-ali           |  5 ++--
 test/anno/test-anno         |  3 ++-
 test/dist/test-dist         |  3 ++-
 test/folder/test-packf      |  3 ++-
 test/folder/test-sortm      |  3 ++-
 test/format/test-dp         |  3 ++-
 test/format/test-fmtdump    |  5 ++--
 test/mhfixmsg/test-mhfixmsg |  3 ++-
 test/mhical/test-mhical     |  3 ++-
 test/mhmail/test-mhmail     |  5 ++--
 test/mhparam/test-mhparam   |  5 ++--
 test/mhpath/test-mhpath     |  5 ++--
 test/mkstemp/test-mkstemp   |  5 ++--
 test/post/test-sendfiles    |  3 ++-
 test/prompter/test-prompter |  5 ++--
 test/rcv/test-rcvdist       |  3 ++-
 test/rcv/test-rcvpack       |  3 ++-
 test/rcv/test-rcvstore      |  5 ++--
 test/rcv/test-rcvtty        |  3 ++-
 test/repl/test-repl         |  5 ++--
 test/slocal/test-slocal     |  3 ++-
 uip/install-mh.c            |  4 ++++
 uip/mhmail                  |  9 ++++++-
 27 files changed, 138 insertions(+), 46 deletions(-)

diff --git a/etc/sendfiles b/etc/sendfiles
index 85e8a49a..b844a1e0 100755
--- a/etc/sendfiles
+++ b/etc/sendfiles
@@ -32,8 +32,16 @@ finddir() {
   esac
 }
 
+help() {
+  printf '%s\n' "$usage"
+  #### Print the nmh intro text.
+  ${nmhbindir}/mhparam -help | sed -n -e '/^$/,$p'
+  exit
+}
+
 die() {
-  printf '%s\n' "$usage"; exit ${1:-1}
+  printf '%s\n' "$usage"
+  exit ${1:-1}
 }
 
 bindir=`finddir $0`
@@ -61,7 +69,7 @@ for arg in "$@"; do
     -f|-fr|-fro|-from) fromarg=1 ;;
     #### Support -gzip for backward compatibility.
     -gzip) compress=gzip ;;
-    -h|-he|-hel|-help) die 0 ;;
+    -h|-he|-hel|-help) help ;;
     #### Support -none for backward compatibility.
     -none) compress=none ;;
     -s|-su|-sub|-subj|-subje|-subjec|-subject) subjectarg=1 ;;
diff --git a/h/prototypes.h b/h/prototypes.h
index bc5b6a56..a44ccbf5 100644
--- a/h/prototypes.h
+++ b/h/prototypes.h
@@ -315,6 +315,7 @@ int pidwait (pid_t, int);
 int pidstatus (int, FILE *, char *);
 char *pluspath(char *);
 void print_help (char *, struct swit *, int);
+void print_intro (FILE *, int);
 void print_sw (const char *, const struct swit *, char *, FILE *);
 void print_version (char *);
 void push (void);
diff --git a/man/nmh.man b/man/nmh.man
index cf143305..fd187089 100644
--- a/man/nmh.man
+++ b/man/nmh.man
@@ -1,4 +1,4 @@
-.TH NMH %manext7% "April 21, 2014" "%nmhversion%"
+.TH NMH %manext7% "September 26, 2016" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -134,12 +134,12 @@ ambiguity with any switches that may be added in the future, it is
 recommended that full switch names be used in durable code such as
 shell scripts, functions, and aliases.
 .PP
-All the
+Each
 .B nmh
-commands may be run with the single switch
+command may be run with the single switch
 .BR \-help ,
-which causes them to print a list of the switches they may be invoked
-with and then exit.
+which causes it to print its available switches, along with any
+profile components that apply, and then exit.
 .PP
 All the
 .B nmh
@@ -550,14 +550,21 @@ The user's nmh profile
 .IR mh-mime (7)
 .ne 4
 .SH BUGS
+\" The contents of this section also appear in sbr/print_help.c .
+Send bug reports, questions, suggestions, and patches to
+.IR nmh-workers@nongnu.org .
+That mailing list is relatively quiet, so user questions are encouraged.
+Users are also encouraged to subscribe, and view the archives, at
+https://lists.gnu.org/mailman/listinfo/nmh-workers .
+.PP
 If problems are encountered with an
 .B nmh
-program, the problems should
+program, they should
 be reported to the local maintainers of
-.BR nmh .
-When doing this, the
-name of the program should be reported, along with the version information
-for the program.
+.BR nmh ,
+if any, or to the mailing list noted above.
+When doing this, the name of the program should be reported, along
+with the version information for the program.
 .PP
 To find out what version of an
 .B nmh
@@ -570,5 +577,4 @@ the version of
 the host it was compiled on, and the date the
 program was linked.
 .PP
-Send bug reports and suggestions to
-.IR nmh-workers@nongnu.org .
+New releases and other information of potential interest are announced at http://www.nongnu.org/nmh/ .
diff --git a/sbr/print_help.c b/sbr/print_help.c
index e045788c..6853caa2 100644
--- a/sbr/print_help.c
+++ b/sbr/print_help.c
@@ -26,6 +26,51 @@ print_help (char *str, struct swit *swp, int print_context)
     /*
      * check if we should print any profile entries
      */
-    if (print_context && (s = context_find (invo_name)))
+    if (print_context && (s = context_find (invo_name))) {
 	printf ("\nProfile: %s\n", s);
+    }
+
+    /* and for further info */
+    puts ("");
+    print_intro (stdout, TRUE);
+    puts ("\nSee the BUGS section the nmh(7) man page for more information.");
+}
+
+
+/*
+ * The text below also appears in man/nmh.man.
+ */
+
+static const char nmh_intro1[] = \
+"Send bug reports, questions, suggestions, and patches to nmh-\n"
+"workers@nongnu.org.  That mailing list is relatively quiet, so user\n"
+"questions are encouraged.  Users are also encouraged to subscribe, and\n"
+"view the archives, at https://lists.gnu.org/mailman/listinfo/nmh-\n"
+"workers .\n";
+
+/* The text below is split so that string constant length doesn't
+   exceed the C90 minimum maximum length of 509 characters. */
+static const char nmh_intro2[] = \
+"\n" \
+"If problems are encountered with an nmh program, they should be\n"
+"reported to the local maintainers of nmh, if any, or to the mailing\n"
+"list noted above.  When doing this, the name of the program should be\n"
+"reported, along with the version information for the program.\n";
+
+static const char nmh_intro3[] = \
+"\n"
+"To find out what version of an nmh program is being run, invoke the\n"
+"program with the -version switch.  This prints the version of nmh, the\n"
+"host it was compiled on, and the date the program was linked.\n"
+"\n"
+"New releases and other information of potential interest are announced\n"
+"at http://www.nongnu.org/nmh/ .\n";
+
+void
+print_intro (FILE *file, int brief) {
+    fputs (nmh_intro1, file);
+    if (! brief) {
+        fputs (nmh_intro2, file);
+        fputs (nmh_intro3, file);
+    }
 }
diff --git a/test/ali/test-ali b/test/ali/test-ali
index 5dda0e5b..6cd9d053 100755
--- a/test/ali/test-ali
+++ b/test/ali/test-ali
@@ -37,8 +37,9 @@ Usage: ali [switches] aliases ...
   -help
 EOF
 
-ali -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+ali -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `ali -v` in
diff --git a/test/anno/test-anno b/test/anno/test-anno
index a9ad95ae..6d45cacf 100755
--- a/test/anno/test-anno
+++ b/test/anno/test-anno
@@ -39,7 +39,8 @@ Usage: anno [+folder] [msgs] [switches]
   -([no]p)reserve
 EOF
 
-run_prog anno -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog anno -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/dist/test-dist b/test/dist/test-dist
index 5c10b17e..fd0df96a 100755
--- a/test/dist/test-dist
+++ b/test/dist/test-dist
@@ -71,7 +71,8 @@ Usage: dist [+folder] [msg] [switches]
   -[no]atfile
 EOF
 
-dist -help >"$actual" 2>&1
+#### Skip nmh intro text.
+dist -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/folder/test-packf b/test/folder/test-packf
index ff98cef5..91c4cb51 100755
--- a/test/folder/test-packf
+++ b/test/folder/test-packf
@@ -31,7 +31,8 @@ Usage: packf [+folder] [msgs] [switches]
   -help
 EOF
 
-packf -help >"$actual" 2>&1
+#### Skip nmh intro text.
+packf -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/folder/test-sortm b/test/folder/test-sortm
index eef5c8a5..331eae7d 100755
--- a/test/folder/test-sortm
+++ b/test/folder/test-sortm
@@ -37,7 +37,8 @@ Usage: sortm [+folder] [msgs] [switches]
   -help
 EOF
 
-run_prog sortm -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog sortm -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/format/test-dp b/test/format/test-dp
index b190d733..2c5b9960 100755
--- a/test/format/test-dp
+++ b/test/format/test-dp
@@ -36,7 +36,8 @@ Usage: dp [switches] dates ...
   -help
 EOF
 
-run_prog $dp -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog "$dp" -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/format/test-fmtdump b/test/format/test-fmtdump
index 73fd14de..5c822db3 100755
--- a/test/format/test-fmtdump
+++ b/test/format/test-fmtdump
@@ -35,8 +35,9 @@ Usage: fmtdump [switches]
   -help
 EOF
 
-$fmtdump -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+"$fmtdump" -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `$fmtdump -v` in
diff --git a/test/mhfixmsg/test-mhfixmsg b/test/mhfixmsg/test-mhfixmsg
index 81d47966..fb9b9450 100755
--- a/test/mhfixmsg/test-mhfixmsg
+++ b/test/mhfixmsg/test-mhfixmsg
@@ -70,7 +70,8 @@ Usage: mhfixmsg [+folder] [msgs] [switches]
   -help
 EOF
 
-run_prog mhfixmsg -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog mhfixmsg -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 
diff --git a/test/mhical/test-mhical b/test/mhical/test-mhical
index fb802508..af75cf87 100755
--- a/test/mhical/test-mhical
+++ b/test/mhical/test-mhical
@@ -46,7 +46,8 @@ Usage: mhical [switches]
   -help
 EOF
 
-run_prog mhical -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog mhical -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 
diff --git a/test/mhmail/test-mhmail b/test/mhmail/test-mhmail
index ff9fd40b..4d127e4e 100755
--- a/test/mhmail/test-mhmail
+++ b/test/mhmail/test-mhmail
@@ -88,8 +88,9 @@ Usage: mhmail [-t(o)] addrs ... [switches]
   mhmail with no arguments is equivalent to inc
 EOF
 
-mhmail -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+mhmail -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 
 # check -version
diff --git a/test/mhparam/test-mhparam b/test/mhparam/test-mhparam
index 29dd11f3..72cb3976 100755
--- a/test/mhparam/test-mhparam
+++ b/test/mhparam/test-mhparam
@@ -33,8 +33,9 @@ Usage: mhparam [profile-components] [switches]
   -(debug)
 EOF
 
-mhparam -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+mhparam -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `mhparam -v` in
diff --git a/test/mhpath/test-mhpath b/test/mhpath/test-mhpath
index a4b621b7..cf2ab5d7 100755
--- a/test/mhpath/test-mhpath
+++ b/test/mhpath/test-mhpath
@@ -28,8 +28,9 @@ Usage: mhpath [+folder] [msgs] [switches]
   -help
 EOF
 
-run_prog mhpath -help > $actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+run_prog mhpath -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `mhpath -v` in
diff --git a/test/mkstemp/test-mkstemp b/test/mkstemp/test-mkstemp
index 084f649a..94ce0567 100755
--- a/test/mkstemp/test-mkstemp
+++ b/test/mkstemp/test-mkstemp
@@ -47,8 +47,9 @@ else
 	EOF
 fi
 
-$mkstemp -h >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+run_prog $mkstemp -h | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 
 # check -version
diff --git a/test/post/test-sendfiles b/test/post/test-sendfiles
index 64bf2696..64ccd5e0 100755
--- a/test/post/test-sendfiles
+++ b/test/post/test-sendfiles
@@ -89,7 +89,8 @@ Usage: sendfiles [switches] -to recipient -subject subject file1 [file2 ...]
   Can use PERSON environment variable instead of -from switch.
 EOF
 
-run_prog sendfiles -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog sendfiles -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/prompter/test-prompter b/test/prompter/test-prompter
index 9a25bc06..704f9986 100755
--- a/test/prompter/test-prompter
+++ b/test/prompter/test-prompter
@@ -35,8 +35,9 @@ Usage: prompter [switches] file
   -help
 EOF
 
-run_prog prompter -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+run_prog prompter -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `prompter -v` in
diff --git a/test/rcv/test-rcvdist b/test/rcv/test-rcvdist
index eca96860..720b1bfe 100755
--- a/test/rcv/test-rcvdist
+++ b/test/rcv/test-rcvdist
@@ -32,7 +32,8 @@ Usage: rcvdist [switches] [switches for postproc] address ...
   -help
 EOF
 
-run_prog $rcvdist -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog "$rcvdist" -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/rcv/test-rcvpack b/test/rcv/test-rcvpack
index 958504c6..15272af7 100755
--- a/test/rcv/test-rcvpack
+++ b/test/rcv/test-rcvpack
@@ -33,7 +33,8 @@ Usage: rcvpack [switches] file
   -help
 EOF
 
-run_prog $rcvpack -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog "$rcvpack" -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/rcv/test-rcvstore b/test/rcv/test-rcvstore
index 9656f373..0f0ab0fe 100755
--- a/test/rcv/test-rcvstore
+++ b/test/rcv/test-rcvstore
@@ -38,8 +38,9 @@ Usage: rcvstore [+folder] [switches]
   -help
 EOF
 
-run_prog $rcvstore -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+run_prog "$rcvstore" -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `$rcvstore -v` in
diff --git a/test/rcv/test-rcvtty b/test/rcv/test-rcvtty
index f0e6558f..800d0fba 100755
--- a/test/rcv/test-rcvtty
+++ b/test/rcv/test-rcvtty
@@ -37,7 +37,8 @@ Usage: rcvtty [command ...]
   -help
 EOF
 
-run_prog $rcvtty -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog "$rcvtty" -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/test/repl/test-repl b/test/repl/test-repl
index 20bb96d7..6beea72a 100755
--- a/test/repl/test-repl
+++ b/test/repl/test-repl
@@ -55,8 +55,9 @@ Usage: repl: [+folder] [msg] [switches]
   -nofmtproc
 EOF
 
-run_prog repl -help >$actual 2>&1
-check $expected $actual
+#### Skip nmh intro text.
+run_prog repl -help | sed '/^$/Q' >"$actual" 2>&1
+check "$expected" "$actual"
 
 # check -version
 case `repl -v` in
diff --git a/test/slocal/test-slocal b/test/slocal/test-slocal
index 3fb73b24..800a16f9 100755
--- a/test/slocal/test-slocal
+++ b/test/slocal/test-slocal
@@ -42,7 +42,8 @@ Usage: slocal [switches]
   -help
 EOF
 
-run_prog $slocal -help >"$actual" 2>&1
+#### Skip nmh intro text.
+run_prog $slocal -help | sed '/^$/Q' >"$actual" 2>&1
 check "$expected" "$actual"
 
 # check -version
diff --git a/uip/install-mh.c b/uip/install-mh.c
index 627c48e2..b3271159 100644
--- a/uip/install-mh.c
+++ b/uip/install-mh.c
@@ -219,6 +219,10 @@ query:
 	    fprintf (out, "%s: %s\n", np->n_name, np->n_field);
     }
     fclose (out);
+
+    puts ("\nPlease see the nmh(7) man page for an introduction to nmh.\n");
+    print_intro (stdout, FALSE);
+
     done (0);
     return 1;
 }
diff --git a/uip/mhmail b/uip/mhmail
index c43f9c3f..27695709 100755
--- a/uip/mhmail
+++ b/uip/mhmail
@@ -48,6 +48,13 @@ finddir() {
   esac
 }
 
+help() {
+  printf '%s\n' "$usage"
+  #### Print the nmh intro text.
+  ${nmhbindir}/mhparam -help | sed -n -e '/^$/,$p'
+  exit
+}
+
 #### Convenience function to allow concise code below.
 die() {
     [ $# -gt 0 ]  &&  printf '%s\n' "$1" >&2
@@ -127,7 +134,7 @@ for arg in "$@"; do
     -f|-fr|-fro|-from) mhmailswitch=1; fromarg=1 ;;
     -hea|-head|-heade|-header|-headerf|-headerfi|-headerfie|-headerfiel|\
 -headerfield) mhmailswitch=1; headerfieldarg=1 ;;
-    -hel|-help) printf '%s\n' "$usage"; exit ;;
+    -hel|-help) help ;;
     -nose|-nosen|-nosend) mhmailswitch=1; sendsw=0 ;;
     -p|-pr|-pro|-prof|-profi|-profil|-profile) mhmailswitch=1; use_send=1 ;;
     -resend) die 'mhmail: did you mean -resent instead of -resend?' ;;
-- 
2.56.0