emacs-27 3f9310b: Fix and improve documentation of mail-related features

[Eli Zaretskii]

branch: emacs-27
commit 3f9310b0fecbd842244798fb9a62d56b2151c534
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Fix and improve documentation of mail-related features
    
    * lisp/simple.el (compose-mail): Clarify the effect of the
    CONTINUE argument.
    * lisp/mail/sendmail.el (mail-from-style): Update the RFC value in
    the obsolescence warning text.
    
    * doc/emacs/sending.texi (Sending Mail): Fix the description of
    the behavior of 'C-x m' wrt prefix argument.
    (Mail Headers): Remove the description of 'mail-from-style'.
    
    * etc/NEWS: Mention that 'mail-from-style' is obsolete.
    
    (Bug#40561)
---
 doc/emacs/sending.texi | 33 +++++++--------------------------
 etc/NEWS               |  4 ++++
 lisp/mail/sendmail.el  |  2 +-
 lisp/simple.el         |  8 ++++++--
 4 files changed, 18 insertions(+), 29 deletions(-)

diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index 190549a..a289549 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -32,12 +32,13 @@ In the mail buffer, send the message and bury the buffer
 
   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
+mail before sending the current one, type @kbd{C-x m} again, and Emacs
+will switch back to the last mail buffer and ask if you want to erase
+the message in that buffer; answer yes to discard the unsent message
+and start composing a new one.  If you know that you'd like to
+continue composing an unsent message, invoke this command with a
+prefix argument, @w{@kbd{C-u C-x m}}, and Emacs will switch to the
+last mail buffer and let you pick up editing the message where you
 left off.
 
 @kindex C-x 4 m
@@ -122,26 +123,6 @@ environment variables (@pxref{General Variables}).  If this
 information is unavailable or wrong, you should customize the
 variables yourself (@pxref{Easy Customization}).
 
-@vindex mail-from-style
-  The value of the variable @code{mail-from-style} specifies how to
-format the contents of the @samp{From} field:
-
-@table @asis
-@item @code{nil}
-Use just the address, as in @samp{king@@grassland.com}.
-@item @code{parens}
-Use both address and full name, as in:@*
-@samp{king@@grassland.com (Elvis Parsley)}.
-@item @code{angles}
-Use both address and full name, as in:@*
-@samp{Elvis Parsley <king@@grassland.com>}.
-@item any other value
-Use @code{angles} normally.  But if the address must be quoted to
-remain syntactically valid under the @code{angles} format but not
-under the @code{parens} format, use @code{parens} instead.  This is
-the default.
-@end table
-
   Apart from @samp{From}, here is a table of commonly-used fields:
 
 @table @samp
diff --git a/etc/NEWS b/etc/NEWS
index 44a92ec..f4edfaf 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2239,6 +2239,10 @@ The option is useful for two reasons when verifying the 
signature:
     2.2.17 to fully benefit from this feature.  See gpg(1) man page for
     "--auto-key-retrieve".
 
++++
+*** The 'mail-from-style' variable is now obsolete.
+According to RFC 5322, only the 'angles' value is valid.
+
 ---
 ** EasyPG
 
diff --git a/lisp/mail/sendmail.el b/lisp/mail/sendmail.el
index 14adb5a..65d598c 100644
--- a/lisp/mail/sendmail.el
+++ b/lisp/mail/sendmail.el
@@ -73,7 +73,7 @@ Otherwise, most addresses look like `angles', but they look 
like
   :version "27.1")
 (make-obsolete-variable
  'mail-from-style
- "only the `angles' value is valid according to RFC2822." "27.1" 'set)
+ "only the `angles' value is valid according to RFC5322." "27.1" 'set)
 
 ;;;###autoload
 (defcustom mail-specify-envelope-from nil
diff --git a/lisp/simple.el b/lisp/simple.el
index cb04c98..da9e04d 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -8020,8 +8020,12 @@ OTHER-HEADERS is an alist specifying additional
 header fields.  Elements look like (HEADER . VALUE) where both
 HEADER and VALUE are strings.
 
-CONTINUE, if non-nil, says to continue editing a message already
-being composed.  Interactively, CONTINUE is the prefix argument.
+By default, if an unsent message is already being composed, this
+command will ask whether to erase the unsent message, and will not
+start a new message if the user doesn't allow erasing.  However, if
+CONTINUE is non-nil, it means to continue editing a message already
+being composed without asking.  Interactively, CONTINUE is the prefix
+argument.
 
 SWITCH-FUNCTION, if non-nil, is a function to use to
 switch to and display the buffer used for mail composition.