Release commit

[gnus] / texi / message.texi

\input texinfo                  @c -*-texinfo-*-

@setfilename message
@settitle Message Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@dircategory Emacs
@direntry
* Message: (message).   Mail and news composition mode that goes with Gnus.
@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd

@ifnottex

This file documents Message, the Emacs message composition mode.

Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 
Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end ifnottex

@tex

@titlepage
@title Message Manual

@author by Lars Magne Ingebrigtsen
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
     Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being none, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end titlepage
@page

@end tex

@node Top
@top Message

All message composition from Gnus (both mail and news) takes place in
Message mode buffers.

@menu
* Interface::         Setting up message buffers.
* Commands::          Commands you can execute in message mode buffers.
* Variables::         Customizing the message buffers.
* Compatibility::     Making Message backwards compatible.
* Appendices::        More technical things.
* Index::             Variable, function and concept index.
* Key Index::         List of Message mode keys.
@end menu

This manual corresponds to Message v5.10.6.  Message is distributed
with the Gnus distribution bearing the same version number as this
manual.


@node Interface
@chapter Interface

When a program (or a person) wants to respond to a message -- reply,
follow up, forward, cancel -- the program (or person) should just put
point in the buffer where the message is and call the required command.
@code{Message} will then pop up a new @code{message} mode buffer with
appropriate headers filled out, and the user can edit the message before
sending it.

@menu
* New Mail Message::     Editing a brand new mail message.
* New News Message::     Editing a brand new news message.
* Reply::                Replying via mail.
* Wide Reply::           Responding to all people via mail.
* Followup::             Following up via news.
* Canceling News::       Canceling a news article.
* Superseding::          Superseding a message.
* Forwarding::           Forwarding a message via news or mail.
* Resending::            Resending a mail message.
* Bouncing::             Bouncing a mail message.
* Mailing Lists::        Send mail to mailing lists.
@end menu


@node New Mail Message
@section New Mail Message

@findex message-mail
The @code{message-mail} command pops up a new message buffer.

Two optional parameters are accepted: The first will be used as the
@code{To} header and the second as the @code{Subject} header.  If these
are @code{nil}, those two headers will be empty.


@node New News Message
@section New News Message

@findex message-news
The @code{message-news} command pops up a new message buffer.

This function accepts two optional parameters.  The first will be used
as the @code{Newsgroups} header and the second as the @code{Subject}
header.  If these are @code{nil}, those two headers will be empty.


@node Reply
@section Reply

@findex message-reply
The @code{message-reply} function pops up a message buffer that's a
reply to the message in the current buffer.

@vindex message-reply-to-function
Message uses the normal methods to determine where replies are to go
(@pxref{Responses}), but you can change the behavior to suit your needs
by fiddling with the @code{message-reply-to-function} variable.

If you want the replies to go to the @code{Sender} instead of the
@code{From}, you could do something like this:

