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

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

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

[Eli Zaretskii]

> From: "Jorge P. de Morais Neto" <jorge+list@disroot.org>
> 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.

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

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

[Eli Zaretskii]

> From: Jorge P. de Morais Neto <jorge+list@disroot.org>
> Cc: 40561-done@debbugs.gnu.org, 40561@debbugs.gnu.org
> Date: Sun, 12 Apr 2020 15:20:22 -0300
> 
> 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.

Please elaborate: what previous description was correct that I messed
up?

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

I use Rmail.  It has only one command: rmail-replay.  It uses these
headers according to the precedence described in the manual, AFAICT.

Maybe Gnus has more "reply" commands, but Gnus has its own manual.

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

I'd be interested to hear opinions by others about this.

> And thank you for your work in Emacs!

Thank you for your attention to the details in the manual.

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

[Eli Zaretskii]

> Date: Sun, 12 Apr 2020 21:34:13 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 40561@debbugs.gnu.org
> 
> > From: Jorge P. de Morais Neto <jorge+list@disroot.org>
> > Cc: 40561-done@debbugs.gnu.org, 40561@debbugs.gnu.org
> > Date: Sun, 12 Apr 2020 15:20:22 -0300
> > 
> > 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.
> 
> Please elaborate: what previous description was correct that I messed
> up?

Ah, I see: message-mode behaves differently here from mail-mode (which
is what I'm using).  Sigh.  Should be fixed now.

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

[Jorge P. de Morais Neto]

Em [2020-04-12 dom 21:34:13+0300], Eli Zaretskii escreveu:

> I use Rmail.  It has only one command: rmail-replay.  It uses these
> headers according to the precedence described in the manual, AFAICT.
>
> Maybe Gnus has more "reply" commands, but Gnus has its own manual.

Gnus may have its own manual, but still including that brief information
in Emacs' manual would help not only Gnus users, but also users of
Notmuch and possibly also other popular clients, so it would have good
cost-effect.  Besides, it would help users understand what effect will
`Mail-Followup-To' likely have on the recipient when he replies to a
message sent by the Emacs user.

I am sorry for insisting so much, so if you still think the manual is
clear here, then I will silently accept.

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

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

[Štěpán Němec]

On Sun, 12 Apr 2020 21:34:13 +0300
Eli Zaretskii wrote:

>> > 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.
>
> I'd be interested to hear opinions by others about this.

I agree with Jorge that the quoted section is confusing, and the recent
change from bug#39639 (which I've now found when trying to make some
sense of it doing 'git blame' on sending.texi) mostly just added to that
confusion, as it only stuck `message-send-mail-function' in the middle
of the 10-year-old text.

https://debbugs.gnu.org/cgi/bugreport.cgi?bug=39639

It would be great if someone who understands how the current default
setup is supposed to fit together had a look at that part of the manual.

-- 
Štěpán