Documentation is usually the last thing to receive any love ...
if it receives much/any at all. In that vein, would it make
sense to focus that "love" on mh-profile(5mh), and then provide
minimal information plus a "see mh-profile entry XYZ" for the man
page portion of any switch that provides a command-line mechanism
for an mh-profile entry that is precisely a duplication? (One
bonus is that there's less sync-ing/harmonizing required across
multiple man pages.)
Bob
On Wed, 10 Mar 2021 03:39:56 -0500 Ken Hornstein <kenh@pobox.com> sez:
Ken: I would not be opposed to documenting this particular
undocumented switch, though I can imagine why it was left
undocumented in the first place.
Well, ABOUT that. While it seems that -client was never
documented, clientname (in mts.conf) was always documented, but
not very well, back in the MH-6.8 days (I thought maybe
clientname did something else, but no ... that's all it ever
did). Now, why was -client undocumented? No idea! The code
has been there for approximately forever and we've just been
bringing it forward. Honestly, I think every switch to every
MH/nmh program warrants SOME kind of documentation, because
otherwise poor schmucks like me are puzzling over it years
later. Yes, put some documentation in for -idanno! Maybe
someone else will make use of it!
And in CASE you're wondering ... -idanno is a special flag used
to communicate annotation information up from post(8) to higher
level programs. It means, "Write annotation information to the
file descriptor given as the argument to -idanno". What that
really means is that if you give post(8) something like
"-idanno 8", then post will write a list of email addresses
that it is sending to, one per line, to whatever is opened on
file descriptor 8. And then ... well, what actually happens
AFTER post(8) does that is kind of complicated and involves
some magic environment variables, and we should really document
that all. It's kind of documented in mh-profile, but not very
well.
--Ken