@lisp
(setq message-reply-to-function
      (lambda ()
       (cond ((equal (mail-fetch-field "from") "somebody")
               (list (cons 'To (mail-fetch-field "sender"))))
             (t
              nil))))
@end lisp

This function will be called narrowed to the head of the article that is
being replied to.

As you can see, this function should return a string if it has an
opinion as to what the To header should be.  If it does not, it should
just return @code{nil}, and the normal methods for determining the To
header will be used.

This function can also return a list.  In that case, each list element
should be a cons, where the @sc{car} should be the name of a header
(e.g. @code{Cc}) and the @sc{cdr} should be the header value
(e.g. @samp{larsi@@ifi.uio.no}).  All these headers will be inserted into
the head of the outgoing mail.


@node Wide Reply
@section Wide Reply

@findex message-wide-reply
The @code{message-wide-reply} pops up a message buffer that's a wide
reply to the message in the current buffer.  A @dfn{wide reply} is a
reply that goes out to all people listed in the @code{To}, @code{From}
(or @code{Reply-to}) and @code{Cc} headers.

@vindex message-wide-reply-to-function
Message uses the normal methods to determine where wide replies are to go,
but you can change the behavior to suit your needs by fiddling with the
@code{message-wide-reply-to-function}.  It is used in the same way as
@code{message-reply-to-function} (@pxref{Reply}).

@vindex message-dont-reply-to-names
Addresses that match the @code{message-dont-reply-to-names} regular
expression will be removed from the @code{Cc} header.

@vindex message-wide-reply-confirm-recipients
If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you
will be asked to confirm that you want to reply to multiple
recipients.  The default is @code{nil}.

@node Followup
@section Followup

@findex message-followup
The @code{message-followup} command pops up a message buffer that's a
followup to the message in the current buffer.

@vindex message-followup-to-function
Message uses the normal methods to determine where followups are to go,
but you can change the behavior to suit your needs by fiddling with the
@code{message-followup-to-function}.  It is used in the same way as
@code{message-reply-to-function} (@pxref{Reply}).

@vindex message-use-followup-to
The @code{message-use-followup-to} variable says what to do about
@code{Followup-To} headers.  If it is @code{use}, always use the value.
If it is @code{ask} (which is the default), ask whether to use the
value.  If it is @code{t}, use the value unless it is @samp{poster}.  If
it is @code{nil}, don't use the value.


@node Canceling News
@section Canceling News

@findex message-cancel-news
The @code{message-cancel-news} command cancels the article in the
current buffer.

@vindex message-cancel-message
The value of @code{message-cancel-message} is inserted in the body of
the cancel message.  The default is @samp{I am canceling my own
article.}.

@cindex Cancel Locks
@vindex message-insert-canlock
@cindex canlock
When Message posts news messages, it inserts @code{Cancel-Lock}
headers by default.  This is a cryptographic header that ensures that
only you can cancel your own messages, which is nice.  The downside
is that if you lose your @file{.emacs} file (which is where Gnus
stores the secret cancel lock password (which is generated
automatically the first time you use this feature)), you won't be
able to cancel your message.

Whether to insert the header or not is controlled by the
@code{message-insert-canlock} variable.

Not many news servers respect the @code{Cancel-Lock} header yet, but
this is expected to change in the future.


@node Superseding
@section Superseding

@findex message-supersede
The @code{message-supersede} command pops up a message buffer that will
supersede the message in the current buffer.

@vindex message-ignored-supersedes-headers
Headers matching the @code{message-ignored-supersedes-headers} are
removed before popping up the new message buffer.  The default is@*
@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@*
^Received:\\|^X-From-Line:\\|Return-Path:\\|^Supersedes:}.



@node Forwarding
@section Forwarding

@findex message-forward
The @code{message-forward} command pops up a message buffer to forward
the message in the current buffer.  If given a prefix, forward using
news.

@table @code
@item message-forward-ignored-headers
@vindex message-forward-ignored-headers
All headers that match this regexp will be deleted when forwarding a message.

@item message-make-forward-subject-function
@vindex message-make-forward-subject-function
A list of functions that are called to generate a subject header for
forwarded messages.  The subject generated by the previous function is
passed into each successive function.

The provided functions are:

@table @code
@item message-forward-subject-author-subject
@findex message-forward-subject-author-subject
Source of article (author or newsgroup), in brackets followed by the
subject.

@item message-forward-subject-fwd
Subject of article with @samp{Fwd:} prepended to it.
@end table

@item message-wash-forwarded-subjects
@vindex message-wash-forwarded-subjects
If this variable is @code{t}, the subjects of forwarded messages have
the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:},
@samp{(fwd)}) removed before the new subject is
constructed.  The default value is @code{nil}.

@item message-forward-as-mime
@vindex message-forward-as-mime
If this variable is @code{t} (the default), forwarded messages are
included as inline @acronym{MIME} RFC822 parts.  If it's @code{nil}, forwarded
messages will just be copied inline to the new message, like previous,
non @acronym{MIME}-savvy versions of Gnus would do.

@item message-forward-before-signature
@vindex message-forward-before-signature
If non-@code{nil}, put forwarded message before signature, else after.

@end table


@node Resending
@section Resending

@findex message-resend
The @code{message-resend} command will prompt the user for an address
and resend the message in the current buffer to that address.

@vindex message-ignored-resent-headers
Headers that match the @code{message-ignored-resent-headers} regexp will
be removed before sending the message.  The default is
@samp{^Return-receipt}.


@node Bouncing
@section Bouncing

@findex message-bounce
The @code{message-bounce} command will, if the current buffer contains a
bounced mail message, pop up a message buffer stripped of the bounce
information.  A @dfn{bounced message} is typically a mail you've sent
out that has been returned by some @code{mailer-daemon} as
undeliverable.

@vindex message-ignored-bounced-headers
Headers that match the @code{message-ignored-bounced-headers} regexp
will be removed before popping up the buffer.  The default is
@samp{^\\(Received\\|Return-Path\\):}.


@node Mailing Lists
@section Mailing Lists

@cindex Mail-Followup-To
Sometimes while posting to mailing lists, the poster needs to direct
followups to the post to specific places.  The Mail-Followup-To (MFT)
was created to enable just this.  Two example scenarios where this is
useful:

@itemize @bullet
@item
A mailing list poster can use MFT to express that responses should be
sent to just the list, and not the poster as well.  This will happen
if the poster is already subscribed to the list.

