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

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

[Allen Li]

[-- Attachment #1: Type: text/plain, Size: 1878 bytes --]

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-reference-to-message-send-and-exit.patch --]
[-- Type: text/x-patch, Size: 1124 bytes --]

From 6c8921957979c22195732954a95a97c4913d0eae Mon Sep 17 00:00:00 2001
From: Allen Li <darkfeline@felesatra.moe>
Date: Sun, 16 Feb 2020 23:45:05 -0800
Subject: [PATCH 1/2] Fix reference to message-send-and-exit

Most of the manual here addresses Message mode, and C-c C-c directly
above cites the Message mode command, not the Mail mode command.

* doc/emacs/sending.texi (Mail Sending): Fix reference
---
 doc/emacs/sending.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index 283a59a291..246d6052e0 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -340,7 +340,7 @@ Mail Sending
 @findex message-send
 @vindex message-kill-buffer-on-exit
   The usual command to send a message is @kbd{C-c C-c}
-(@code{mail-send-and-exit}).  This sends the message and then
+(@code{message-send-and-exit}).  This sends the message and then
 buries the mail buffer, putting it at the lowest priority for
 reselection.  If you want it to kill the mail buffer instead, change
 the variable @code{message-kill-buffer-on-exit} to @code{t}.
-- 
2.25.0


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-Document-message-send-mail-function.patch --]
[-- Type: text/x-patch, Size: 1294 bytes --]

From 77991a80ff9b6185b2b466eec25f4fa7d5e181aa Mon Sep 17 00:00:00 2001
From: Allen Li <darkfeline@felesatra.moe>
Date: Sun, 16 Feb 2020 23:55:43 -0800
Subject: [PATCH 2/2] Document message-send-mail-function

Most of the manual here addresses Message mode, yet talks about
send-mail-function which is used for Mail mode.

Fixing this completely requires more involved work, but for now at
least document the difference here.

* doc/emacs/sending.texi (Mail Sending): Clarify manual
---
 doc/emacs/sending.texi | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index 246d6052e0..8d3f96139f 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -361,9 +361,12 @@ Mail Sending
 @cindex Feedmail
 @cindex Sendmail
 @cindex Mailclient
+@vindex message-send-mail-function
 @vindex send-mail-function
-  The variable @code{send-mail-function} controls how the message is
-delivered.  Its value should be one of the following functions:
+  The variable @code{message-send-mail-function} controls how the
+message is delivered (@code{send-mail-function} is used for Mail mode).
+The value of @code{send-mail-function} should be one of the following
+functions:
 
 @table @code
 @item sendmail-query-once
-- 
2.25.0


[-- Attachment #4: Type: text/plain, Size: 210 bytes --]


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

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

[Eli Zaretskii]

> From: Allen Li <darkfeline@felesatra.moe>
> Date: Mon, 17 Feb 2020 00:14:02 -0800
> 
> I have attached two patches improving the situation ever so slightly,
> but more work is needed here.

Thanks, I installed this on the release branch.  (Please in the future
make sure to end each sentence in the commit log message with a
period.)

Patches are welcome to clean up this area of the manual and of the
related code.