bug#39639: 26.3; Sending Mail Manual is a mess between Message/Mail mode

[Allen Li]

This bug applies to 26.3 and master as of right now.

The way sending mail works and is documented is a mess due to the
Message mode and Mail mode split.

I'll try to point out a few of the problems here:

1. The distinction between message and mail mode is not clearly
explained in the manual.

That's partly incorrectly, the manual does cover it AT THE END of the
Sending Mail section, which is not very useful.  The entire preceding
section flips back and forth between talking about message and mail
mode.

2. The way send-mail-function and message-send-mail-function work is
Lovecraftian.

The docstrings for both of them claim to control sending mail.  The
docstrings for both of them point to the other one.

As best as I can tell, send-mail-function is used by mail mode, and
message-send-mail-function is used by message mode.

Message mode is the default now, and the manual mostly documents message
mode, but it also only documents send-mail-function.

The default value of message-send-mail-function is inferred from
send-mail-function when it is first defined.  Unfortunately, it doesn't
work properly when send-mail-function is customized, I think due to the
order in which the respective libraries are loaded (I haven'te debugged
yet).

The default value of message-send-mail-function is set to
sendmail-query-once if send-mail-function is also set to
sendmail-query-once.  Unfortunately, sendmail-query-once only sets
send-mail-function and not message-send-mail-function, so if you use
message mode (the default), then the default is to query every single
time.  So much for "query once".

message-send-mail-function should then be inferred from
send-mail-function on the next startup, but due to the load order issue
mentioned above, this also doesn't work.

I have attached two patches improving the situation ever so slightly,
but more work is needed here.

0001-Fix-reference-to-message-send-and-exit.patch
Description: Text Data

0002-Document-message-send-mail-function.patch
Description: Text Data

In GNU Emacs 26.3 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.10)
 of 2019-08-29 built on juergen
Windowing system distributor 'The X.Org Foundation', version 11.0.12007000
System Description:     Arch Linux