As I've updated the online MH book (http://www.ics.uci.edu/~mh/book/) for nmh-1.0, I've noticed some things in nmh documentation that might be changed in the next releases: --------------------------------------------------------------------------- 1) The nmh INSTALL file mentions the print edition of the book. But since that is out of print and may be hard for people to get, how about adding the URL to that section of the online book? Here's a patch: --- INSTALL Sun Jan 24 00:35:06 1999 +++ /tmp/INSTALL.new Sun Feb 14 14:32:51 1999 @@ -107,7 +107,8 @@ If you have specialized programs to handle various types, you will need to edit the `mhn.defaults' file manually. The syntax of this file is described in the man page for `mhn', and in section 9.4 of the book - "MH & xmh: Email for Users and Programmers", 3rd edition, by Jerry Peek. + "MH & xmh: Email for Users and Programmers", 3rd edition, by Jerry Peek, + on the Internet at <http://www.ics.uci.edu/~mh/book/mh/confmhn.htm>. 9) Add an optional global mh.profile, if desired. This profile should be placed in the nmh `etc' directory with the name `mh.profile'. This --------------------------------------------------------------------------- 2) I think that the whatnow(1) manpage should have a note in the BUGS section to explain this. The behavior has been going on as long as I can remember; I think I reported it a year or two ago as a bug, but maybe Richard didn't think it needed changing in the code. Maybe he thought it would be more of a pain than a benefit? I could agree. Still, it's puzzling and (IMO) worth documenting. If the buildmimeproc script returns a nonzero status to signal that something went wrong during MIME processing, whatnow doesn't say so: it simply gives another "What now?" prompt, like always: What now? mime What now? whatnow is depending on the buildmimeproc to print some kind of error message. Is this a good assumption? When I send the draft, the recipient will get a message full of mhbuild directives. At least there's a sign when the buildmimeproc is called as an automimeproc (when you type "send" or "push"): What now? send What now? But there's still no clue why the message wasn't sent. Here's a patch to the manpage: --- whatnow.man Fri Jan 15 17:09:17 1999 +++ /tmp/whatnow.man Fri Feb 19 02:13:24 1999 @@ -129,6 +129,10 @@ If the initial edit fails, \fIwhatnow\fR deletes your draft (by renaming it with a leading comma); failure of a later edit preserves the draft. +If the \fIbuildmimeproc\fR fails (returns a nonzero status), \fIwhatnow\fR +simply prints a \*(lqWhat now?\*(rq prompt. \fIwhatnow\fR depends on the +\fIbuildmimeproc\fR to tell the user that something went wrong. + If \fIwhatnowproc\fR is \fIwhatnow\fR, then \fIcomp\fR, \fIdist\fP, \fIforw\fP, and \fIrepl\fP use a built\-in \fIwhatnow\fR, and do not actually run the \fIwhatnow\fR program. Hence, if you define your own --------------------------------------------------------------------------- 3) The packf(1) manpage has a small typo. I also think that it should explain how MMDF-style delimiters are generated; this is non-obvious, and the required header fields (Return-Path: and X-Envelope-From:) aren't documented in any other manpage (as far as I can tell!). (The MAIL.FILTERING file does mention X-Envelope-From:, but I'm not sure all nmh users will know to look in the source tree for that info.) Here's a patch: --- packf.man Fri Feb 13 08:52:08 1998 +++ /tmp/packf.man Sat Feb 20 20:47:48 1999 @@ -31,13 +31,19 @@ mmdf style delimiters. Each message in the file is separated by four CTRL\-A's and a newline. -You may specify the name of the file in which to use with the -`\-file\ name' switch. If you do specify the name of the file, it -will default to `msgbox'. +You may specify the output filename with the `\-file\ name' switch. +Without `\-file', the default filename is `msgbox'. If the given file name points to an existing file, then the specified messages will be appended to the end of the file, otherwise the file will be created and the messages appended. + +\fIpackf\fR makes an mbox-style delimiter by examining the first line +of the message. If the first line is a \*(lqReturn-Path:\*(rq +field, its address and the current date and time are used. Otherwise, +if the first line has an \*(lqX-Envelope-From:\*(rq field, its +contents (which should already be in the correct format) are used. +Otherwise, a dummy address and the current date and time are used. Messages that are packed by \fIpackf\fR can be unpacked using \fIinc\fR. --------------------------------------------------------------------------- 4) The mhshow -verbose and -noverbose switches are documented in the mhshow(1) manpage synposis, but nowhere else. They're accepted by the code, but they don't seem (?) to do anything. I checked uip/mhshow.c and didn't see anywhere that their values are actually used. Same goes for mhstore. (There's an mhLIST -verbose example in the mhstore manpage, nothing else.) If they're there for future use, maybe that should be documented? Otherwise, should they be removed from manpages (and maybe the code)? --------------------------------------------------------------------------- Overall, IMO, mhn documentation is a lot better than the MH docs were. Jerry
