sieve-manage-capability: Do not bug out when the server-value of the capability is nil

[gnus] / texi / message.texi

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

@setfilename message
@settitle Message Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@copying
This file documents Message, the Emacs message composition mode.

Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 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''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@end quotation
@end copying

@dircategory Emacs
@direntry
* Message: (message).           Mail and news composition mode that
                                  goes with Gnus.
@end direntry
@iftex
@finalout
@end iftex

@titlepage
@title Message Manual

@author by Lars Magne Ingebrigtsen
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents
@contents

@node Top
@top Message

@ifnottex
@insertcopying
@end ifnottex

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.
* GNU Free Documentation License:: The license for this documentation.
* Index::             Variable, function and concept index.
* Key Index::         List of Message mode keys.
@end menu

@c Adjust ../Makefile.in if you change the following lines:
Message is distributed with Gnus.  The Gnus distribution
@c
corresponding to this manual is No Gnus v0.11.


@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

You can customize the Message Mode tool bar, see @kbd{M-x
customize-apropos RET message-tool-bar}.  This feature is only available
in Emacs.

@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 list.  In this case, it
returns @code{((To . "Whom"))} 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.

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 (or list of regular expressions) will be removed from the
@code{Cc} header. A value of @code{nil} means exclude your name only.

@vindex message-prune-recipient-rules
@code{message-prune-recipient-rules} is used to prune the addresses
used when doing a wide reply.  It's meant to be used to remove
duplicate addresses and the like.  It's a list of lists, where the
first element is a regexp to match the address to trigger the rule,
and the second is a regexp that will be expanded based on the first,
to match addresses to be pruned.

It's complicated to explain, but it's easy to use.

For instance, if you get an email from @samp{foo@@example.org}, but
@samp{foo@@zot.example.org} is also in the @code{Cc} list, then your
wide reply will go out to both these addresses, since they are unique.

To avoid this, do something like the following:

@lisp
(setq message-prune-recipient-rules
      '(("^\\([^@@]+\\)@@\\(.*\\)" "\\1@@.*[.]\\2")))
@end lisp

If, for instance, you want all wide replies that involve messages from
@samp{cvs@@example.org} to go to that address, and nowhere else (i.e.,
remove all other recipients if @samp{cvs@@example.org} is in the
recipient list:

@lisp
(setq message-prune-recipient-rules
      '(("cvs@@example.org" ".")))
@end lisp

@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.  If you want to manage a password yourself,
you can put something like the following in your @file{~/.gnus.el} file:

@lisp
(setq canlock-password "geheimnis"
      canlock-password-for-verify canlock-password)
@end lisp

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:\\|^X-Trace:\\|^X-Complaints-To:\\|@*
Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@*
^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@*
^X-Payment:\\|^Approved:}.



@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