Feature requests from a new user

"za3k.za3k.com via nullmailer" <[email protected]> Mon, 18 May 2020 00:54:33 -0700
Newsgroups gmane.mail.nullmailer
Message-ID <[email protected]>
Hey, took me a while to set up nullmailer and I had some suggestions to 
streamline things.

1. Defaulting the port to 587 if "--starttls" is enabled might be 
reasonable if this is standard enough, as is done for "--tls"? I think I 
found some erroneous documentation that this was already the case, but I 
can't find it again, sorry.
2. I had a lot of problems with error message "Sending failed: Host or 
network unreachable". It would be good to be more specific. I would 
suggest
  - Including the port in "starting delivery".
  - Give the exact line you can use to reproduce using 'smtp'. Also, 
document that 'smtp' exists.
3. Add a clarification that "tls-anon-auth" is a TLS authentication mode 
unrelated to SMTP, not "TLS authentication + no SMTP authentication". 
This was definitely a dumb mistake on my part, but hey, it will probably 
help someone.
4. Your man pages for nullmailer-send have good explanations and clear 
examples, but it's not organized in a way that's friendly for new users 
(i.e. basically all readers). The problem is that a new user doesn't 
know which man page(s) to read, and how to set up a new system. There is 
no "starting point" to read from, and then read sub-sections as clearly 
needed.

There are too many pointers (cross-references) at each step, with no 
clear pointer to follow: nullmailer(7) points at everything without 
directly telling you how to use or configure the system; sendmail points 
at nullmailer-inject and nullmailer-smtpd; and nullmailer-send, 
nullmailer-queue, and nullmailer-inject contain the actual control 
files, which is what the user is probably looking for.

(I think this is ultimately coming from a desire to write everything in 
exactly one place, one time? Although it's not inherently a problem in 
documentation, I would recommend against when there are multiple 
"documents" which could be read separately, as in this case.)

I think it's most worth re-organizing things so nullmailer(7) is a 
centralized introduction:
- Add what each program does, in one line, so people know what man pages 
to read more about.
- How to configure a new system. That probably means, put information 
about all control files in nullmailer(7), in full detail. Either 
duplicate information to nullmailer(7), or move it to nullmailer(7) and 
have the command-line programs reference nullmailer(7) with a list of 
the options which they use (currently it is vice-versa).
- Possibly, include an entire example configuration, or 
checklist/tutorial of steps to do when setting up a system.

If you'd like, I can write a patch for any/all of the above.