GNU bug report logs - #55569
Improve documentation of mail-user-agent

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55569 in the body.
You can then email your comments to 55569 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Subject: Improve documentation of mail-user-agent
Date: Sun, 22 May 2022 08:16:25 +0200

[Message part 1 (text/plain, inline)]

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

[0001-Improve-documentation-of-mail-user-agent.patch (text/patch, attachment)]

Message #8 received at 55569 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 55569 <at> debbugs.gnu.org
Subject: Re: bug#55569: Improve documentation of mail-user-agent
Date: Sun, 22 May 2022 09:26:43 +0300

> From: Damien Cassou <damien <at> 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?

Message #11 received at 55569 <at> debbugs.gnu.org (full text, mbox):

From: Damien Cassou <damien <at> cassou.me>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55569 <at> debbugs.gnu.org
Subject: Re: bug#55569: Improve documentation of mail-user-agent
Date: Sun, 22 May 2022 09:18:58 +0200

Hi Eli,

Eli Zaretskii <eliz <at> 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

Message #14 received at 55569 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 55569 <at> debbugs.gnu.org
Subject: Re: bug#55569: Improve documentation of mail-user-agent
Date: Sun, 22 May 2022 10:28:38 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 55569 <at> debbugs.gnu.org
> Date: Sun, 22 May 2022 09:18:58 +0200
> 
> Hi Eli,
> 
> Eli Zaretskii <eliz <at> 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".

Message #17 received at 55569 <at> debbugs.gnu.org (full text, mbox):

From: Damien Cassou <damien <at> cassou.me>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55569 <at> debbugs.gnu.org
Subject: Re: bug#55569: Improve documentation of mail-user-agent
Date: Sun, 22 May 2022 09:48:46 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Improve-documentation-of-mail-user-agent.patch (text/x-patch, attachment)]

Message #22 received at 55569-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 55569-done <at> debbugs.gnu.org
Subject: Re: bug#55569: Improve documentation of mail-user-agent
Date: Sun, 22 May 2022 11:18:32 +0300

> From: Damien Cassou <damien <at> cassou.me>
> Cc: 55569 <at> debbugs.gnu.org
> Date: Sun, 22 May 2022 09:48:46 +0200
> 
> Eli Zaretskii <eliz <at> 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).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.