--- Begin Message ---
|
Subject: |
27.0.90; Mail-related errors in docstrings and manuals |
|
Date: |
Sat, 11 Apr 2020 16:00:50 -0300 |
* 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?]]
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#40561: 27.0.90; Mail-related errors in docstrings and manuals |
|
Date: |
Sun, 12 Apr 2020 11:47:23 +0300 |
> From: "Jorge P. de Morais Neto" <address@hidden>
> 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.
--- End Message ---