bug#67638: Description of the variable message-mail-user-agent in Emacs 29.1

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 05 Dec 2023 16:22:17 +0000
> From: rameiko87@posteo.net
> Cc: 67638@debbugs.gnu.org
> 
> Dear Eli,
> Thanks very much for your swift reply. Please understand that I mean no 
> disturbance through my questions, I'm only trying to understand. What is 
> confusing me still is that mail-user-agent sets the composition package 
> for outgoing emails (in my personal configuration this is the Message 
> package, in my mind this is the MUA being used when writing emails). The 
> message-mail-user-agent variable instead it's not clear what is setting.

message.el basically implements the message-mode, which is a
specialized text-editing mode.  It does not itself deal with
email-specific stuff, like mail headers, the structure of the message
according to the various RFCs, and neither does it handle the sending
process itself.

> > "Your preferred mail composition package when reading email with 
> > message.el.
> 
> But I read my emails with Rmail. Perhaps you meant "when composing 
> emails with message.el"?

No.

> If yes, I thought that the message package was 
> the email composition package

No, see above.  "Mail User Agent" is separate from message.el.

> and that I assigned this with the variable 
> mail-user-agent, so I'm not sure what I'm setting here.

If you want mail-user-agent to take precedence, you need to customize
message-mail-user-agent to the value t.  That's what the doc string
says.

> >   Like `mail-user-agent' (which see), this specifies the mail-sending 
> > package you prefer.
> 
> Now the composition package from the first quote turned into sending 
> package! What is a mail sending package?

Mail User Agent is both.  See below.

> How is this variable the 
> "analogous" of mail-user-agent (I really don't like that "Like")?

Once again, "like", with a hyperlink after it, invites you to read the
documentation of mail-user-agent.  This is our usual style in doc
strings to avoid repetition.

> >   The value can be any value accepted by `mail-user-agent', and in 
> > addition it can be nil or t.  If the value is nil, use the Gnus native 
> > Mail User Agent (MUA); if it is t, use the value of `mail-user-agent'."
> 
> Why is the default the Gnus package?

Because message.el was originally part of Gnus, and Gnus users expect
that default.

> The problem is that I still don't understand the difference with
> mail-user-agent.

They are two separate options, and users have the freedom which one to
customize and how.

Next iteration of the doc string below.

   "Your preferred package for composing and sending email when using message.el.
 Like `mail-user-agent' (which see), this specifies the package you prefer
 to use for composing and sending email messages.
 The value can be anything accepted by `mail-user-agent', and in addition
 it can be nil or t.  If the value is nil, use the Gnus native Mail User
 Agent (MUA); if it is t, use the value of `mail-user-agent'.
 For more about mail user agents, see Info node `(emacs)Mail Methods'"