bug#55569: Improve documentation of mail-user-agent

bug#55569: Improve documentation of mail-user-agent

[Damien Cassou]

[-- Attachment #1: Type: text/plain, Size: 274 bytes --]

Tags: patch

* doc/emacs/sending.texi (Mail Methods): Add sentences.
* lisp/simple.el (mail-user-agent): Add sentences to the documentation
string.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-documentation-of-mail-user-agent.patch --]
[-- Type: text/patch, Size: 2023 bytes --]

From be4bcf3ade2b64b211074ba92688922f4f43978e Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@cassou.me>
Date: Sun, 22 May 2022 08:09:38 +0200
Subject: [PATCH] Improve documentation of mail-user-agent.

* doc/emacs/sending.texi (Mail Methods): Add sentences.
* lisp/simple.el (mail-user-agent): Add sentences to the documentation
string.
---
 doc/emacs/sending.texi | 4 +++-
 lisp/simple.el         | 7 ++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index ea87e0a77b..221d2aa3dd 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -667,7 +667,9 @@ Mail Methods
 customize the variable @code{mail-user-agent}.  Currently, legitimate
 values include @code{message-user-agent} (Message mode)
 @code{sendmail-user-agent} (Mail mode), @code{gnus-user-agent}, and
-@code{mh-e-user-agent}.
+@code{mh-e-user-agent}.  Additional options may be available; check
+with the author of your mail user agent package for details.  You may
+also define another mail user agent using `define-mail-user-agent'.
 
   If you select a different mail-composition method, the information
 in this chapter about the mail buffer and Message mode does not apply;
diff --git a/lisp/simple.el b/lisp/simple.el
index 6906675f68..f901da9bc6 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9210,9 +9210,10 @@ mail-user-agent
                            paraphernalia if Gnus is running, particularly
                            the Gcc: header for archiving.
 
-Additional valid symbols may be available; check with the author of
-your package for details.  The function should return non-nil if it
-succeeds.
+Additional valid symbols may be available; check with the author
+of your mail user agent package for details.  You may also define
+your own symbol to be used as value for this variable using
+`define-mail-user-agent'.
 
 See also `read-mail-command' concerning reading mail."
   :type '(radio (function-item :tag "Message package"
-- 
2.36.0

bug#55569: Improve documentation of mail-user-agent

[Eli Zaretskii]

> From: Damien Cassou <damien@cassou.me>
> Date: Sun, 22 May 2022 08:16:25 +0200
> 
> diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
> index ea87e0a77b..221d2aa3dd 100644
> --- a/doc/emacs/sending.texi
> +++ b/doc/emacs/sending.texi
> @@ -667,7 +667,9 @@ Mail Methods
>  customize the variable @code{mail-user-agent}.  Currently, legitimate
>  values include @code{message-user-agent} (Message mode)
>  @code{sendmail-user-agent} (Mail mode), @code{gnus-user-agent}, and
> -@code{mh-e-user-agent}.
> +@code{mh-e-user-agent}.  Additional options may be available; check
> +with the author of your mail user agent package for details.  You may
> +also define another mail user agent using `define-mail-user-agent'.

Thanks, but what do you mean by "the author of your mail user agent
package"?  This is an Emacs user manual, and I very much doubt that
Emacs users could figure out where and how to check that.

Can we provide more practical advice here how to check for those
additional options?

bug#55569: Improve documentation of mail-user-agent

[Damien Cassou]

Hi Eli,