@item
A mailing list poster can use MFT to express that responses should be
sent to the list and the poster as well.  This will happen if the poster
is not subscribed to the list.

@item
If a message is posted to several mailing lists, MFT may also be used
to direct the following discussion to one list only, because
discussions that are spread over several lists tend to be fragmented
and very difficult to follow.

@end itemize

Gnus honors the MFT header in other's messages (i.e. while following
up to someone else's post) and also provides support for generating
sensible MFT headers for outgoing messages as well.

@c @menu
@c * Honoring an MFT post::        What to do when one already exists
@c * Composing with a MFT header:: Creating one from scratch.
@c @end menu

@c @node Composing with a MFT header
@subsection  Composing a correct MFT header automagically

The first step in getting Gnus to automagically generate a MFT header
in posts you make is to give Gnus a list of the mailing lists
addresses you are subscribed to.  You can do this in more than one
way.  The following variables would come in handy.

@table @code

@vindex message-subscribed-addresses
@item message-subscribed-addresses
This should be a list of addresses the user is subscribed to.  Its
default value is @code{nil}.  Example:
@lisp
(setq message-subscribed-addresses
      '("ding@@gnus.org" "bing@@noose.org"))
@end lisp

@vindex message-subscribed-regexps
@item message-subscribed-regexps
This should be a list of regexps denoting the addresses of mailing
lists subscribed to.  Default value is @code{nil}.  Example: If you
want to achieve the same result as above:
@lisp
(setq message-subscribed-regexps
      '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org")
@end lisp

@vindex message-subscribed-address-functions
@item message-subscribed-address-functions
This can be a list of functions to be called (one at a time!!) to
determine the value of MFT headers.  It is advisable that these
functions not take any arguments.  Default value is @code{nil}.

There is a pre-defined function in Gnus that is a good candidate for
this variable.  @code{gnus-find-subscribed-addresses} is a function
that returns a list of addresses corresponding to the groups that have
the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters,
gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value.
This is how you would do it.

@lisp
(setq message-subscribed-address-functions
      '(gnus-find-subscribed-addresses))
@end lisp

@vindex message-subscribed-address-file
@item message-subscribed-address-file
You might be one organised human freak and have a list of addresses of
all subscribed mailing lists in a separate file!  Then you can just
set this variable to the name of the file and life would be good.

@end table

You can use one or more of the above variables.  All their values are
``added'' in some way that works :-)

Now you are all set.  Just start composing a message as you normally do.
And just send it; as always.  Just before the message is sent out, Gnus'
MFT generation thingy kicks in and checks if the message already has a
MFT field.  If there is one, it is left alone.  (Except if it's empty -
in that case, the field is removed and is not replaced with an
automatically generated one.  This lets you disable MFT generation on a
per-message basis.)  If there is none, then the list of recipient
addresses (in the To: and Cc: headers) is checked to see if one of them
is a list address you are subscribed to.  If none of them is a list
address, then no MFT is generated; otherwise, a MFT is added to the
other headers and set to the value of all addresses in To: and Cc:

@kindex C-c C-f C-a
@findex message-generate-unsubscribed-mail-followup-to
@kindex C-c C-f C-m
@findex message-goto-mail-followup-to
Hm.  ``So'', you ask, ``what if I send an email to a list I am not
subscribed to?  I want my MFT to say that I want an extra copy.''  (This
is supposed to be interpreted by others the same way as if there were no
MFT, but you can use an explicit MFT to override someone else's
to-address group parameter.)  The function
@code{message-generate-unsubscribed-mail-followup-to} might come in
handy.  It is bound to @kbd{C-c C-f C-a} by default.  In any case, you
can insert a MFT of your own choice; @kbd{C-c C-f C-m}
(@code{message-goto-mail-followup-to}) will help you get started.

@c @node Honoring an MFT post
@subsection Honoring an MFT post

@vindex message-use-mail-followup-to
When you followup to a post on a mailing list, and the post has a MFT
header, Gnus' action will depend on the value of the variable
@code{message-use-mail-followup-to}.  This variable can be one of:

@table @code
@item use
 Always honor MFTs.  The To: and Cc: headers in your followup will be
 derived from the MFT header of the original post.  This is the default.

@item nil
 Always dishonor MFTs (just ignore the darned thing)

@item ask
Gnus will prompt you for an action.

@end table

It is considered good netiquette to honor MFT, as it is assumed the
fellow who posted a message knows where the followups need to go
better than you do.

@node Commands
@chapter Commands

@menu
* Buffer Entry::        Commands after entering a Message buffer.
* Header Commands::     Commands for moving headers or changing headers.
* Movement::            Moving around in message buffers.