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

[Jorge P. de Morais Neto]

* Mail-related documentation errors

Hello.  Below I report a series of small mail-related
errors/inconsistencies in Emacs docstrings and Info manual.

** C-u C-x m

[[info:emacs#Sending Mail]] says

    If you invoke the command with a prefix argument, ‘C-u C-x m’, Emacs
    switches back to the last mail buffer, and asks if you want to erase
    the message in that buffer

However, the docstring of `compose-mail' says just

    CONTINUE, if non-nil, says to continue editing a message already
    being composed.  Interactively, CONTINUE is the prefix argument.

And in my quick testing with emacs -q, `C-u C-x m' does not ask to erase
the message, suggesting the docstring is correct but not the manual.

** [[info:emacs#Mail Headers]]

*** mail-from-style

In comparison with the `mail-from-style' docstring, the manual informs
the wrong default and fails to mention that the variable is obsolete
because only the `angles' value respects RFC2822[1].  And I think that,
since the variable is now obsolete , then the Info manual should not
even discuss it at length.

1: I don't know why the docstring mentions RFC 2822, as Wikipedia says
that RFC 5322 replaced the earlier RFC 2822 in 2008.  See
https://en.wikipedia.org/wiki/Email#Internet_Message_Format

*** `Mail-Followup-To'

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'.

** [[info:emacs#Mail Aliases]]

Is this feature still widely used?  Are users supposed to manually
maintain ~/.mailrc?  Do not the great majority rely on more convenient
completion mechanisms like LDAP, notmuch or EBDB?  If so, it may be wise
to move this manual section to the end, and mention (even if just in a
generic way) that there are much more popular completion mechanisms.
The Emacs manual is large, and it seems a good idea to organize it in
such a way that the user can easily identify (and optionally skip) the
less important sections.

** [[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?

** [[info:emacs#Header Editing]]

This section of the Info manual says that `message-tab'

    attempts to insert the full name corresponding to the address based
    on a couple of methods, including EUDC, a library that recognizes a
    number of directory server protocols[...]  Failing that, it attempts
    to expand the address as a mail alias[...]

The docstring, however, omits the fallback to mail alias completion.

** `mail-user-agent' docstring

The docstring of `mail-user-agent' refers to the Info node `(message)'
for Message mode and `(emacs)Sending Mail' for Mail mode.  This is a bit
misleading because `(emacs)Sending Mail' describes directly Message mode
and only indirectly (by compatibility) does it describe Mail mode.

* Feedback

I am obsessed with detail and I welcome feedback about that -- please
tell me whether I am nitpicking.

Regards

In GNU Emacs 27.0.90 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.5)
 of 2020-04-11 built on jorge--inspiron-5570
Repository revision: fd27685c1e68e742abf1698573dac53743f15e48
Repository branch: emacs-27
Windowing system distributor 'The X.Org Foundation', version 11.0.12004000
System Description: Debian GNU/Linux 10 (buster)

[ I omitted some details generated by M-x report-emacs-bug that seem
irrelevant to documentation bug reports. ]

-- 
- <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?]]