master fb89711: ; Fix documentation of a recently-installed change

[Eli Zaretskii]

branch: master
commit fb89711ebc6fb6ddc72269c50ae0f5cae7ce62c3
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix documentation of a recently-installed change
    
    * lisp/gnus/message.el (message-server-alist)
    (message-update-smtp-method-header): Doc string fixes.
    
    * doc/misc/message.texi (Sending Variables): Fix wording and
    markup.
    
    * etc/NEWS: Fix the wording of the 'message-server-alist' entry.
---
 doc/misc/message.texi | 19 +++++++++++++------
 etc/NEWS              |  6 +++---
 lisp/gnus/message.el  | 23 ++++++++++++-----------
 3 files changed, 28 insertions(+), 20 deletions(-)

diff --git a/doc/misc/message.texi b/doc/misc/message.texi
index dac5e75..b628fd1 100644
--- a/doc/misc/message.texi
+++ b/doc/misc/message.texi
@@ -2555,12 +2555,19 @@ message.
 
 @item message-server-alist
 @vindex message-server-alist
-An alist describing how to insert a @code{X-Message-SMTP-Method}
-header before sending out a new message.  The key has to be a string,
-that will be matched with the @code{From} header, and will insert the
-value as the SMTP Method if these are equal.  Alternatively, the key
-may be a function that will be called in the message buffer without
-any arguments, and matches if a non-nil value is returned.
+An alist describing the rules for generating the
+@code{X-Message-SMTP-Method} header to insert before sending out a new
+message, if the message doesn't yet have such a header.  Each element
+of the alist should be of the form
+@w{@code{(@var{cond} . @var{method})}}.  If @var{cond} is a string, it
+will be compared with the @code{From} header, and if they compare
+equal, the corresponding @var{method} will be inserted as a string
+into the message headers as the SMTP Method.  If @var{cond} is a
+function, it will be called in the message buffer without any
+arguments, and the corresponding @var{method} will be inserted into
+the message headers as the SMTP Method if the function returns a
+non-@code{nil} value; if @var{method} is nil, the value returned by
+the function @code{cond} is used instead.
 
 @end table
 
diff --git a/etc/NEWS b/etc/NEWS
index 86f1807..948dbba 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -402,9 +402,9 @@ If non-nil, 'C-c C-a' will put attached files at the end of 
the message.
 *** Message Mode now supports image yanking.
 
 ---
-*** New user option 'message-server-alist'
-Enables automatically inserting "X-Message-SMTP-Method" before sending
-a message.
+*** New user option 'message-server-alist'.
+This controls automatic insertion of the "X-Message-SMTP-Method"
+header before sending a message.
 
 ** HTML Mode
 
diff --git a/lisp/gnus/message.el b/lisp/gnus/message.el
index c18560b..f69f51a 100644
--- a/lisp/gnus/message.el
+++ b/lisp/gnus/message.el
@@ -4336,16 +4336,17 @@ Instead, just auto-save the buffer and then bury it."
 (autoload 'mml-secure-bcc-is-safe "mml-sec")
 
 (defcustom message-server-alist nil
-  "Alist of rules to generate \"X-Message-SMTP-Method\" headers.
-If any entry of the form (COND . METHOD) matches, the header will
-be inserted just before the message is sent.  If COND is a
-string, METHOD will be inserted if the \"From\" header matches
-COND.  If COND is a function, METHOD will be inserted if COND
-returns a non-nil value, when called in the message buffer
-without any arguments.  If METHOD is nil in the last case, the
-return value of the function will be returned instead.  None of
-this applies if the buffer already has a\"X-Message-SMTP-Method\"
-header."
+  "Alist of rules to generate \"X-Message-SMTP-Method\" header.
+The header will be inserted just before the message is sent.
+Elements should be of the form (COND . METHOD).
+If COND is a string, METHOD will be inserted if the \"From\"
+address compares equal with COND.
+If COND is a function, METHOD will be inserted if COND returns
+a non-nil value when called in the message buffer without any
+arguments.  If METHOD is nil in this case, the return value of
+the function will be inserted instead.
+If the buffer already has a\"X-Message-SMTP-Method\" header,
+it is left unchanged."
   :type '(alist :key-type '(choice
                             (string :tag "From Address")
                             (function :tag "Predicate"))
@@ -4354,7 +4355,7 @@ header."
   :group 'message-sending)
 
 (defun message-update-smtp-method-header ()
-  "Check `message-server-alist' to insert a SMTP-Method header."
+  "Insert an X-Message-SMTP-Method header according to `message-server-alist'."
   (unless (message-fetch-field "X-Message-SMTP-Method")
     (let ((from (cadr (mail-extract-address-components (message-fetch-field 
"From"))))
           method)