\input texinfo @c -*-texinfo-*-
-@setfilename message.info
-@settitle Message Manual
+@setfilename message
+@settitle Message 0.33 Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
+@c @direntry
+@c * Message: (message). Mail and news composition mode that goes with Gnus.
+@c @end direntry
@iftex
@finalout
@end iftex
@ifinfo
-This file documents Messa, the Emacs message composition mode.
+This file documents Message, the Emacs message composition mode.
Copyright (C) 1996 Free Software Foundation, Inc.
@tex
@titlepage
-@title Message Manual
+@title Message 0.33 Manual
@author by Lars Magne Ingebrigtsen
@page
@node Top
@top Message
-All message composition (both mail and news) takes place in Message mode
-buffers.
+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 0.33. Message is distributed with
+the Gnus distribution bearing the same version number as this manual
+has.
+
@node Interface
@chapter Interface
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
-aren't present, those two headers will be empty.
+are @code{nil}, those two headers will be empty.
@node New News Message
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 aren't present, those two headers will be empty.
+header. If these are @code{nil}, those two headers will be empty.
@node Reply
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,
-but you can change the behavior to suit your needs by fiddling with the
-@code{message-reply-to-function} variable.
+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:
@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.
+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,
@code{message-reply-to-function} (@pxref{Reply}).
@findex rmail-dont-reply-to-names
-Addresses that matches the @code{rmail-dont-reply-to-names} regular
+Addresses that match the @code{rmail-dont-reply-to-names} regular
expression will be removed from the @code{Cc} header.
@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:}.
+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:}.
@table @code
@item message-forward-start-separator
@vindex message-forward-start-separator
-Delimiter inserted before forwarded messages. The default is
+Delimiter inserted before forwarded messages. The default is@*
@samp{------- Start of forwarded message -------\n}.
@vindex message-forward-end-separator
@item message-forward-end-separator
@vindex message-forward-end-separator
-Delimiter inserted after forwarded messages. The default is
+Delimiter inserted after forwarded messages. The default is@*
@samp{------- End of forwarded message -------\n}.
@item message-signature-before-forwarded-message
and resend the message in the current buffer to that address.
@vindex message-ignored-resent-headers
-Headers the match the @code{message-ignored-resent-headers} regexp will
+Headers that match the @code{message-ignored-resent-headers} regexp will
be removed before sending the message. The default is
@samp{^Return-receipt}.
@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.
+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:}.
+@samp{^\\(Received\\|Return-Path\\):}.
@node Commands
* Insertion:: Inserting things into message buffers.
* Various Commands:: Various things.
* Sending:: Actually sending the message.
+* Mail Aliases:: How to use mail aliases.
@end menu
@item C-c C-q
@kindex C-c C-q
@findex message-fill-yanked-message
-Fill the yanked message (@code{message-fill-yanked-message}).
+Fill the yanked message (@code{message-fill-yanked-message}). Warning:
+Can severely mess up the yanked text if its quoting conventions are
+strange. You'll quickly get a feel for when it's safe, though. Anyway,
+just remember that @kbd{C-x u} (@code{undo}) is available and you'll be
+all right.
+
@item C-c C-w
@kindex C-c C-w
@item message-citation-line-function
@vindex message-citation-line-function
Function called to insert the citation line. The default is
-@code{message-insert-citation-line}.
+@code{message-insert-citation-line}, which will lead to citation lines
+that look like:
+
+@example
+Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
+@end example
+
+Point will be at the beginning of the body of the message when this
+function is called.
@item message-yank-prefix
@vindex message-yank-prefix
@vindex message-cite-function
@findex message-cite-original
@findex sc-cite-original
-@cindex SuperCite
+@findex message-cite-original-without-signature
+@cindex Supercite
Function for citing an original message. The default is
-@code{message-cite-original}. You can also set it to
-@code{sc-cite-original} to use SuperCite.
+@code{message-cite-original}, which simply inserts the original message
+and prepends @samp{> } to each line.
+@code{message-cite-original-without-signature} does the same, but elides
+the signature. You can also set it to @code{sc-cite-original} to use
+Supercite.
@item message-indent-citation-function
@vindex message-indent-citation-function
@end table
-Note that RFC1036 says that a signature should be preceded by the three
+Note that RFC1036bis says that a signature should be preceded by the three
characters @samp{-- } on a line by themselves. This is to make it
easier for the recipient to automatically recognize and process the
signature. So don't remove those characters, even though you might feel
-that they ruin you beautiful design, like, totally.
+that they ruin your beautiful design, like, totally.
Also note that no signature should be more than four lines long.
Including ASCII graphics is an efficient way to get everybody to believe
rotate the visible portion of the buffer. A numerical prefix says how
many places to rotate the text. The default is 13.
+@item C-c C-e
+@kindex C-c C-e
+@findex message-elide-region
+Elide the text between point and mark (@code{message-elide-region}).
+The text is killed and an ellipsis (@samp{[...]}) will be inserted in
+its place.
+
+@item C-c C-z
+@kindex C-c C-x
+@findex message-kill-to-signature
+Kill all the text up to the signature, or if that's missing, up to the
+end of the message (@code{message-kill-to-signature}).
+
+@item C-c C-v
+@kindex C-c C-v
+@findex message-delete-not-region
+Delete all text in the body of the message that is outside the region
+(@code{message-delete-not-region}).
+
+@item M-RET
+@kindex M-RET
+@kindex message-newline-and-reformat
+Insert four newlines, and then reformat if inside quoted text.
+
+Here's an example:
+
+@example
+> This is some quoted text. And here's more quoted text.
+@end example
+
+If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
+
+@example
+> This is some quoted text.
+
+*
+
+> And here's more quoted text.
+@end example
+
+@samp{*} says where point will be placed.
+
@item C-c C-t
@kindex C-c C-t
@findex message-insert-to
@end table
+
+@node Mail Aliases
+@section Mail Aliases
+@cindex mail aliases
+@cindex aliases
+
+@vindex message-mail-alias-type
+The @code{message-mail-alias-type} variable controls what type of mail
+alias expansion to use. Currently only one form is supported---Message
+uses @code{mailabbrev} to handle mail aliases. If this variable is
+@code{nil}, no mail alias expansion will be performed.
+
+@code{mailabbrev} works by parsing the @file{/etc/mailrc} and
+@file{~/.mailrc} files. These files look like:
+
+@example
+alias lmi "Lars Magne Ingebrigtsen <larsi@@ifi.uio.no>"
+alias ding "ding@@ifi.uio.no (ding mailing list)"
+@end example
+
+After adding lines like this to your @file{~/.mailrc} file, you should
+be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so
+on) headers and press @kbd{SPC} to expand the alias.
+
+No expansion will be performed upon sending of the message---all
+expansions have to be done explicitly.
+
+
+
@node Variables
@chapter Variables
@node Message Headers
@section Message Headers
-Message is quite aggressive on the message generation front. It has
-to be -- it's a combined news and mail agent. To be able to send
-combined messages, it has to generate all headers itself to ensure that
-mail and news copies of messages look sufficiently similar.
+Message is quite aggressive on the message generation front. It has to
+be -- it's a combined news and mail agent. To be able to send combined
+messages, it has to generate all headers itself (instead of letting the
+mail/news system do it) to ensure that mail and news copies of messages
+look sufficiently similar.
@table @code
@table @code
@item message-required-mail-headers
@vindex message-required-mail-headers
-See @pxref{News Headers} for the syntax of this variable. It is
+@xref{News Headers}, for the syntax of this variable. It is
@code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
(optional . X-Mailer))} by default.
@item message-ignored-mail-headers
@vindex message-ignored-mail-headers
Regexp of headers to be removed before mailing. The default is
-@samp{^Gcc:\\|^Fcc:}.
+@samp{^[GF]cc:\\|^Resent-Fcc:}.
@item message-default-mail-headers
@vindex message-default-mail-headers
@code{message-send-mail-with-sendmail}. If you prefer using MH
instead, set this variable to @code{message-send-mail-with-mh}.
+@item message-mh-deletable-headers
+@vindex message-mh-deletable-headers
+Most versions of MH doesn't like being fed messages that contain the
+headers in this variable. If this variable is non-@code{nil} (which is
+the default), these headers will be removed before mailing when sending
+messages via MH. Set it to @code{nil} if your MH can handle these
+headers.
+
@end table
@cindex organization
This optional header will be filled out depending on the
@code{message-user-organization} variable.
-@code{message-user-organization-file} will be used if that variable is
-@code{t}.
+@code{message-user-organization-file} will be used if this variable is
+@code{t}. This variable can also be a string (in which case this string
+will be used), or it can be a function (which will be called with no
+parameters and should return a string to be used).
@item Lines
@cindex Lines
@findex system-name
@cindex Sun
This required header will be generated by Message. A unique ID will be
-created based on date, time, user name and system name. Message will
+created based on the date, time, user name and system name. Message will
use @code{mail-host-address} as the fully qualified domain name (FQDN)
-of the machine if that variable is define. If not, it will use
+of the machine if that variable is defined. If not, it will use
@code{system-name}, which doesn't report a FQDN on some machines --
notably Suns.
@item In-Reply-To
This optional header is filled out using the @code{Date} and @code{From}
-header of the article being replied.
+header of the article being replied to.
@item Expires
@cindex Expires
@item Path
@cindex path
-This extremely optional header should probably not ever be used.
+This extremely optional header should probably never be used.
However, some @emph{very} old servers require that this header is
present. @code{message-user-path} further controls how this
-@code{Path} header is to look. If is is @code{nil}, the the server name
-as the leaf node. If is is a string, use the string. If it is neither
+@code{Path} header is to look. If it is @code{nil}, use the server name
+as the leaf node. If it is a string, use the string. If it is neither
a string nor @code{nil}, use the user name only. However, it is highly
unlikely that you should need to fiddle with this variable at all.
@end table
@item message-syntax-checks
@vindex message-syntax-checks
-If non-@code{nil}, message will attempt to check the legality of the
+If non-@code{nil}, Message will attempt to check the legality of the
headers, as well as some other stuff, before posting. You can control
the granularity of the check by adding or removing elements from this
list. Legal elements are:
@item empty-headers
Check whether any of the headers are empty.
@item existing-newsgroups
-Check whether the newsgroups mentioned in the Newsgroups and
-Followup-To headers exist.
+Check whether the newsgroups mentioned in the @code{Newsgroups} and
+@code{Followup-To} headers exist.
@item valid-newsgroups
-Check whether the @code{Newsgroups} and @code{Followup-To} headers
-are valid syntactially.
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+are valid syntactically.
+@item repeated-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-to} headers
+contains repeated group names.
+@item shorten-followup-to
+Check whether to add a @code{Followup-to} header to shorten the number
+of groups to post to.
@end table
All these conditions are checked by default.
@item message-ignored-news-headers
@vindex message-ignored-news-headers
-Regexp of headers to be removed before posting. The default is
-@samp{^NNTP-Posting-Host:\\|^Xref:\\|^Bcc:\\|^Gcc:\\|^Fcc:}.
+Regexp of headers to be removed before posting. The default is@*
+@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:}.
@item message-default-news-headers
@vindex message-default-news-headers
@item message-post-method
@vindex message-post-method
-Method used for posting a prepared news message.
+Gnusish @dfn{select method} (see the Gnus manual for details) used for
+posting a prepared news message.
@end table
@item message-setup-hook
@vindex message-setup-hook
-Hook run as the last thing when the message buffer has been initialized.
+Hook run as the last thing when the message buffer has been initialized,
+but before yanked text is inserted.
@item message-header-setup-hook
@vindex message-header-setup-hook
Hook called narrowed to the headers after initializing the headers.
+For instance, if you're running Gnus and wish to insert a
+@samp{Mail-Copies-To} header in all your news articles and all messages
+you send to mailing lists, you could do something like the following:
+
+@lisp
+(defun my-message-header-setup-hook ()
+ (let ((group (or gnus-newsgroup-name "")))
+ (when (or (message-fetch-field "newsgroups")
+ (gnus-group-find-parameter group 'to-address)
+ (gnus-group-find-parameter group 'to-list))
+ (insert "Mail-Copies-To: never\n"))))
+
+(add-hook 'message-header-setup-hook
+ 'my-message-header-setup-hook)
+@end lisp
+
@item message-send-hook
@vindex message-send-hook
Hook run before sending messages.
+If you want to add certain headers before sending, you can use the
+@code{message-add-header} function in this hook. For instance:
+@findex message-add-header
+
+@lisp
+(add-hook 'message-send-hook 'my-message-add-content)
+(defun my-message-add-content ()
+ (message-add-header
+ "Mime-Version: 1.0"
+ "Content-Type: text/plain"
+ "Content-Transfer-Encoding: 7bit"))
+@end lisp
+
+This function won't add the header if the header is already present.
+
+@item message-send-mail-hook
+@vindex message-send-mail-hook
+Hook run before sending mail messages.
+
+@item message-send-news-hook
+@vindex message-send-news-hook
+Hook run before sending news messages.
+
@item message-sent-hook
@vindex message-sent-hook
Hook run after sending messages.
@vindex message-mode-syntax-table
Syntax table used in message mode buffers.
+@item message-send-method-alist
+@vindex message-send-method-alist
+
+Alist of ways to send outgoing messages. Each element has the form
+
+@lisp
+(TYPE PREDICATE FUNCTION)
+@end lisp
+
+@table @var
+@item type
+A symbol that names the method.
+
+@item predicate
+A function called without any parameters to determine whether the
+message is a message of type @var{type}.
+
+@item function
+A function to be called if @var{predicate} returns non-@code{nil}.
+@var{function} is called with one parameter -- the prefix.
+@end table
+
+@lisp
+((news message-news-p message-send-via-news)
+ (mail message-mail-p message-send-via-mail))
+@end lisp
+
+
+
@end table
@vindex message-fcc-handler-function
A function called to save outgoing articles. This function will be
called with the name of the file to store the article in. The default
-function is @code{rmail-output} which saves in Unix mailbox format.
+function is @code{message-output} which saves in Unix mailbox format.
@item message-courtesy-message
@vindex message-courtesy-message
When sending combined messages, this string is inserted at the start of
-the mailed copy. If this variable is @code{nil}, no such courtesy
-message will be added.
+the mailed copy. If the string contains the format spec @samp{%s}, the
+newsgroups the article has been posted to will be inserted there. If
+this variable is @code{nil}, no such courtesy message will be added.
+The default value is @samp{"The following message is a courtesy copy of
+an article\nthat has been posted to %s as well.\n\n"}.
@end table
Message will generate new buffers with unique buffer names when you
request a message buffer. When you send the message, the buffer isn't
-normally killed off. It's name is changed and a certain number of old
+normally killed off. Its name is changed and a certain number of old
message buffers are kept alive.
@table @code
@item message-generate-new-buffers
-@findex message-generate-new-buffers
-If non-@code{nil}, generate new buffers. The default is @code{t}.
+@vindex message-generate-new-buffers
+If non-@code{nil}, generate new buffers. The default is @code{t}. If
+this is a function, call that function with three parameters: The type,
+the to address and the group name. (Any of these may be @code{nil}.)
+The function should return the new buffer name.
@item message-max-buffers
-@findex message-max-buffers
+@vindex message-max-buffers
This variable says how many old message buffers to keep. If there are
more message buffers than this, the oldest buffer will be killed. The
default is 10. If this variable is @code{nil}, no old message buffers
will ever be killed.
+@item message-send-rename-function
+@vindex message-send-rename-function
+After sending a message, the buffer is renamed from, for instance,
+@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't
+like this, set this variable to a function that renames the buffer in a
+manner you like. If you don't want to rename the buffer at all, you can
+say:
+
+@lisp
+(setq message-send-rename-function 'ignore)
+@end lisp
+
@item message-kill-buffer-on-exit
@findex message-kill-buffer-on-exit
If non-@code{nil}, kill the buffer immediately on exit.
This restores the Gnus window configuration when the message buffer is
killed, postponed or exited.
-An @dfn{action} can be either a normal function; or a list where the
-@code{car} is a function and the @code{cdr} is the list of arguments; or
+An @dfn{action} can be either: a normal function, or a list where the
+@code{car} is a function and the @code{cdr} is the list of arguments, or
a form to be @code{eval}ed.
+
+@node Compatibility
+@chapter Compatibility
+@cindex compatibility
+
+Message uses virtually only its own variables---older @code{mail-}
+variables aren't consulted. To force Message to take those variables
+into account, you can put the following in your @code{.emacs} file:
+
+@lisp
+(require 'messcompat)
+@end lisp
+
+This will initialize many Message variables from the values in the
+corresponding mail variables.
+
+
+@node Appendices
+@chapter Appendices
+
+@menu
+* Responses:: Standard rules for determining where responses go.
+@end menu
+
+
+@node Responses
+@section Responses
+
+To determine where a message is to go, the following algorithm is used
+by default.
+
+@table @dfn
+@item reply
+A @dfn{reply} is when you want to respond @emph{just} to the person who
+sent the message via mail. There will only be one recipient. To
+determine who the recipient will be, the following headers are
+consulted, in turn:
+
+@table @code
+@item Reply-To
+
+@item From
+@end table
+
+
+@item wide reply
+A @dfn{wide reply} is a mail response that includes @emph{all} entities
+mentioned in the message you are responded to. All mailboxes from the
+following headers will be concatenated to form the outgoing
+@code{To}/@code{Cc} headers:
+
+@table @code
+@item From
+(unless there's a @code{Reply-To}, in which case that is used instead).
+
+@item Cc
+
+@item To
+@end table
+
+If a @code{Mail-Copies-To} header is present, it will also be included
+in the list of mailboxes. If this header is @samp{never}, that means
+that the @code{From} (or @code{Reply-To}) mailbox will be suppressed.
+
+
+@item followup
+A @dfn{followup} is a response sent via news. The following headers
+(listed in order of precedence) determine where the response is to be
+sent:
+
+@table @code
+
+@item Followup-To
+
+@item Newsgroups
+
+@end table
+
+If a @code{Mail-Copies-To} header is present, it will be used as the
+basis of the new @code{Cc} header, except if this header is
+@samp{never}.
+
+@end table
+
+
+
@node Index
@chapter Index
@printindex cp
projects / gnus / blobdiff