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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 12 Apr 2020 11:47:23 +0300

> From: "Jorge P. de Morais Neto" <[email-masked]>
> Date: Sat, 11 Apr 2020 16:00:50 -0300
> 
> ** 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.

Sigh.  10 years since the defaults of sending email changed in Emacs
23.2, and we are still not done with the fallout.

I fixed the manual to describe what actually happens.  I do think that
what the manual described originally is a saner behavior:

    The mail buffer is an ordinary Emacs buffer, so you can switch to
  other buffers while composing the mail.  If you want to send another
  mail before finishing the current one, type @kbd{C-x m} again to open
  a new mail buffer whose name has a different numeric suffix
  (@pxref{Misc Buffer}).  If you invoke the command with a prefix
  argument, @w{@kbd{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; if
  you answer no, this lets you pick up editing the message where you
  left off.

But we cannot have that, since message-mail doesn't support the
special value 'new' for the CONTINUE argument (sendmail.el's 'mail'
did), and this the ability to compose a new message without losing the
previous one is lost.  The inverted defaults for when to ask whether
to erase existing text also sounds like a step backward to me.  Oh
well.

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

Removed from manual.  (Btw, the fact that the variable is obsolete was
never called out in NEWS.)

> 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

Fixed the RFC number.

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

Not sure what is unclear, the description sounds very clear to me,
although I'm nowhere near being an expert.

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

Yes, this feature is still used.  No, I don't see a reason to move the
description.

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

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

The doc string doesn't omit that, because what you call "the fallback"
is actually prescribed by message-completion-alist: as long as
message-expand-name is in that list, the fallback will work, since
message-expand-name implements it.  But message-completion-alist is a
defcustom, so users can customize it to anything they want, including
the removal of message-expand-name from the list.

> ** `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.

I see no problem here.

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

No comment.

Thanks.