Eli Zaretskii <eliz@gnu.org> writes:
>> +@code{mh-e-user-agent}.  Additional options may be available; check
>> +with the author of your mail user agent package for details.  You may
>> +also define another mail user agent using `define-mail-user-agent'.
>
> Thanks, but what do you mean by "the author of your mail user agent
> package"?


I mean that the authors of notmuch and mu4e both define a symbol to be
used as value for the `mail-user-agent` variable: `mu4e-user-agent` and
`notmuch-user-agent`.  These symbols should be documented somewhere in
notmuch and mu4e manuals so their users know they should pass them to
`mail-user-agent`.  There might be other mail user agent packages out
there that I don't know about.


> This is an Emacs user manual, and I very much doubt that
> Emacs users could figure out where and how to check that.
>
> Can we provide more practical advice here how to check for those
> additional options?


I could certainly mention the symbols for notmuch and mu4e if you think
that is ok to mention external packages inside the Emacs manual but I'm
not sure what else I could do.

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

bug#55569: Improve documentation of mail-user-agent

[Eli Zaretskii]

> From: Damien Cassou <damien@cassou.me>
> Cc: 55569@debbugs.gnu.org
> Date: Sun, 22 May 2022 09:18:58 +0200
> 
> Hi Eli,
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> >> +@code{mh-e-user-agent}.  Additional options may be available; check
> >> +with the author of your mail user agent package for details.  You may
> >> +also define another mail user agent using `define-mail-user-agent'.
> >
> > Thanks, but what do you mean by "the author of your mail user agent
> > package"?
> 
> 
> I mean that the authors of notmuch and mu4e both define a symbol to be
> used as value for the `mail-user-agent` variable: `mu4e-user-agent` and
> `notmuch-user-agent`.  These symbols should be documented somewhere in
> notmuch and mu4e manuals so their users know they should pass them to
> `mail-user-agent`.  There might be other mail user agent packages out
> there that I don't know about.
> 
> 
> > This is an Emacs user manual, and I very much doubt that
> > Emacs users could figure out where and how to check that.
> >
> > Can we provide more practical advice here how to check for those
> > additional options?
> 
> 
> I could certainly mention the symbols for notmuch and mu4e if you think
> that is ok to mention external packages inside the Emacs manual but I'm
> not sure what else I could do.

If those additional options are supposed to be documented in the MUA
manual, let's suggest that users look in those manuals.  That is IMO
better than to send them to some unnamed "authors".

bug#55569: Improve documentation of mail-user-agent

[Damien Cassou]

[-- Attachment #1: Type: text/plain, Size: 450 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:
> If those additional options are supposed to be documented in the MUA
> manual, let's suggest that users look in those manuals.  That is IMO
> better than to send them to some unnamed "authors".

Here is a new version of the patch that references the "manual" instead
of the "authors".

-- 
Damien Cassou

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-documentation-of-mail-user-agent.patch --]
[-- Type: text/x-patch, Size: 2019 bytes --]

From 14361675353a4f026eacffd04b88c31bdd4cc9f9 Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@cassou.me>
Date: Sun, 22 May 2022 08:09:38 +0200
Subject: [PATCH] Improve documentation of mail-user-agent.

* doc/emacs/sending.texi (Mail Methods): Add sentences.
* lisp/simple.el (mail-user-agent): Add sentences to the documentation
string.
---
 doc/emacs/sending.texi | 4 +++-
 lisp/simple.el         | 7 ++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index ea87e0a77b..acdae8a263 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -667,7 +667,9 @@ Mail Methods
 customize the variable @code{mail-user-agent}.  Currently, legitimate
 values include @code{message-user-agent} (Message mode)
 @code{sendmail-user-agent} (Mail mode), @code{gnus-user-agent}, and
-@code{mh-e-user-agent}.
+@code{mh-e-user-agent}.  Additional options may be available; check
+in the manual of your mail user agent package for details.  You may
+also define another mail user agent using `define-mail-user-agent'.
 
   If you select a different mail-composition method, the information
 in this chapter about the mail buffer and Message mode does not apply;
diff --git a/lisp/simple.el b/lisp/simple.el
index 6906675f68..cdb7ce6832 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9210,9 +9210,10 @@ mail-user-agent
                            paraphernalia if Gnus is running, particularly
                            the Gcc: header for archiving.
 
-Additional valid symbols may be available; check with the author of
-your package for details.  The function should return non-nil if it
-succeeds.
+Additional valid symbols may be available; check in the manual of
+your mail user agent package for details.  You may also define
+your own symbol to be used as value for this variable using
+`define-mail-user-agent'.
 
 See also `read-mail-command' concerning reading mail."
   :type '(radio (function-item :tag "Message package"
-- 
2.36.0

bug#55569: Improve documentation of mail-user-agent

[Eli Zaretskii]

> From: Damien Cassou <damien@cassou.me>
> Cc: 55569@debbugs.gnu.org
> Date: Sun, 22 May 2022 09:48:46 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> > If those additional options are supposed to be documented in the MUA
> > manual, let's suggest that users look in those manuals.  That is IMO
> > better than to send them to some unnamed "authors".
> 
> Here is a new version of the patch that references the "manual" instead
> of the "authors".

Thanks, installed on the release branch (with some minor fixups).