*** empty log message ***
[emacs.git] / man / message.texi
blobbc288f5c7502152de6d62a0ced9b4b178de55c52
1 \input texinfo                  @c -*-texinfo-*-
3 @setfilename ../info/message
4 @settitle Message 5.9.0 Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8 @dircategory Editors
9 @direntry
10 * Message: (message).   Mail and news composition mode that goes with Gnus.
11 @end direntry
12 @iftex
13 @finalout
14 @end iftex
15 @setchapternewpage odd
17 @ifnottex
19 This file documents Message, the Emacs message composition mode.
21 Copyright (C) 1996,97,98,99,2000 Free Software Foundation, Inc.
23 Permission is granted to copy, distribute and/or modify this document
24 under the terms of the GNU Free Documentation License, Version 1.1 or
25 any later version published by the Free Software Foundation; with no
26 Invariant Sections, with the Front-Cover texts being ``A GNU
27 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
28 license is included in the section entitled ``GNU Free Documentation
29 License'' in the Emacs manual.
31 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
32 this GNU Manual, like GNU software.  Copies published by the Free
33 Software Foundation raise funds for GNU development.''
35 This document is part of a collection distributed under the GNU Free
36 Documentation License.  If you want to distribute this document
37 separately from the collection, you can do so by adding a copy of the
38 license to the document, as described in section 6 of the license.
39 @end ifnottex
41 @tex
43 @titlepage
44 @title Message 5.9.0 Manual
46 @author by Lars Magne Ingebrigtsen
47 @page
49 @vskip 0pt plus 1filll
50 Copyright @copyright{} 1996,97,98,99,2000 Free Software Foundation, Inc.
52 Permission is granted to copy, distribute and/or modify this document
53 under the terms of the GNU Free Documentation License, Version 1.1 or
54 any later version published by the Free Software Foundation; with the
55 Invariant Sections being none, with the Front-Cover texts being ``A GNU
56 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
57 license is included in the section entitled ``GNU Free Documentation
58 License'' in the Emacs manual.
60 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
61 this GNU Manual, like GNU software.  Copies published by the Free
62 Software Foundation raise funds for GNU development.''
64 This document is part of a collection distributed under the GNU Free
65 Documentation License.  If you want to distribute this document
66 separately from the collection, you can do so by adding a copy of the
67 license to the document, as described in section 6 of the license.
68 @end titlepage
69 @page
71 @end tex
73 @node Top
74 @top Message
76 All message composition from Gnus (both mail and news) takes place in
77 Message mode buffers.
79 @menu
80 * Interface::         Setting up message buffers.
81 * Commands::          Commands you can execute in message mode buffers.
82 * Variables::         Customizing the message buffers.
83 * Compatibility::     Making Message backwards compatible.
84 * Appendices::        More technical things.
85 * Index::             Variable, function and concept index.
86 * Key Index::         List of Message mode keys.
87 @end menu
89 This manual corresponds to Message 5.9.0.  Message is distributed with
90 the Gnus distribution bearing the same version number as this manual.
93 @node Interface
94 @chapter Interface
96 When a program (or a person) wants to respond to a message -- reply,
97 follow up, forward, cancel -- the program (or person) should just put
98 point in the buffer where the message is and call the required command.
99 @code{Message} will then pop up a new @code{message} mode buffer with
100 appropriate headers filled out, and the user can edit the message before
101 sending it.
103 @menu
104 * New Mail Message::     Editing a brand new mail message.
105 * New News Message::     Editing a brand new news message.
106 * Reply::                Replying via mail.
107 * Wide Reply::           Responding to all people via mail.
108 * Followup::             Following up via news.
109 * Canceling News::       Canceling a news article.
110 * Superseding::          Superseding a message.
111 * Forwarding::           Forwarding a message via news or mail.
112 * Resending::            Resending a mail message.
113 * Bouncing::             Bouncing a mail message.
114 @end menu
117 @node New Mail Message
118 @section New Mail Message
120 @findex message-mail
121 The @code{message-mail} command pops up a new message buffer.
123 Two optional parameters are accepted: The first will be used as the
124 @code{To} header and the second as the @code{Subject} header.  If these
125 are @code{nil}, those two headers will be empty.
128 @node New News Message
129 @section New News Message
131 @findex message-news
132 The @code{message-news} command pops up a new message buffer.
134 This function accepts two optional parameters.  The first will be used
135 as the @code{Newsgroups} header and the second as the @code{Subject}
136 header.  If these are @code{nil}, those two headers will be empty.
139 @node Reply
140 @section Reply
142 @findex message-reply
143 The @code{message-reply} function pops up a message buffer that's a
144 reply to the message in the current buffer.
146 @vindex message-reply-to-function
147 Message uses the normal methods to determine where replies are to go
148 (@pxref{Responses}), but you can change the behavior to suit your needs
149 by fiddling with the @code{message-reply-to-function} variable.
151 If you want the replies to go to the @code{Sender} instead of the
152 @code{From}, you could do something like this:
154 @lisp
155 (setq message-reply-to-function
156       (lambda ()
157        (cond ((equal (mail-fetch-field "from") "somebody")
158                (list (cons 'To (mail-fetch-field "sender"))))
159              (t
160               nil))))
161 @end lisp
163 This function will be called narrowed to the head of the article that is
164 being replied to.
166 As you can see, this function should return a string if it has an
167 opinion as to what the To header should be.  If it does not, it should
168 just return @code{nil}, and the normal methods for determining the To
169 header will be used.
171 This function can also return a list.  In that case, each list element
172 should be a cons, where the car should be the name of an header
173 (eg. @code{Cc}) and the cdr should be the header value
174 (eg. @samp{larsi@@ifi.uio.no}).  All these headers will be inserted into
175 the head of the outgoing mail.
178 @node Wide Reply
179 @section Wide Reply
181 @findex message-wide-reply
182 The @code{message-wide-reply} pops up a message buffer that's a wide
183 reply to the message in the current buffer.  A @dfn{wide reply} is a
184 reply that goes out to all people listed in the @code{To}, @code{From}
185 (or @code{Reply-to}) and @code{Cc} headers.
187 @vindex message-wide-reply-to-function
188 Message uses the normal methods to determine where wide replies are to go,
189 but you can change the behavior to suit your needs by fiddling with the
190 @code{message-wide-reply-to-function}.  It is used in the same way as
191 @code{message-reply-to-function} (@pxref{Reply}).
193 @findex message-dont-reply-to-names
194 Addresses that match the @code{message-dont-reply-to-names} regular
195 expression will be removed from the @code{Cc} header.
198 @node Followup
199 @section Followup
201 @findex message-followup
202 The @code{message-followup} command pops up a message buffer that's a
203 followup to the message in the current buffer.
205 @vindex message-followup-to-function
206 Message uses the normal methods to determine where followups are to go,
207 but you can change the behavior to suit your needs by fiddling with the
208 @code{message-followup-to-function}.  It is used in the same way as
209 @code{message-reply-to-function} (@pxref{Reply}).
211 @vindex message-use-followup-to
212 The @code{message-use-followup-to} variable says what to do about
213 @code{Followup-To} headers.  If it is @code{use}, always use the value.
214 If it is @code{ask} (which is the default), ask whether to use the
215 value.  If it is @code{t}, use the value unless it is @samp{poster}.  If
216 it is @code{nil}, don't use the value.
219 @node Canceling News
220 @section Canceling News
222 @findex message-cancel-news
223 The @code{message-cancel-news} command cancels the article in the
224 current buffer.
227 @node Superseding
228 @section Superseding
230 @findex message-supersede
231 The @code{message-supersede} command pops up a message buffer that will
232 supersede the message in the current buffer.
234 @vindex message-ignored-supersedes-headers
235 Headers matching the @code{message-ignored-supersedes-headers} are
236 removed before popping up the new message buffer.  The default is@*
237 @samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@*
238 ^Received:\\|^X-From-Line:\\|Return-Path:\\|^Supersedes:}.
242 @node Forwarding
243 @section Forwarding
245 @findex message-forward
246 The @code{message-forward} command pops up a message buffer to forward
247 the message in the current buffer.  If given a prefix, forward using
248 news.
250 @table @code
251 @item message-forward-ignored-headers
252 @vindex message-forward-ignored-headers
253 All headers that match this regexp will be deleted when forwarding a message.
255 @item message-make-forward-subject-function
256 @vindex message-make-forward-subject-function
257 A list of functions that are called to generate a subject header for
258 forwarded messages.  The subject generated by the previous function is
259 passed into each successive function.
261 The provided functions are:
263 @table @code
264 @item message-forward-subject-author-subject
265 @findex message-forward-subject-author-subject
266 Source of article (author or newsgroup), in brackets followed by the
267 subject.
269 @item message-forward-subject-fwd
270 Subject of article with @samp{Fwd:} prepended to it.
271 @end table
273 @item message-wash-forwarded-subjects
274 @vindex message-wash-forwarded-subjects
275 If this variable is @code{t}, the subjects of forwarded messages have
276 the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:},
277 @samp{(fwd)}) removed before the new subject is
278 constructed.  The default value is @code{nil}.
280 @item message-forward-as-mime
281 @vindex message-forward-as-mime
282 If this variable is @code{t} (the default), forwarded messages are
283 included as inline MIME RFC822 parts.  If it's @code{nil}, forwarded
284 messages will just be copied inline to the new message, like previous,
285 non MIME-savvy versions of gnus would do.
286 @end table
289 @node Resending
290 @section Resending
292 @findex message-resend
293 The @code{message-resend} command will prompt the user for an address
294 and resend the message in the current buffer to that address.
296 @vindex message-ignored-resent-headers
297 Headers that match the @code{message-ignored-resent-headers} regexp will
298 be removed before sending the message.  The default is
299 @samp{^Return-receipt}.
302 @node Bouncing
303 @section Bouncing
305 @findex message-bounce
306 The @code{message-bounce} command will, if the current buffer contains a
307 bounced mail message, pop up a message buffer stripped of the bounce
308 information.  A @dfn{bounced message} is typically a mail you've sent
309 out that has been returned by some @code{mailer-daemon} as
310 undeliverable.
312 @vindex message-ignored-bounced-headers
313 Headers that match the @code{message-ignored-bounced-headers} regexp
314 will be removed before popping up the buffer.  The default is
315 @samp{^\\(Received\\|Return-Path\\):}.
318 @node Commands
319 @chapter Commands
321 @menu
322 * Header Commands::     Commands for moving to headers.
323 * Movement::            Moving around in message buffers.
324 * Insertion::           Inserting things into message buffers.
325 * MIME::                @sc{mime} considerations.
326 * Various Commands::    Various things.
327 * Sending::             Actually sending the message.
328 * Mail Aliases::        How to use mail aliases.
329 @end menu
332 @node Header Commands
333 @section Header Commands
335 All these commands move to the header in question.  If it doesn't exist,
336 it will be inserted.
338 @table @kbd
340 @item C-c ?
341 @kindex C-c ?
342 @findex message-goto-to
343 Describe the message mode.
345 @item C-c C-f C-t
346 @kindex C-c C-f C-t
347 @findex message-goto-to
348 Go to the @code{To} header (@code{message-goto-to}).
350 @item C-c C-f C-b
351 @kindex C-c C-f C-b
352 @findex message-goto-bcc
353 Go to the @code{Bcc} header (@code{message-goto-bcc}).
355 @item C-c C-f C-f
356 @kindex C-c C-f C-f
357 @findex message-goto-fcc
358 Go to the @code{Fcc} header (@code{message-goto-fcc}).
360 @item C-c C-f C-c
361 @kindex C-c C-f C-c
362 @findex message-goto-cc
363 Go to the @code{Cc} header (@code{message-goto-cc}).
365 @item C-c C-f C-s
366 @kindex C-c C-f C-s
367 @findex message-goto-subject
368 Go to the @code{Subject} header (@code{message-goto-subject}).
370 @item C-c C-f C-r
371 @kindex C-c C-f C-r
372 @findex message-goto-reply-to
373 Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
375 @item C-c C-f C-n
376 @kindex C-c C-f C-n
377 @findex message-goto-newsgroups
378 Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
380 @item C-c C-f C-d
381 @kindex C-c C-f C-d
382 @findex message-goto-distribution
383 Go to the @code{Distribution} header (@code{message-goto-distribution}).
385 @item C-c C-f C-o
386 @kindex C-c C-f C-o
387 @findex message-goto-followup-to
388 Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
390 @item C-c C-f C-k
391 @kindex C-c C-f C-k
392 @findex message-goto-keywords
393 Go to the @code{Keywords} header (@code{message-goto-keywords}).
395 @item C-c C-f C-u
396 @kindex C-c C-f C-u
397 @findex message-goto-summary
398 Go to the @code{Summary} header (@code{message-goto-summary}).
400 @end table
403 @node Movement
404 @section Movement
406 @table @kbd
407 @item C-c C-b
408 @kindex C-c C-b
409 @findex message-goto-body
410 Move to the beginning of the body of the message
411 (@code{message-goto-body}).
413 @item C-c C-i
414 @kindex C-c C-i
415 @findex message-goto-signature
416 Move to the signature of the message (@code{message-goto-signature}).
418 @end table
421 @node Insertion
422 @section Insertion
424 @table @kbd
426 @item C-c C-y
427 @kindex C-c C-y
428 @findex message-yank-original
429 Yank the message that's being replied to into the message buffer
430 (@code{message-yank-original}).
432 @item C-c M-C-y
433 @kindex C-c M-C-y
434 @findex message-yank-buffer
435 Prompt for a buffer name and yank the contents of that buffer into the
436 message buffer (@code{message-yank-buffer}).
438 @item C-c C-q
439 @kindex C-c C-q
440 @findex message-fill-yanked-message
441 Fill the yanked message (@code{message-fill-yanked-message}).  Warning:
442 Can severely mess up the yanked text if its quoting conventions are
443 strange.  You'll quickly get a feel for when it's safe, though.  Anyway,
444 just remember that @kbd{C-x u} (@code{undo}) is available and you'll be
445 all right.
447 @item C-c C-w
448 @kindex C-c C-w
449 @findex message-insert-signature
450 Insert a signature at the end of the buffer
451 (@code{message-insert-signature}).
453 @item C-c M-h
454 @kindex C-c M-h
455 @findex message-insert-headers
456 Insert the message headers (@code{message-insert-headers}).
458 @end table
460 @table @code
461 @item message-ignored-cited-headers
462 @vindex message-ignored-cited-headers
463 All headers that match this regexp will be removed from yanked
464 messages.  The default is @samp{.}, which means that all headers will be
465 removed.
467 @item message-citation-line-function
468 @vindex message-citation-line-function
469 Function called to insert the citation line.  The default is
470 @code{message-insert-citation-line}, which will lead to citation lines
471 that look like:
473 @example
474 Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
475 @end example
477 Point will be at the beginning of the body of the message when this
478 function is called.
480 @item message-yank-prefix
481 @vindex message-yank-prefix
482 @cindex yanking
483 @cindex quoting
484 When you are replying to or following up an article, you normally want
485 to quote the person you are answering.  Inserting quoted text is done by
486 @dfn{yanking}, and each quoted line you yank will have
487 @code{message-yank-prefix} prepended to it.  The default is @samp{> }.
489 @item message-indentation-spaces
490 @vindex message-indentation-spaces
491 Number of spaces to indent yanked messages.
493 @item message-cite-function
494 @vindex message-cite-function
495 @findex message-cite-original
496 @findex sc-cite-original
497 @findex message-cite-original-without-signature
498 @cindex Supercite
499 Function for citing an original message.  The default is
500 @code{message-cite-original}, which simply inserts the original message
501 and prepends @samp{> } to each line.
502 @code{message-cite-original-without-signature} does the same, but elides
503 the signature.  You can also set it to @code{sc-cite-original} to use
504 Supercite.
506 @item message-indent-citation-function
507 @vindex message-indent-citation-function
508 Function for modifying a citation just inserted in the mail buffer.
509 This can also be a list of functions.  Each function can find the
510 citation between @code{(point)} and @code{(mark t)}.  And each function
511 should leave point and mark around the citation text as modified.
513 @item message-signature
514 @vindex message-signature
515 String to be inserted at the end of the message buffer.  If @code{t}
516 (which is the default), the @code{message-signature-file} file will be
517 inserted instead.  If a function, the result from the function will be
518 used instead.  If a form, the result from the form will be used instead.
519 If this variable is @code{nil}, no signature will be inserted at all.
521 @item message-signature-file
522 @vindex message-signature-file
523 File containing the signature to be inserted at the end of the buffer.
524 The default is @samp{~/.signature}.
526 @end table
528 Note that RFC1036bis says that a signature should be preceded by the three
529 characters @samp{-- } on a line by themselves.  This is to make it
530 easier for the recipient to automatically recognize and process the
531 signature.  So don't remove those characters, even though you might feel
532 that they ruin your beautiful design, like, totally.
534 Also note that no signature should be more than four lines long.
535 Including ASCII graphics is an efficient way to get everybody to believe
536 that you are silly and have nothing important to say.
539 @node MIME
540 @section MIME
541 @cindex MML
542 @cindex MIME
543 @cindex multipart
544 @cindex attachment
546 Message is a @sc{mime}-compliant posting agent.  The user generally
547 doesn't have to do anything to make the @sc{mime} happen---Message will
548 automatically add the @code{Content-Type} and
549 @code{Content-Transfer-Encoding} headers.
551 The most typical thing users want to use the multipart things in
552 @sc{mime} for is to add ``attachments'' to mail they send out.  This can
553 be done with the @code{C-c C-a} command, which will prompt for a file
554 name and a @sc{mime} type.
556 You can also create arbitrarily complex multiparts using the MML
557 language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME
558 Manual}).
561 @node Various Commands
562 @section Various Commands
564 @table @kbd
566 @item C-c C-r
567 @kindex C-c C-r
568 @findex message-caesar-buffer-body
569 Caesar rotate (aka. rot13) the current message
570 (@code{message-caesar-buffer-body}).  If narrowing is in effect, just
571 rotate the visible portion of the buffer.  A numerical prefix says how
572 many places to rotate the text.  The default is 13.
574 @item C-c C-e
575 @kindex C-c C-e
576 @findex message-elide-region
577 Elide the text between point and mark (@code{message-elide-region}).
578 The text is killed and replaced with the contents of the variable
579 @code{message-elide-ellipsis}. The default value is to use an ellipsis
580 (@samp{[...]}).
582 @item C-c C-z
583 @kindex C-c C-x
584 @findex message-kill-to-signature
585 Kill all the text up to the signature, or if that's missing, up to the
586 end of the message (@code{message-kill-to-signature}).
588 @item C-c C-v
589 @kindex C-c C-v
590 @findex message-delete-not-region
591 Delete all text in the body of the message that is outside the region
592 (@code{message-delete-not-region}).
594 @item M-RET
595 @kindex M-RET
596 @kindex message-newline-and-reformat
597 Insert four newlines, and then reformat if inside quoted text.
599 Here's an example:
601 @example
602 > This is some quoted text.  And here's more quoted text.
603 @end example
605 If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
607 @example
608 > This is some quoted text.
612 > And here's more quoted text.
613 @end example
615 @samp{*} says where point will be placed.
617 @item C-c C-t
618 @kindex C-c C-t
619 @findex message-insert-to
620 Insert a @code{To} header that contains the @code{Reply-To} or
621 @code{From} header of the message you're following up
622 (@code{message-insert-to}).
624 @item C-c C-n
625 @kindex C-c C-n
626 @findex message-insert-newsgroups
627 Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
628 or @code{Newsgroups} header of the article you're replying to
629 (@code{message-insert-newsgroups}).
631 @item C-c M-r
632 @kindex C-c M-r
633 @findex message-rename-buffer
634 Rename the buffer (@code{message-rename-buffer}).  If given a prefix,
635 prompt for a new buffer name.
637 @end table
640 @node Sending
641 @section Sending
643 @table @kbd
644 @item C-c C-c
645 @kindex C-c C-c
646 @findex message-send-and-exit
647 Send the message and bury the current buffer
648 (@code{message-send-and-exit}).
650 @item C-c C-s
651 @kindex C-c C-s
652 @findex message-send
653 Send the message (@code{message-send}).
655 @item C-c C-d
656 @kindex C-c C-d
657 @findex message-dont-send
658 Bury the message buffer and exit (@code{message-dont-send}).
660 @item C-c C-k
661 @kindex C-c C-k
662 @findex message-kill-buffer
663 Kill the message buffer and exit (@code{message-kill-buffer}).
665 @end table
669 @node Mail Aliases
670 @section Mail Aliases
671 @cindex mail aliases
672 @cindex aliases
674 @vindex message-mail-alias-type
675 The @code{message-mail-alias-type} variable controls what type of mail
676 alias expansion to use.  Currently only one form is supported---Message
677 uses @code{mailabbrev} to handle mail aliases.  If this variable is
678 @code{nil}, no mail alias expansion will be performed.
680 @code{mailabbrev} works by parsing the @file{/etc/mailrc} and
681 @file{~/.mailrc} files.  These files look like:
683 @example
684 alias lmi "Lars Magne Ingebrigtsen <larsi@@ifi.uio.no>"
685 alias ding "ding@@ifi.uio.no (ding mailing list)"
686 @end example
688 After adding lines like this to your @file{~/.mailrc} file, you should
689 be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so
690 on) headers and press @kbd{SPC} to expand the alias.
692 No expansion will be performed upon sending of the message---all
693 expansions have to be done explicitly.
697 @node Variables
698 @chapter Variables
700 @menu
701 * Message Headers::             General message header stuff.
702 * Mail Headers::                Customizing mail headers.
703 * Mail Variables::              Other mail variables.
704 * News Headers::                Customizing news headers.
705 * News Variables::              Other news variables.
706 * Various Message Variables::   Other message variables.
707 * Sending Variables::           Variables for sending.
708 * Message Buffers::             How Message names its buffers.
709 * Message Actions::             Actions to be performed when exiting.
710 @end menu
713 @node Message Headers
714 @section Message Headers
716 Message is quite aggressive on the message generation front.  It has to
717 be -- it's a combined news and mail agent.  To be able to send combined
718 messages, it has to generate all headers itself (instead of letting the
719 mail/news system do it) to ensure that mail and news copies of messages
720 look sufficiently similar.
722 @table @code
724 @item message-generate-headers-first
725 @vindex message-generate-headers-first
726 If non-@code{nil}, generate all headers before starting to compose the
727 message.
729 @item message-from-style
730 @vindex message-from-style
731 Specifies how @code{From} headers should look.  There are four valid
732 values:
734 @table @code
735 @item nil
736 Just the address -- @samp{king@@grassland.com}.
738 @item parens
739 @samp{king@@grassland.com (Elvis Parsley)}.
741 @item angles
742 @samp{Elvis Parsley <king@@grassland.com>}.
744 @item default
745 Look like @code{angles} if that doesn't require quoting, and
746 @code{parens} if it does.  If even @code{parens} requires quoting, use
747 @code{angles} anyway.
749 @end table
751 @item message-deletable-headers
752 @vindex message-deletable-headers
753 Headers in this list that were previously generated by Message will be
754 deleted before posting.  Let's say you post an article.  Then you decide
755 to post it again to some other group, you naughty boy, so you jump back
756 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
757 ship it off again.  By default, this variable makes sure that the old
758 generated @code{Message-ID} is deleted, and a new one generated.  If
759 this isn't done, the entire empire would probably crumble, anarchy would
760 prevail, and cats would start walking on two legs and rule the world.
761 Allegedly.
763 @item message-default-headers
764 @vindex message-default-headers
765 This string is inserted at the end of the headers in all message
766 buffers.
768 @item message-subject-re-regexp
769 @vindex message-subject-re-regexp
770 Responses to messages have subjects that start with @samp{Re: }.  This
771 is @emph{not} an abbreviation of the English word ``response'', but in
772 Latin, and means ``in response to''.  Some illiterate nincompoops have
773 failed to grasp this fact, and have ``internationalized'' their software
774 to use abonimations like @samp{Aw: } (``antwort'') or @samp{Sv: }
775 (``svar'') instead, which is meaningless and evil.  However, you may
776 have to deal with users that use these evil tools, in which case you may
777 set this variable to a regexp that matches these prefixes.  Myself, I
778 just throw away non-compliant mail.
780 @item message-alternative-emails
781 @vindex message-alternative-emails
782 A regexp to match the alternative email addresses.  The first matched
783 address (not primary one) is used in the @code{From} field.
785 @end table
788 @node Mail Headers
789 @section Mail Headers
791 @table @code
792 @item message-required-mail-headers
793 @vindex message-required-mail-headers
794 @xref{News Headers}, for the syntax of this variable.  It is
795 @code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
796 (optional . X-Mailer))} by default.
798 @item message-ignored-mail-headers
799 @vindex message-ignored-mail-headers
800 Regexp of headers to be removed before mailing.  The default is
801 @samp{^[GF]cc:\\|^Resent-Fcc:}.
803 @item message-default-mail-headers
804 @vindex message-default-mail-headers
805 This string is inserted at the end of the headers in all message
806 buffers that are initialized as mail.
808 @end table
811 @node Mail Variables
812 @section Mail Variables
814 @table @code
815 @item message-send-mail-function
816 @vindex message-send-mail-function
817 Function used to send the current buffer as mail.  The default is
818 @code{message-send-mail-with-sendmail}.   If you prefer using MH
819 instead, set this variable to @code{message-send-mail-with-mh}.
821 @item message-mh-deletable-headers
822 @vindex message-mh-deletable-headers
823 Most versions of MH doesn't like being fed messages that contain the
824 headers in this variable.  If this variable is non-@code{nil} (which is
825 the default), these headers will be removed before mailing when sending
826 messages via MH.  Set it to @code{nil} if your MH can handle these
827 headers.
829 @end table
832 @node News Headers
833 @section News Headers
835 @vindex message-required-news-headers
836 @code{message-required-news-headers} a list of header symbols.  These
837 headers will either be automatically generated, or, if that's
838 impossible, they will be prompted for.  The following symbols are valid:
840 @table @code
842 @item From
843 @cindex From
844 @findex user-full-name
845 @findex user-mail-address
846 This required header will be filled out with the result of the
847 @code{message-make-from} function, which depends on the
848 @code{message-from-style}, @code{user-full-name},
849 @code{user-mail-address} variables.
851 @item Subject
852 @cindex Subject
853 This required header will be prompted for if not present already.
855 @item Newsgroups
856 @cindex Newsgroups
857 This required header says which newsgroups the article is to be posted
858 to.  If it isn't present already, it will be prompted for.
860 @item Organization
861 @cindex organization
862 This optional header will be filled out depending on the
863 @code{message-user-organization} variable.
864 @code{message-user-organization-file} will be used if this variable is
865 @code{t}.  This variable can also be a string (in which case this string
866 will be used), or it can be a function (which will be called with no
867 parameters and should return a string to be used).
869 @item Lines
870 @cindex Lines
871 This optional header will be computed by Message.
873 @item Message-ID
874 @cindex Message-ID
875 @vindex mail-host-address
876 @findex system-name
877 @cindex Sun
878 This required header will be generated by Message.  A unique ID will be
879 created based on the date, time, user name and system name.  Message
880 will use @code{system-name} to determine the name of the system.  If
881 this isn't a fully qualified domain name (FQDN), Message will use
882 @code{mail-host-address} as the FQDN of the machine.
884 @item X-Newsreader
885 @cindex X-Newsreader
886 This optional header will be filled out according to the
887 @code{message-newsreader} local variable.
889 @item X-Mailer
890 This optional header will be filled out according to the
891 @code{message-mailer} local variable, unless there already is an
892 @code{X-Newsreader} header present.
894 @item In-Reply-To
895 This optional header is filled out using the @code{Date} and @code{From}
896 header of the article being replied to.
898 @item Expires
899 @cindex Expires
900 This extremely optional header will be inserted according to the
901 @code{message-expires} variable.  It is highly deprecated and shouldn't
902 be used unless you know what you're doing.
904 @item Distribution
905 @cindex Distribution
906 This optional header is filled out according to the
907 @code{message-distribution-function} variable.  It is a deprecated and
908 much misunderstood header.
910 @item Path
911 @cindex path
912 This extremely optional header should probably never be used.
913 However, some @emph{very} old servers require that this header is
914 present.  @code{message-user-path} further controls how this
915 @code{Path} header is to look.  If it is @code{nil}, use the server name
916 as the leaf node.  If it is a string, use the string.  If it is neither
917 a string nor @code{nil}, use the user name only.  However, it is highly
918 unlikely that you should need to fiddle with this variable at all.
919 @end table
921 @findex yow
922 @cindex Mime-Version
923 In addition, you can enter conses into this list.  The car of this cons
924 should be a symbol.  This symbol's name is the name of the header, and
925 the cdr can either be a string to be entered verbatim as the value of
926 this header, or it can be a function to be called.  This function should
927 return a string to be inserted.  For instance, if you want to insert
928 @code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
929 into the list.  If you want to insert a funny quote, you could enter
930 something like @code{(X-Yow . yow)} into the list.  The function
931 @code{yow} will then be called without any arguments.
933 If the list contains a cons where the car of the cons is
934 @code{optional}, the cdr of this cons will only be inserted if it is
935 non-@code{nil}.
937 Other variables for customizing outgoing news articles:
939 @table @code
941 @item message-syntax-checks
942 @vindex message-syntax-checks
943 Controls what syntax checks should not be performed on outgoing posts.
944 To disable checking of long signatures, for instance, add
946 @lisp
947 (signature . disabled)
948 @end lisp
950 to this list.
952 Valid checks are:
954 @table @code
955 @item subject-cmsg
956 Check the subject for commands.
957 @item sender
958 @cindex Sender
959 Insert a new @code{Sender} header if the @code{From} header looks odd.
960 @item multiple-headers
961 Check for the existence of multiple equal headers.
962 @item sendsys
963 @cindex sendsys
964 Check for the existence of version and sendsys commands.
965 @item message-id
966 Check whether the @code{Message-ID} looks ok.
967 @item from
968 Check whether the @code{From} header seems nice.
969 @item long-lines
970 @cindex long lines
971 Check for too long lines.
972 @item control-chars
973 Check for invalid characters.
974 @item size
975 Check for excessive size.
976 @item new-text
977 Check whether there is any new text in the messages.
978 @item signature
979 Check the length of the signature.
980 @item approved
981 @cindex approved
982 Check whether the article has an @code{Approved} header, which is
983 something only moderators should include.
984 @item empty
985 Check whether the article is empty.
986 @item invisible-text
987 Check whether there is any invisible text in the buffer.
988 @item empty-headers
989 Check whether any of the headers are empty.
990 @item existing-newsgroups
991 Check whether the newsgroups mentioned in the @code{Newsgroups} and
992 @code{Followup-To} headers exist.
993 @item valid-newsgroups
994 Check whether the @code{Newsgroups} and @code{Followup-to} headers
995 are valid syntactically.
996 @item repeated-newsgroups
997 Check whether the @code{Newsgroups} and @code{Followup-to} headers
998 contains repeated group names.
999 @item shorten-followup-to
1000 Check whether to add a @code{Followup-to} header to shorten the number
1001 of groups to post to.
1002 @end table
1004 All these conditions are checked by default.
1006 @item message-ignored-news-headers
1007 @vindex message-ignored-news-headers
1008 Regexp of headers to be removed before posting.  The default is@*
1009 @samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:}.
1011 @item message-default-news-headers
1012 @vindex message-default-news-headers
1013 This string is inserted at the end of the headers in all message
1014 buffers that are initialized as news.
1016 @end table
1019 @node News Variables
1020 @section News Variables
1022 @table @code
1023 @item message-send-news-function
1024 @vindex message-send-news-function
1025 Function used to send the current buffer as news.  The default is
1026 @code{message-send-news}.
1028 @item message-post-method
1029 @vindex message-post-method
1030 Gnusish @dfn{select method} (see the Gnus manual for details) used for
1031 posting a prepared news message.
1033 @end table
1036 @node Various Message Variables
1037 @section Various Message Variables
1039 @table @code
1040 @item message-default-charset
1041 @vindex message-default-charset
1042 @cindex charset
1043 Symbol naming a @sc{mime} charset.  Non-ASCII characters in messages are
1044 assumed to be encoded using this charset.  The default is @code{nil},
1045 which means ask the user.  (This variable is used only on non-@sc{mule}
1046 Emacsen.  
1047 @xref{Charset Translation, , Charset Translation, emacs-mime, 
1048       Emacs MIME Manual}, for details on the @sc{mule}-to-@sc{mime}
1049 translation process.
1051 @item message-signature-separator
1052 @vindex message-signature-separator
1053 Regexp matching the signature separator.  It is @samp{^-- *$} by
1054 default.
1056 @item mail-header-separator
1057 @vindex mail-header-separator
1058 String used to separate the headers from the body.  It is @samp{--text
1059 follows this line--} by default.
1061 @item message-directory
1062 @vindex message-directory
1063 Directory used by many mailey things.  The default is @file{~/Mail/}.
1065 @item message-signature-setup-hook
1066 @vindex message-signature-setup-hook
1067 Hook run when initializing the message buffer.  It is run after the
1068 headers have been inserted but before the signature has been inserted.
1070 @item message-setup-hook
1071 @vindex message-setup-hook
1072 Hook run as the last thing when the message buffer has been initialized,
1073 but before yanked text is inserted.
1075 @item message-header-setup-hook
1076 @vindex message-header-setup-hook
1077 Hook called narrowed to the headers after initializing the headers.
1079 For instance, if you're running Gnus and wish to insert a
1080 @samp{Mail-Copies-To} header in all your news articles and all messages
1081 you send to mailing lists, you could do something like the following:
1083 @lisp
1084 (defun my-message-header-setup-hook ()
1085   (let ((group (or gnus-newsgroup-name "")))
1086     (when (or (message-fetch-field "newsgroups")
1087               (gnus-group-find-parameter group 'to-address)
1088               (gnus-group-find-parameter group 'to-list))
1089       (insert "Mail-Copies-To: never\n"))))
1091 (add-hook 'message-header-setup-hook
1092           'my-message-header-setup-hook)
1093 @end lisp
1095 @item message-send-hook
1096 @vindex message-send-hook
1097 Hook run before sending messages.
1099 If you want to add certain headers before sending, you can use the
1100 @code{message-add-header} function in this hook.  For instance:
1101 @findex message-add-header
1103 @lisp
1104 (add-hook 'message-send-hook 'my-message-add-content)
1105 (defun my-message-add-content ()
1106   (message-add-header
1107    "X-In-No-Sense: Nonsense"
1108    "X-Whatever: no"))
1109 @end lisp
1111 This function won't add the header if the header is already present.
1113 @item message-send-mail-hook
1114 @vindex message-send-mail-hook
1115 Hook run before sending mail messages.
1117 @item message-send-news-hook
1118 @vindex message-send-news-hook
1119 Hook run before sending news messages.
1121 @item message-sent-hook
1122 @vindex message-sent-hook
1123 Hook run after sending messages.
1125 @item message-mode-syntax-table
1126 @vindex message-mode-syntax-table
1127 Syntax table used in message mode buffers.
1129 @item message-send-method-alist
1130 @vindex message-send-method-alist
1132 Alist of ways to send outgoing messages.  Each element has the form
1134 @lisp
1135 (TYPE PREDICATE FUNCTION)
1136 @end lisp
1138 @table @var
1139 @item type
1140 A symbol that names the method.
1142 @item predicate
1143 A function called without any parameters to determine whether the
1144 message is a message of type @var{type}.
1146 @item function
1147 A function to be called if @var{predicate} returns non-@code{nil}.
1148 @var{function} is called with one parameter -- the prefix.
1149 @end table
1151 @lisp
1152 ((news message-news-p message-send-via-news)
1153  (mail message-mail-p message-send-via-mail))
1154 @end lisp
1158 @end table
1162 @node Sending Variables
1163 @section Sending Variables
1165 @table @code
1167 @item message-fcc-handler-function
1168 @vindex message-fcc-handler-function
1169 A function called to save outgoing articles.  This function will be
1170 called with the name of the file to store the article in.  The default
1171 function is @code{message-output} which saves in Unix mailbox format.
1173 @item message-courtesy-message
1174 @vindex message-courtesy-message
1175 When sending combined messages, this string is inserted at the start of
1176 the mailed copy.  If the string contains the format spec @samp{%s}, the
1177 newsgroups the article has been posted to will be inserted there.  If
1178 this variable is @code{nil}, no such courtesy message will be added.
1179 The default value is @samp{"The following message is a courtesy copy of
1180 an article\nthat has been posted to %s as well.\n\n"}.
1182 @end table
1185 @node Message Buffers
1186 @section Message Buffers
1188 Message will generate new buffers with unique buffer names when you
1189 request a message buffer.  When you send the message, the buffer isn't
1190 normally killed off.  Its name is changed and a certain number of old
1191 message buffers are kept alive.
1193 @table @code
1194 @item message-generate-new-buffers
1195 @vindex message-generate-new-buffers
1196 If non-@code{nil}, generate new buffers.  The default is @code{t}.  If
1197 this is a function, call that function with three parameters: The type,
1198 the to address and the group name.  (Any of these may be @code{nil}.)
1199 The function should return the new buffer name.
1201 @item message-max-buffers
1202 @vindex message-max-buffers
1203 This variable says how many old message buffers to keep.  If there are
1204 more message buffers than this, the oldest buffer will be killed.  The
1205 default is 10.  If this variable is @code{nil}, no old message buffers
1206 will ever be killed.
1208 @item message-send-rename-function
1209 @vindex message-send-rename-function
1210 After sending a message, the buffer is renamed from, for instance,
1211 @samp{*reply to Lars*} to @samp{*sent reply to Lars*}.  If you don't
1212 like this, set this variable to a function that renames the buffer in a
1213 manner you like.  If you don't want to rename the buffer at all, you can
1214 say:
1216 @lisp
1217 (setq message-send-rename-function 'ignore)
1218 @end lisp
1220 @item message-kill-buffer-on-exit
1221 @findex message-kill-buffer-on-exit
1222 If non-@code{nil}, kill the buffer immediately on exit.
1224 @end table
1227 @node Message Actions
1228 @section Message Actions
1230 When Message is being used from a news/mail reader, the reader is likely
1231 to want to perform some task after the message has been sent.  Perhaps
1232 return to the previous window configuration or mark an article as
1233 replied.
1235 @vindex message-kill-actions
1236 @vindex message-postpone-actions
1237 @vindex message-exit-actions
1238 @vindex message-send-actions
1239 The user may exit from the message buffer in various ways.  The most
1240 common is @kbd{C-c C-c}, which sends the message and exits.  Other
1241 possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c
1242 C-d} which postpones the message editing and buries the message buffer,
1243 and @kbd{C-c C-k} which kills the message buffer.  Each of these actions
1244 have lists associated with them that contains actions to be executed:
1245 @code{message-send-actions}, @code{message-exit-actions},
1246 @code{message-postpone-actions}, and @code{message-kill-actions}.
1248 Message provides a function to interface with these lists:
1249 @code{message-add-action}.  The first parameter is the action to be
1250 added, and the rest of the arguments are which lists to add this action
1251 to.  Here's an example from Gnus:
1253 @lisp
1254   (message-add-action
1255    `(set-window-configuration ,(current-window-configuration))
1256    'exit 'postpone 'kill)
1257 @end lisp
1259 This restores the Gnus window configuration when the message buffer is
1260 killed, postponed or exited.
1262 An @dfn{action} can be either: a normal function, or a list where the
1263 @code{car} is a function and the @code{cdr} is the list of arguments, or
1264 a form to be @code{eval}ed.
1267 @node Compatibility
1268 @chapter Compatibility
1269 @cindex compatibility
1271 Message uses virtually only its own variables---older @code{mail-}
1272 variables aren't consulted.  To force Message to take those variables
1273 into account, you can put the following in your @code{.emacs} file:
1275 @lisp
1276 (require 'messcompat)
1277 @end lisp
1279 This will initialize many Message variables from the values in the
1280 corresponding mail variables.
1283 @node Appendices
1284 @chapter Appendices
1286 @menu
1287 * Responses::          Standard rules for determining where responses go.
1288 @end menu
1291 @node Responses
1292 @section Responses
1294 To determine where a message is to go, the following algorithm is used
1295 by default.
1297 @table @dfn
1298 @item reply
1299 A @dfn{reply} is when you want to respond @emph{just} to the person who
1300 sent the message via mail.  There will only be one recipient.  To
1301 determine who the recipient will be, the following headers are
1302 consulted, in turn:
1304 @table @code
1305 @item Reply-To
1307 @item From
1308 @end table
1311 @item wide reply
1312 A @dfn{wide reply} is a mail response that includes @emph{all} entities
1313 mentioned in the message you are responded to.  All mailboxes from the
1314 following headers will be concatenated to form the outgoing
1315 @code{To}/@code{Cc} headers:
1317 @table @code
1318 @item From
1319 (unless there's a @code{Reply-To}, in which case that is used instead).
1321 @item Cc
1323 @item To
1324 @end table
1326 If a @code{Mail-Copies-To} header is present, it will also be included
1327 in the list of mailboxes.  If this header is @samp{never}, that means
1328 that the @code{From} (or @code{Reply-To}) mailbox will be suppressed.
1331 @item followup
1332 A @dfn{followup} is a response sent via news.  The following headers
1333 (listed in order of precedence) determine where the response is to be
1334 sent:
1336 @table @code
1338 @item Followup-To
1340 @item Newsgroups
1342 @end table
1344 If a @code{Mail-Copies-To} header is present, it will be used as the
1345 basis of the new @code{Cc} header, except if this header is
1346 @samp{never}.
1348 @end table
1352 @node Index
1353 @chapter Index
1354 @printindex cp
1356 @node Key Index
1357 @chapter Key Index
1358 @printindex ky
1360 @summarycontents
1361 @contents
1362 @bye
1364 @c End: