bug#40561: 27.0.90; Mail-related errors in docstrings and manuals

[Jorge P . de Morais Neto]

Hi.

Em [2020-04-12 dom 11:47:23+0300], Eli Zaretskii escreveu:
> I fixed the manual to describe what actually happens.

I have just updated Emacs to the latest emacs-27 commit, and, while you
fixed the description of `C-u C-x m', unfortunately you messed up the
behavior of plain `C-x m'.  According to my quick testing (via `emacs
-q`), a plain C-x m behaves as previously described in the manual.

>> I could not understand the meaning of `Mail-Followup-To'.  The manual
>> describes a use case, but I did not understand what is the intended
>> difference in behavior of a mail client that replies to a message
>> containing `Mail-Followup-To' instead of `Mail-Reply-To' or `Reply-To'.
>
> Not sure what is unclear, the description sounds very clear to me,
> although I'm nowhere near being an expert.

I had to search the web and read <https://cr.yp.to/proto/replyto.html>
to understand the behavior of `Mail-Followup-To'.  I then understood
that reply-to-sender goes to Mail-Reply-To/Reply-To/From while wide
reply goes to Mail-Followup-To/(To+Cc+(Mail-Reply-To/Reply-To/From)).  I
believe this is not obvious from the Emacs manual.

I am not asking Emacs manual to reproduce all the contents of the web
page mentioned above.  But at least it could say (in addition to what it
already says) that:

1. Mail clients typically have two different reply functions: one called
   `reply to author' or `reply to sender' or `personal reply,' and one
   called `follow up' or `reply to all' or `reply to sender and
   recipients' or `wide reply' or `group reply'.  (Optionally the manual
   could mention only the terms used by popular Emacs mail readers.)
2. Mention that reply to sender typically goes to
   Mail-Reply-To/Reply-To/From and wide reply goes to
   Mail-Followup-To/(To+Cc+(Mail-Reply-To/Reply-To/From)).  Briefly
   explain that this slash syntax indicates prioritized alternatives.

>> ** [[info:emacs#Mail Sending]]
>> 
>> Why does this section describe the possible values of
>> `send-mail-function' (used for Mail mode), when the section is about
>> Message mode?
>
> That section is not about message-mode, it's about sending email.
> message-mode is just the default mode we use for editing and sending.

I still find the manual a bit misleading.  The first sentence of the
last paragraph of the parent section says:

    In this section, we will describe some of the most commonly-used
    commands available in Message mode.

Then the [[info:emacs#Mail Sending]] section says

    The variable ‘message-send-mail-function’ controls how the message is
    delivered (‘send-mail-function’ is used for Mail mode).

That made me think that people who use Message Mode should set
‘message-send-mail-function’ instead of ‘send-mail-function’.

It is possible that this misunderstanding was caused by bad reading
comprehension on my part -- and my native (and everyday) language is
Portuguese.

And thank you for your work in Emacs!

Regards
-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- I am Brazilian.  I hope my English is correct and I welcome feedback.
- Please adopt free/libre formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z.
- Free/libre software for Replicant, LineageOS and Android: https://f-droid.org
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]