(back_comment): Make sure we only consider comment-starters
[emacs.git] / man / message.texi
blob054b0036a7e2b2c7ecab961466011812540a5427
1 \input texinfo                  @c -*-texinfo-*-
3 @setfilename ../info/message
4 @settitle Message 5.7 Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8 @direntry
9 * Message: (message).   Mail and news composition mode that goes with Gnus.
10 @end direntry
11 @iftex
12 @finalout
13 @end iftex
14 @setchapternewpage odd
16 @ifinfo
18 This file documents Message, the Emacs message composition mode.
20 Copyright (C) 1996 Free Software Foundation, Inc.
22 Permission is granted to make and distribute verbatim copies of
23 this manual provided the copyright notice and this permission notice
24 are preserved on all copies.
26 @ignore
27 Permission is granted to process this file through Tex and print the
28 results, provided the printed document carries copying permission
29 notice identical to this one except for the removal of this paragraph
30 (this paragraph not being relevant to the printed manual).
32 @end ignore
33 Permission is granted to copy and distribute modified versions of this
34 manual under the conditions for verbatim copying, provided also that the
35 entire resulting derived work is distributed under the terms of a
36 permission notice identical to this one.
38 Permission is granted to copy and distribute translations of this manual
39 into another language, under the above conditions for modified versions.
40 @end ifinfo
42 @tex
44 @titlepage
45 @title Message 5.7 Manual
47 @author by Lars Magne Ingebrigtsen
48 @page
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1996 Free Software Foundation, Inc. 
53 Permission is granted to make and distribute verbatim copies of
54 this manual provided the copyright notice and this permission notice
55 are preserved on all copies.
57 Permission is granted to copy and distribute modified versions of this
58 manual under the conditions for verbatim copying, provided that the
59 entire resulting derived work is distributed under the terms of a
60 permission notice identical to this one.
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions.
65 @end titlepage
66 @page
68 @end tex
70 @node Top
71 @top Message
73 All message composition from Gnus (both mail and news) takes place in
74 Message mode buffers.
76 @menu
77 * Interface::         Setting up message buffers.
78 * Commands::          Commands you can execute in message mode buffers.
79 * Variables::         Customizing the message buffers.
80 * Compatibility::     Making Message backwards compatible.
81 * Appendices::        More technical things.
82 * Index::             Variable, function and concept index.
83 * Key Index::         List of Message mode keys.
84 @end menu
86 This manual corresponds to Message 5.7.  Message is distributed with
87 the Gnus distribution bearing the same version number as this manual
88 has. 
91 @node Interface
92 @chapter Interface
94 When a program (or a person) wants to respond to a message -- reply,
95 follow up, forward, cancel -- the program (or person) should just put
96 point in the buffer where the message is and call the required command.
97 @code{Message} will then pop up a new @code{message} mode buffer with
98 appropriate headers filled out, and the user can edit the message before
99 sending it.
101 @menu
102 * New Mail Message::     Editing a brand new mail message.
103 * New News Message::     Editing a brand new news message.
104 * Reply::                Replying via mail.
105 * Wide Reply::           Responding to all people via mail.
106 * Followup::             Following up via news.
107 * Canceling News::       Canceling a news article.
108 * Superseding::          Superseding a message.
109 * Forwarding::           Forwarding a message via news or mail.
110 * Resending::            Resending a mail message.
111 * Bouncing::             Bouncing a mail message.
112 @end menu
115 @node New Mail Message
116 @section New Mail Message
118 @findex message-mail
119 The @code{message-mail} command pops up a new message buffer.  
121 Two optional parameters are accepted: The first will be used as the
122 @code{To} header and the second as the @code{Subject} header.  If these
123 are @code{nil}, those two headers will be empty.
126 @node New News Message
127 @section New News Message
129 @findex message-news
130 The @code{message-news} command pops up a new message buffer.  
132 This function accepts two optional parameters.  The first will be used
133 as the @code{Newsgroups} header and the second as the @code{Subject}
134 header.  If these are @code{nil}, those two headers will be empty.
137 @node Reply
138 @section Reply
140 @findex message-reply
141 The @code{message-reply} function pops up a message buffer that's a
142 reply to the message in the current buffer.
144 @vindex message-reply-to-function
145 Message uses the normal methods to determine where replies are to go
146 (@pxref{Responses}), but you can change the behavior to suit your needs
147 by fiddling with the @code{message-reply-to-function} variable.
149 If you want the replies to go to the @code{Sender} instead of the
150 @code{From}, you could do something like this:
152 @lisp
153 (setq message-reply-to-function
154       (lambda ()
155        (cond ((equal (mail-fetch-field "from") "somebody")
156                (mail-fetch-field "sender"))     
157              (t 
158               nil))))
159 @end lisp
161 This function will be called narrowed to the head of the article that is
162 being replied to.
164 As you can see, this function should return a string if it has an
165 opinion as to what the To header should be.  If it does not, it should
166 just return @code{nil}, and the normal methods for determining the To
167 header will be used.
169 This function can also return a list.  In that case, each list element
170 should be a cons, where the car should be the name of an header
171 (eg. @code{Cc}) and the cdr should be the header value
172 (eg. @samp{larsi@@ifi.uio.no}).  All these headers will be inserted into
173 the head of the outgoing mail. 
176 @node Wide Reply
177 @section Wide Reply
179 @findex message-wide-reply
180 The @code{message-wide-reply} pops up a message buffer that's a wide
181 reply to the message in the current buffer.  A @dfn{wide reply} is a
182 reply that goes out to all people listed in the @code{To}, @code{From}
183 (or @code{Reply-to}) and @code{Cc} headers.
185 @vindex message-wide-reply-to-function
186 Message uses the normal methods to determine where wide replies are to go,
187 but you can change the behavior to suit your needs by fiddling with the
188 @code{message-wide-reply-to-function}.  It is used in the same way as
189 @code{message-reply-to-function} (@pxref{Reply}). 
191 @findex rmail-dont-reply-to-names
192 Addresses that match the @code{rmail-dont-reply-to-names} regular
193 expression will be removed from the @code{Cc} header.
196 @node Followup
197 @section Followup
199 @findex message-followup
200 The @code{message-followup} command pops up a message buffer that's a
201 followup to the message in the current buffer.
203 @vindex message-followup-to-function
204 Message uses the normal methods to determine where followups are to go,
205 but you can change the behavior to suit your needs by fiddling with the
206 @code{message-followup-to-function}.  It is used in the same way as
207 @code{message-reply-to-function} (@pxref{Reply}).
209 @vindex message-use-followup-to
210 The @code{message-use-followup-to} variable says what to do about
211 @code{Followup-To} headers.  If it is @code{use}, always use the value.
212 If it is @code{ask} (which is the default), ask whether to use the
213 value.  If it is @code{t}, use the value unless it is @samp{poster}.  If
214 it is @code{nil}, don't use the value.
217 @node Canceling News
218 @section Canceling News
220 @findex message-cancel-news
221 The @code{message-cancel-news} command cancels the article in the
222 current buffer.
225 @node Superseding
226 @section Superseding
228 @findex message-supersede
229 The @code{message-supersede} command pops up a message buffer that will
230 supersede the message in the current buffer.
232 @vindex message-ignored-supersedes-headers
233 Headers matching the @code{message-ignored-supersedes-headers} are
234 removed before popping up the new message buffer.  The default is@*
235 @samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@*
236 ^Received:\\|^X-From-Line:\\|Return-Path:\\|^Supersedes:}.
240 @node Forwarding
241 @section Forwarding
243 @findex message-forward
244 The @code{message-forward} command pops up a message buffer to forward
245 the message in the current buffer.  If given a prefix, forward using
246 news.
248 @table @code
249 @item message-forward-start-separator
250 @vindex message-forward-start-separator
251 Delimiter inserted before forwarded messages.  The default is@*
252 @samp{------- Start of forwarded message -------\n}. 
254 @vindex message-forward-end-separator
255 @item message-forward-end-separator
256 @vindex message-forward-end-separator
257 Delimiter inserted after forwarded messages.  The default is@*
258 @samp{------- End of forwarded message -------\n}. 
260 @item message-signature-before-forwarded-message
261 @vindex message-signature-before-forwarded-message
262 If this variable is @code{t}, which it is by default, your personal
263 signature will be inserted before the forwarded message.  If not, the
264 forwarded message will be inserted first in the new mail.
266 @item message-included-forward-headers
267 @vindex message-included-forward-headers
268 Regexp matching header lines to be included in forwarded messages.  
270 @item message-make-forward-subject-function
271 @vindex message-make-forward-subject-function
272 A list of functions that are called to generate a subject header for
273 forwarded messages.  The subject generated by the previous function is
274 passed into each successive function.
276 The provided functions are:
278 @table @code
279 @item message-forward-subject-author-subject
280 @findex message-forward-subject-author-subject
281 Source of article (author or newsgroup), in brackets followed by the
282 subject.
284 @item message-forward-subject-fwd
285 Subject of article with @samp{Fwd:} prepended to it.
286 @end table
288 @item message-wash-forwarded-subjects
289 @vindex message-wash-forwarded-subjects
290 If this variable is @code{t}, the subjects of forwarded messages have
291 the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:}, 
292 @samp{(fwd)}) removed before the new subject is
293 constructed.  The default value is @code{nil}.
295 @end table
298 @node Resending
299 @section Resending
301 @findex message-resend
302 The @code{message-resend} command will prompt the user for an address
303 and resend the message in the current buffer to that address.
305 @vindex message-ignored-resent-headers
306 Headers that match the @code{message-ignored-resent-headers} regexp will
307 be removed before sending the message.  The default is
308 @samp{^Return-receipt}. 
311 @node Bouncing
312 @section Bouncing
314 @findex message-bounce
315 The @code{message-bounce} command will, if the current buffer contains a
316 bounced mail message, pop up a message buffer stripped of the bounce
317 information.  A @dfn{bounced message} is typically a mail you've sent
318 out that has been returned by some @code{mailer-daemon} as
319 undeliverable. 
321 @vindex message-ignored-bounced-headers
322 Headers that match the @code{message-ignored-bounced-headers} regexp
323 will be removed before popping up the buffer.  The default is
324 @samp{^\\(Received\\|Return-Path\\):}.
327 @node Commands
328 @chapter Commands
330 @menu
331 * Header Commands::     Commands for moving to headers.
332 * Movement::            Moving around in message buffers.
333 * Insertion::           Inserting things into message buffers.
334 * Various Commands::    Various things.
335 * Sending::             Actually sending the message.
336 * Mail Aliases::        How to use mail aliases.
337 @end menu
340 @node Header Commands
341 @section Header Commands
343 All these commands move to the header in question.  If it doesn't exist,
344 it will be inserted.
346 @table @kbd
348 @item C-c ?
349 @kindex C-c ?
350 @findex message-goto-to
351 Describe the message mode.
353 @item C-c C-f C-t
354 @kindex C-c C-f C-t 
355 @findex message-goto-to
356 Go to the @code{To} header (@code{message-goto-to}).
358 @item C-c C-f C-b
359 @kindex C-c C-f C-b 
360 @findex message-goto-bcc
361 Go to the @code{Bcc} header (@code{message-goto-bcc}).
363 @item C-c C-f C-f
364 @kindex C-c C-f C-f 
365 @findex message-goto-fcc
366 Go to the @code{Fcc} header (@code{message-goto-fcc}).
368 @item C-c C-f C-c
369 @kindex C-c C-f C-c 
370 @findex message-goto-cc
371 Go to the @code{Cc} header (@code{message-goto-cc}).
373 @item C-c C-f C-s
374 @kindex C-c C-f C-s 
375 @findex message-goto-subject
376 Go to the @code{Subject} header (@code{message-goto-subject}).
378 @item C-c C-f C-r
379 @kindex C-c C-f C-r 
380 @findex message-goto-reply-to
381 Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
383 @item C-c C-f C-n
384 @kindex C-c C-f C-n 
385 @findex message-goto-newsgroups
386 Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
388 @item C-c C-f C-d
389 @kindex C-c C-f C-d 
390 @findex message-goto-distribution
391 Go to the @code{Distribution} header (@code{message-goto-distribution}).
393 @item C-c C-f C-o
394 @kindex C-c C-f C-o 
395 @findex message-goto-followup-to
396 Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
398 @item C-c C-f C-k
399 @kindex C-c C-f C-k 
400 @findex message-goto-keywords
401 Go to the @code{Keywords} header (@code{message-goto-keywords}).
403 @item C-c C-f C-u
404 @kindex C-c C-f C-u 
405 @findex message-goto-summary
406 Go to the @code{Summary} header (@code{message-goto-summary}).
408 @end table
411 @node Movement
412 @section Movement
414 @table @kbd
415 @item C-c C-b
416 @kindex C-c C-b 
417 @findex message-goto-body
418 Move to the beginning of the body of the message
419 (@code{message-goto-body}). 
421 @item C-c C-i
422 @kindex C-c C-i 
423 @findex message-goto-signature
424 Move to the signature of the message (@code{message-goto-signature}).
426 @end table
429 @node Insertion
430 @section Insertion
432 @table @kbd
434 @item C-c C-y
435 @kindex C-c C-y 
436 @findex message-yank-original
437 Yank the message that's being replied to into the message buffer
438 (@code{message-yank-original}). 
440 @item C-c C-q
441 @kindex C-c C-q 
442 @findex message-fill-yanked-message
443 Fill the yanked message (@code{message-fill-yanked-message}).  Warning:
444 Can severely mess up the yanked text if its quoting conventions are
445 strange.  You'll quickly get a feel for when it's safe, though.  Anyway,
446 just remember that @kbd{C-x u} (@code{undo}) is available and you'll be
447 all right.
450 @item C-c C-w
451 @kindex C-c C-w 
452 @findex message-insert-signature
453 Insert a signature at the end of the buffer
454 (@code{message-insert-signature}).  
456 @end table
458 @table @code
459 @item message-ignored-cited-headers
460 @vindex message-ignored-cited-headers
461 All headers that match this regexp will be removed from yanked
462 messages.  The default is @samp{.}, which means that all headers will be
463 removed.
465 @item message-citation-line-function
466 @vindex message-citation-line-function
467 Function called to insert the citation line.  The default is
468 @code{message-insert-citation-line}, which will lead to citation lines
469 that look like:
471 @example
472 Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
473 @end example
475 Point will be at the beginning of the body of the message when this
476 function is called.
478 @item message-yank-prefix
479 @vindex message-yank-prefix
480 @cindex yanking
481 @cindex quoting
482 When you are replying to or following up an article, you normally want
483 to quote the person you are answering.  Inserting quoted text is done by
484 @dfn{yanking}, and each quoted line you yank will have
485 @code{message-yank-prefix} prepended to it.  The default is @samp{> }.
486 If it is @code{nil}, just indent the message.
488 @item message-indentation-spaces
489 @vindex message-indentation-spaces
490 Number of spaces to indent yanked messages.
492 @item message-cite-function
493 @vindex message-cite-function
494 @findex message-cite-original
495 @findex sc-cite-original
496 @findex message-cite-original-without-signature
497 @cindex Supercite
498 Function for citing an original message.  The default is
499 @code{message-cite-original}, which simply inserts the original message
500 and prepends @samp{> } to each line.
501 @code{message-cite-original-without-signature} does the same, but elides
502 the signature.  You can also set it to @code{sc-cite-original} to use
503 Supercite.
505 @item message-indent-citation-function
506 @vindex message-indent-citation-function
507 Function for modifying a citation just inserted in the mail buffer.
508 This can also be a list of functions.  Each function can find the
509 citation between @code{(point)} and @code{(mark t)}.  And each function
510 should leave point and mark around the citation text as modified.
512 @item message-signature
513 @vindex message-signature
514 String to be inserted at the end of the message buffer.  If @code{t}
515 (which is the default), the @code{message-signature-file} file will be
516 inserted instead.  If a function, the result from the function will be
517 used instead.  If a form, the result from the form will be used instead.
518 If this variable is @code{nil}, no signature will be inserted at all.
520 @item message-signature-file
521 @vindex message-signature-file
522 File containing the signature to be inserted at the end of the buffer.
523 The default is @samp{~/.signature}.
525 @end table
527 Note that RFC1036bis says that a signature should be preceded by the three
528 characters @samp{-- } on a line by themselves.  This is to make it
529 easier for the recipient to automatically recognize and process the
530 signature.  So don't remove those characters, even though you might feel
531 that they ruin your beautiful design, like, totally.
533 Also note that no signature should be more than four lines long.
534 Including ASCII graphics is an efficient way to get everybody to believe
535 that you are silly and have nothing important to say.
539 @node Various Commands
540 @section Various Commands
542 @table @kbd
544 @item C-c C-r
545 @kindex C-c C-r 
546 @findex message-caesar-buffer-body
547 Caesar rotate (aka. rot13) the current message
548 (@code{message-caesar-buffer-body}).  If narrowing is in effect, just
549 rotate the visible portion of the buffer.  A numerical prefix says how
550 many places to rotate the text.  The default is 13.
552 @item C-c C-e
553 @kindex C-c C-e
554 @findex message-elide-region
555 Elide the text between point and mark (@code{message-elide-region}).
556 The text is killed and an ellipsis (@samp{[...]}) will be inserted in
557 its place.
559 @item C-c C-z
560 @kindex C-c C-x
561 @findex message-kill-to-signature
562 Kill all the text up to the signature, or if that's missing, up to the
563 end of the message (@code{message-kill-to-signature}).
565 @item C-c C-v
566 @kindex C-c C-v
567 @findex message-delete-not-region
568 Delete all text in the body of the message that is outside the region
569 (@code{message-delete-not-region}).
571 @item M-RET
572 @kindex M-RET
573 @kindex message-newline-and-reformat
574 Insert four newlines, and then reformat if inside quoted text.
576 Here's an example:
578 @example
579 > This is some quoted text.  And here's more quoted text.
580 @end example
582 If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
584 @example
585 > This is some quoted text.
589 > And here's more quoted text.
590 @end example
592 @samp{*} says where point will be placed.  
594 @item C-c C-t
595 @kindex C-c C-t 
596 @findex message-insert-to
597 Insert a @code{To} header that contains the @code{Reply-To} or
598 @code{From} header of the message you're following up
599 (@code{message-insert-to}). 
601 @item C-c C-n
602 @kindex C-c C-n 
603 @findex message-insert-newsgroups
604 Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
605 or @code{Newsgroups} header of the article you're replying to
606 (@code{message-insert-newsgroups}).
608 @item C-c M-r
609 @kindex C-c M-r
610 @findex message-rename-buffer
611 Rename the buffer (@code{message-rename-buffer}).  If given a prefix,
612 prompt for a new buffer name.
614 @end table
617 @node Sending
618 @section Sending
620 @table @kbd
621 @item C-c C-c
622 @kindex C-c C-c 
623 @findex message-send-and-exit
624 Send the message and bury the current buffer
625 (@code{message-send-and-exit}). 
627 @item C-c C-s
628 @kindex C-c C-s 
629 @findex message-send
630 Send the message (@code{message-send}). 
632 @item C-c C-d
633 @kindex C-c C-d
634 @findex message-dont-send
635 Bury the message buffer and exit (@code{message-dont-send}).
637 @item C-c C-k
638 @kindex C-c C-k
639 @findex message-kill-buffer
640 Kill the message buffer and exit (@code{message-kill-buffer}).
642 @end table
646 @node Mail Aliases
647 @section Mail Aliases
648 @cindex mail aliases
649 @cindex aliases
651 @vindex message-mail-alias-type
652 The @code{message-mail-alias-type} variable controls what type of mail
653 alias expansion to use.  Currently only one form is supported---Message
654 uses @code{mailabbrev} to handle mail aliases.  If this variable is
655 @code{nil}, no mail alias expansion will be performed.
657 @code{mailabbrev} works by parsing the @file{/etc/mailrc} and
658 @file{~/.mailrc} files.  These files look like:
660 @example
661 alias lmi "Lars Magne Ingebrigtsen <larsi@@ifi.uio.no>"
662 alias ding "ding@@ifi.uio.no (ding mailing list)"
663 @end example
665 After adding lines like this to your @file{~/.mailrc} file, you should
666 be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so
667 on) headers and press @kbd{SPC} to expand the alias.
669 No expansion will be performed upon sending of the message---all
670 expansions have to be done explicitly.
674 @node Variables
675 @chapter Variables
677 @menu
678 * Message Headers::             General message header stuff.
679 * Mail Headers::                Customizing mail headers.
680 * Mail Variables::              Other mail variables.
681 * News Headers::                Customizing news headers.
682 * News Variables::              Other news variables.
683 * Various Message Variables::   Other message variables.
684 * Sending Variables::           Variables for sending.
685 * Message Buffers::             How Message names its buffers.
686 * Message Actions::             Actions to be performed when exiting.
687 @end menu
690 @node Message Headers
691 @section Message Headers
693 Message is quite aggressive on the message generation front.  It has to
694 be -- it's a combined news and mail agent.  To be able to send combined
695 messages, it has to generate all headers itself (instead of letting the
696 mail/news system do it) to ensure that mail and news copies of messages
697 look sufficiently similar.
699 @table @code
701 @item message-generate-headers-first
702 @vindex message-generate-headers-first
703 If non-@code{nil}, generate all headers before starting to compose the
704 message.  
706 @item message-from-style
707 @vindex message-from-style
708 Specifies how @code{From} headers should look.  There are four valid
709 values:
711 @table @code
712 @item nil
713 Just the address -- @samp{king@@grassland.com}.
715 @item parens
716 @samp{king@@grassland.com (Elvis Parsley)}.
718 @item angles
719 @samp{Elvis Parsley <king@@grassland.com>}.
721 @item default
722 Look like @code{angles} if that doesn't require quoting, and
723 @code{parens} if it does.  If even @code{parens} requires quoting, use
724 @code{angles} anyway.
726 @end table
728 @item message-deletable-headers
729 @vindex message-deletable-headers
730 Headers in this list that were previously generated by Message will be
731 deleted before posting.  Let's say you post an article.  Then you decide
732 to post it again to some other group, you naughty boy, so you jump back
733 to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
734 ship it off again.  By default, this variable makes sure that the old
735 generated @code{Message-ID} is deleted, and a new one generated.  If
736 this isn't done, the entire empire would probably crumble, anarchy would
737 prevail, and cats would start walking on two legs and rule the world.
738 Allegedly.  
740 @item message-default-headers
741 @vindex message-default-headers
742 This string is inserted at the end of the headers in all message
743 buffers.
745 @item message-subject-re-regexp
746 @vindex message-subject-re-regexp
747 Responses to messages have subjects that start with @samp{Re: }.  This
748 is @emph{not} an abbreviation of the English word ``response'', but in
749 Latin, and means ``in response to''.  Some illiterate nincompoops have
750 failed to grasp this fact, and have ``internationalized'' their software
751 to use abonimations like @samp{Aw: } (``antwort'') or @samp{Sv: }
752 (``svar'') instead, which is meaningless and evil.  However, you may
753 have to deal with users that use these evil tools, in which case you may
754 set this variable to a regexp that matches these prefixes.  Myself, I
755 just throw away non-compliant mail.
757 @end table
760 @node Mail Headers
761 @section Mail Headers
763 @table @code
764 @item message-required-mail-headers
765 @vindex message-required-mail-headers
766 @xref{News Headers}, for the syntax of this variable.  It is
767 @code{(From Date Subject (optional . In-Reply-To) Message-ID Lines
768 (optional . X-Mailer))} by default.
770 @item message-ignored-mail-headers
771 @vindex message-ignored-mail-headers
772 Regexp of headers to be removed before mailing.  The default is
773 @samp{^[GF]cc:\\|^Resent-Fcc:}.
775 @item message-default-mail-headers
776 @vindex message-default-mail-headers
777 This string is inserted at the end of the headers in all message
778 buffers that are initialized as mail.
780 @end table
783 @node Mail Variables
784 @section Mail Variables 
786 @table @code
787 @item message-send-mail-function
788 @vindex message-send-mail-function
789 Function used to send the current buffer as mail.  The default is
790 @code{message-send-mail-with-sendmail}.   If you prefer using MH
791 instead, set this variable to @code{message-send-mail-with-mh}.
793 @item message-mh-deletable-headers
794 @vindex message-mh-deletable-headers
795 Most versions of MH doesn't like being fed messages that contain the
796 headers in this variable.  If this variable is non-@code{nil} (which is
797 the default), these headers will be removed before mailing when sending
798 messages via MH.  Set it to @code{nil} if your MH can handle these
799 headers.
801 @end table
804 @node News Headers
805 @section News Headers
807 @vindex message-required-news-headers
808 @code{message-required-news-headers} a list of header symbols.  These
809 headers will either be automatically generated, or, if that's
810 impossible, they will be prompted for.  The following symbols are valid:
812 @table @code
814 @item From
815 @cindex From
816 @findex user-full-name
817 @findex user-mail-address
818 This required header will be filled out with the result of the
819 @code{message-make-from} function, which depends on the
820 @code{message-from-style}, @code{user-full-name},
821 @code{user-mail-address} variables.
823 @item Subject
824 @cindex Subject
825 This required header will be prompted for if not present already. 
827 @item Newsgroups
828 @cindex Newsgroups
829 This required header says which newsgroups the article is to be posted
830 to.  If it isn't present already, it will be prompted for.
832 @item Organization
833 @cindex organization
834 This optional header will be filled out depending on the
835 @code{message-user-organization} variable.
836 @code{message-user-organization-file} will be used if this variable is
837 @code{t}.  This variable can also be a string (in which case this string
838 will be used), or it can be a function (which will be called with no
839 parameters and should return a string to be used).
841 @item Lines
842 @cindex Lines
843 This optional header will be computed by Message.
845 @item Message-ID
846 @cindex Message-ID
847 @vindex mail-host-address
848 @findex system-name
849 @cindex Sun
850 This required header will be generated by Message.  A unique ID will be
851 created based on the date, time, user name and system name.  Message will
852 use @code{mail-host-address} as the fully qualified domain name (FQDN)
853 of the machine if that variable is defined.  If not, it will use
854 @code{system-name}, which doesn't report a FQDN on some machines --
855 notably Suns.
857 @item X-Newsreader
858 @cindex X-Newsreader
859 This optional header will be filled out according to the
860 @code{message-newsreader} local variable.
862 @item X-Mailer
863 This optional header will be filled out according to the
864 @code{message-mailer} local variable, unless there already is an
865 @code{X-Newsreader} header present.
867 @item In-Reply-To
868 This optional header is filled out using the @code{Date} and @code{From}
869 header of the article being replied to.
871 @item Expires
872 @cindex Expires
873 This extremely optional header will be inserted according to the
874 @code{message-expires} variable.  It is highly deprecated and shouldn't
875 be used unless you know what you're doing.
877 @item Distribution
878 @cindex Distribution
879 This optional header is filled out according to the
880 @code{message-distribution-function} variable.  It is a deprecated and
881 much misunderstood header.
883 @item Path
884 @cindex path
885 This extremely optional header should probably never be used.
886 However, some @emph{very} old servers require that this header is
887 present.  @code{message-user-path} further controls how this
888 @code{Path} header is to look.  If it is @code{nil}, use the server name
889 as the leaf node.  If it is a string, use the string.  If it is neither
890 a string nor @code{nil}, use the user name only.  However, it is highly
891 unlikely that you should need to fiddle with this variable at all.
892 @end table
894 @findex yow
895 @cindex Mime-Version
896 In addition, you can enter conses into this list.  The car of this cons
897 should be a symbol.  This symbol's name is the name of the header, and
898 the cdr can either be a string to be entered verbatim as the value of
899 this header, or it can be a function to be called.  This function should
900 return a string to be inserted.  For instance, if you want to insert
901 @code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
902 into the list.  If you want to insert a funny quote, you could enter
903 something like @code{(X-Yow . yow)} into the list.  The function
904 @code{yow} will then be called without any arguments.
906 If the list contains a cons where the car of the cons is
907 @code{optional}, the cdr of this cons will only be inserted if it is
908 non-@code{nil}.
910 Other variables for customizing outgoing news articles:
912 @table @code
914 @item message-syntax-checks
915 @vindex message-syntax-checks
916 Controls what syntax checks should not be performed on outgoing posts.
917 To disable checking of long signatures, for instance, add
919 @lisp
920 (signature . disabled)
921 @end lisp
923 to this list.
925 Valid checks are:
927 @table @code
928 @item subject-cmsg 
929 Check the subject for commands.
930 @item sender
931 @cindex Sender
932 Insert a new @code{Sender} header if the @code{From} header looks odd. 
933 @item multiple-headers 
934 Check for the existence of multiple equal headers.
935 @item sendsys 
936 @cindex sendsys
937 Check for the existence of version and sendsys commands.
938 @item message-id
939 Check whether the @code{Message-ID} looks ok.
940 @item from
941 Check whether the @code{From} header seems nice.
942 @item long-lines 
943 @cindex long lines
944 Check for too long lines.
945 @item control-chars
946 Check for invalid characters.
947 @item size
948 Check for excessive size.
949 @item new-text
950 Check whether there is any new text in the messages.
951 @item signature
952 Check the length of the signature.
953 @item approved
954 @cindex approved
955 Check whether the article has an @code{Approved} header, which is
956 something only moderators should include.
957 @item empty
958 Check whether the article is empty.
959 @item empty-headers
960 Check whether any of the headers are empty.
961 @item existing-newsgroups
962 Check whether the newsgroups mentioned in the @code{Newsgroups} and 
963 @code{Followup-To} headers exist.
964 @item valid-newsgroups
965 Check whether the @code{Newsgroups} and @code{Followup-to} headers
966 are valid syntactically.
967 @item repeated-newsgroups
968 Check whether the @code{Newsgroups} and @code{Followup-to} headers
969 contains repeated group names.
970 @item shorten-followup-to
971 Check whether to add a @code{Followup-to} header to shorten the number
972 of groups to post to.
973 @end table
975 All these conditions are checked by default.
977 @item message-ignored-news-headers
978 @vindex message-ignored-news-headers
979 Regexp of headers to be removed before posting.  The default is@*
980 @samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:}.
982 @item message-default-news-headers
983 @vindex message-default-news-headers
984 This string is inserted at the end of the headers in all message
985 buffers that are initialized as news.
987 @end table
990 @node News Variables
991 @section News Variables
993 @table @code
994 @item message-send-news-function
995 @vindex message-send-news-function
996 Function used to send the current buffer as news.  The default is
997 @code{message-send-news}. 
999 @item message-post-method
1000 @vindex message-post-method
1001 Gnusish @dfn{select method} (see the Gnus manual for details) used for
1002 posting a prepared news message.
1004 @end table
1007 @node Various Message Variables
1008 @section Various Message Variables
1010 @table @code
1011 @item message-signature-separator
1012 @vindex message-signature-separator
1013 Regexp matching the signature separator.  It is @samp{^-- *$} by
1014 default. 
1016 @item mail-header-separator
1017 @vindex mail-header-separator
1018 String used to separate the headers from the body.  It is @samp{--text
1019 follows this line--} by default.
1021 @item message-directory
1022 @vindex message-directory
1023 Directory used by many mailey things.  The default is @file{~/Mail/}. 
1025 @item message-signature-setup-hook
1026 @vindex message-signature-setup-hook
1027 Hook run when initializing the message buffer.  It is run after the
1028 headers have been inserted but before the signature has been inserted. 
1030 @item message-setup-hook
1031 @vindex message-setup-hook
1032 Hook run as the last thing when the message buffer has been initialized,
1033 but before yanked text is inserted.
1035 @item message-header-setup-hook
1036 @vindex message-header-setup-hook
1037 Hook called narrowed to the headers after initializing the headers. 
1039 For instance, if you're running Gnus and wish to insert a
1040 @samp{Mail-Copies-To} header in all your news articles and all messages
1041 you send to mailing lists, you could do something like the following:
1043 @lisp
1044 (defun my-message-header-setup-hook ()
1045   (let ((group (or gnus-newsgroup-name "")))
1046     (when (or (message-fetch-field "newsgroups")
1047               (gnus-group-find-parameter group 'to-address)
1048               (gnus-group-find-parameter group 'to-list))
1049       (insert "Mail-Copies-To: never\n"))))
1051 (add-hook 'message-header-setup-hook
1052           'my-message-header-setup-hook)
1053 @end lisp
1055 @item message-send-hook
1056 @vindex message-send-hook
1057 Hook run before sending messages.
1059 If you want to add certain headers before sending, you can use the
1060 @code{message-add-header} function in this hook.  For instance:
1061 @findex message-add-header
1063 @lisp
1064 (add-hook 'message-send-hook 'my-message-add-content)
1065 (defun my-message-add-content ()
1066   (message-add-header
1067    "Mime-Version: 1.0"
1068    "Content-Type: text/plain"
1069    "Content-Transfer-Encoding: 7bit"))
1070 @end lisp
1072 This function won't add the header if the header is already present.
1074 @item message-send-mail-hook
1075 @vindex message-send-mail-hook
1076 Hook run before sending mail messages.
1078 @item message-send-news-hook
1079 @vindex message-send-news-hook
1080 Hook run before sending news messages.
1082 @item message-sent-hook
1083 @vindex message-sent-hook
1084 Hook run after sending messages.
1086 @item message-mode-syntax-table
1087 @vindex message-mode-syntax-table
1088 Syntax table used in message mode buffers.
1090 @item message-send-method-alist
1091 @vindex message-send-method-alist
1093 Alist of ways to send outgoing messages.  Each element has the form
1095 @lisp
1096 (TYPE PREDICATE FUNCTION)
1097 @end lisp
1099 @table @var
1100 @item type
1101 A symbol that names the method.
1103 @item predicate
1104 A function called without any parameters to determine whether the
1105 message is a message of type @var{type}.
1107 @item function
1108 A function to be called if @var{predicate} returns non-@code{nil}.
1109 @var{function} is called with one parameter -- the prefix.
1110 @end table
1112 @lisp
1113 ((news message-news-p message-send-via-news)
1114  (mail message-mail-p message-send-via-mail))
1115 @end lisp
1119 @end table
1123 @node Sending Variables
1124 @section Sending Variables
1126 @table @code
1128 @item message-fcc-handler-function 
1129 @vindex message-fcc-handler-function 
1130 A function called to save outgoing articles.  This function will be
1131 called with the name of the file to store the article in. The default
1132 function is @code{message-output} which saves in Unix mailbox format.
1134 @item message-courtesy-message
1135 @vindex message-courtesy-message
1136 When sending combined messages, this string is inserted at the start of
1137 the mailed copy.  If the string contains the format spec @samp{%s}, the
1138 newsgroups the article has been posted to will be inserted there.  If
1139 this variable is @code{nil}, no such courtesy message will be added.
1140 The default value is @samp{"The following message is a courtesy copy of
1141 an article\nthat has been posted to %s as well.\n\n"}. 
1143 @end table
1146 @node Message Buffers
1147 @section Message Buffers
1149 Message will generate new buffers with unique buffer names when you
1150 request a message buffer.  When you send the message, the buffer isn't
1151 normally killed off.  Its name is changed and a certain number of old
1152 message buffers are kept alive.
1154 @table @code
1155 @item message-generate-new-buffers
1156 @vindex message-generate-new-buffers
1157 If non-@code{nil}, generate new buffers.  The default is @code{t}.  If
1158 this is a function, call that function with three parameters: The type,
1159 the to address and the group name.  (Any of these may be @code{nil}.)
1160 The function should return the new buffer name.
1162 @item message-max-buffers
1163 @vindex message-max-buffers
1164 This variable says how many old message buffers to keep.  If there are
1165 more message buffers than this, the oldest buffer will be killed.  The
1166 default is 10.  If this variable is @code{nil}, no old message buffers
1167 will ever be killed.
1169 @item message-send-rename-function
1170 @vindex message-send-rename-function
1171 After sending a message, the buffer is renamed from, for instance,
1172 @samp{*reply to Lars*} to @samp{*sent reply to Lars*}.  If you don't
1173 like this, set this variable to a function that renames the buffer in a
1174 manner you like.  If you don't want to rename the buffer at all, you can
1175 say:
1177 @lisp
1178 (setq message-send-rename-function 'ignore)
1179 @end lisp
1181 @item message-kill-buffer-on-exit
1182 @findex message-kill-buffer-on-exit
1183 If non-@code{nil}, kill the buffer immediately on exit.
1185 @end table
1188 @node Message Actions
1189 @section Message Actions
1191 When Message is being used from a news/mail reader, the reader is likely
1192 to want to perform some task after the message has been sent.  Perhaps
1193 return to the previous window configuration or mark an article as
1194 replied.  
1196 @vindex message-kill-actions
1197 @vindex message-postpone-actions
1198 @vindex message-exit-actions
1199 @vindex message-send-actions
1200 The user may exit from the message buffer in various ways.  The most
1201 common is @kbd{C-c C-c}, which sends the message and exits.  Other
1202 possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c
1203 C-d} which postpones the message editing and buries the message buffer,
1204 and @kbd{C-c C-k} which kills the message buffer.  Each of these actions
1205 have lists associated with them that contains actions to be executed:
1206 @code{message-send-actions}, @code{message-exit-actions},
1207 @code{message-postpone-actions}, and @code{message-kill-actions}.  
1209 Message provides a function to interface with these lists:
1210 @code{message-add-action}.  The first parameter is the action to be
1211 added, and the rest of the arguments are which lists to add this action
1212 to.  Here's an example from Gnus:
1214 @lisp
1215   (message-add-action
1216    `(set-window-configuration ,(current-window-configuration))
1217    'exit 'postpone 'kill)
1218 @end lisp
1220 This restores the Gnus window configuration when the message buffer is
1221 killed, postponed or exited.
1223 An @dfn{action} can be either: a normal function, or a list where the
1224 @code{car} is a function and the @code{cdr} is the list of arguments, or
1225 a form to be @code{eval}ed.
1228 @node Compatibility
1229 @chapter Compatibility
1230 @cindex compatibility
1232 Message uses virtually only its own variables---older @code{mail-}
1233 variables aren't consulted.  To force Message to take those variables
1234 into account, you can put the following in your @code{.emacs} file:
1236 @lisp
1237 (require 'messcompat)
1238 @end lisp
1240 This will initialize many Message variables from the values in the
1241 corresponding mail variables.
1244 @node Appendices
1245 @chapter Appendices
1247 @menu
1248 * Responses::          Standard rules for determining where responses go.
1249 @end menu
1252 @node Responses
1253 @section Responses
1255 To determine where a message is to go, the following algorithm is used
1256 by default.
1258 @table @dfn
1259 @item reply
1260 A @dfn{reply} is when you want to respond @emph{just} to the person who
1261 sent the message via mail.  There will only be one recipient.  To
1262 determine who the recipient will be, the following headers are
1263 consulted, in turn:
1265 @table @code
1266 @item Reply-To
1268 @item From
1269 @end table
1272 @item wide reply
1273 A @dfn{wide reply} is a mail response that includes @emph{all} entities
1274 mentioned in the message you are responded to.  All mailboxes from the
1275 following headers will be concatenated to form the outgoing
1276 @code{To}/@code{Cc} headers:
1278 @table @code
1279 @item From
1280 (unless there's a @code{Reply-To}, in which case that is used instead).
1282 @item Cc
1284 @item To
1285 @end table
1287 If a @code{Mail-Copies-To} header is present, it will also be included
1288 in the list of mailboxes.  If this header is @samp{never}, that means
1289 that the @code{From} (or @code{Reply-To}) mailbox will be suppressed.
1292 @item followup
1293 A @dfn{followup} is a response sent via news.  The following headers
1294 (listed in order of precedence) determine where the response is to be
1295 sent:
1297 @table @code
1299 @item Followup-To
1301 @item Newsgroups
1303 @end table
1305 If a @code{Mail-Copies-To} header is present, it will be used as the
1306 basis of the new @code{Cc} header, except if this header is
1307 @samp{never}.
1309 @end table
1313 @node Index
1314 @chapter Index
1315 @printindex cp
1317 @node Key Index
1318 @chapter Key Index
1319 @printindex ky
1321 @summarycontents
1322 @contents
1323 @bye
1325 @c End: