66c3ff3ece8928d73ade246ccf2e1c71172787cb
[gnus] / texi / message.texi
1 \input texinfo                  @c -*-texinfo-*-
2
3 @setfilename message
4 @settitle Pterodactyl Message 0.10 Manual
5 @synindex fn cp
6 @synindex vr cp
7 @synindex pg cp
8 @c @direntry
9 @c * Message: (message).   Mail and news composition mode that goes with Gnus.
10 @c @end direntry
11 @iftex
12 @finalout
13 @end iftex
14 @setchapternewpage odd
15
16 @ifinfo
17
18 This file documents Message, the Emacs message composition mode.
19
20 Copyright (C) 1996 Free Software Foundation, Inc.
21
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.
25
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).
31
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.
37
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
41
42 @tex
43
44 @titlepage
45 @title Pterodactyl Message 0.10 Manual
46
47 @author by Lars Magne Ingebrigtsen
48 @page
49
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1996 Free Software Foundation, Inc. 
52
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.
56
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.
61
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions.
64
65 @end titlepage
66 @page
67
68 @end tex
69
70 @node Top
71 @top Message
72
73 All message composition from Gnus (both mail and news) takes place in
74 Message mode buffers.
75
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
85
86 This manual corresponds to Pterodactyl Message 0.10.  Message is
87 distributed with the Gnus distribution bearing the same version number
88 as this manual has.
89
90
91 @node Interface
92 @chapter Interface
93
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.
100
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
113
114
115 @node New Mail Message
116 @section New Mail Message
117
118 @findex message-mail
119 The @code{message-mail} command pops up a new message buffer.  
120
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.
124
125
126 @node New News Message
127 @section New News Message
128
129 @findex message-news
130 The @code{message-news} command pops up a new message buffer.  
131
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.
135
136
137 @node Reply
138 @section Reply
139
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.
143
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.
148
149 If you want the replies to go to the @code{Sender} instead of the
150 @code{From}, you could do something like this:
151
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
160
161 This function will be called narrowed to the head of the article that is
162 being replied to.
163
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.
168
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. 
174
175
176 @node Wide Reply
177 @section Wide Reply
178
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.
184
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}). 
190
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.
194
195
196 @node Followup
197 @section Followup
198
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.
202
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}).
208
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.
215
216
217 @node Canceling News
218 @section Canceling News
219
220 @findex message-cancel-news
221 The @code{message-cancel-news} command cancels the article in the
222 current buffer.
223
224
225 @node Superseding
226 @section Superseding
227
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.
231
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:}.
237
238
239
240 @node Forwarding
241 @section Forwarding
242
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.
247
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}. 
253
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}. 
259
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.
265
266 @item message-included-forward-headers
267 @vindex message-included-forward-headers
268 Regexp matching header lines to be included in forwarded messages.  
269
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.
275
276 The provided functions are:
277
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.
283
284 @item message-forward-subject-fwd
285 Subject of article with @samp{Fwd:} prepended to it.
286 @end table
287
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}.
294
295 @end table
296
297
298 @node Resending
299 @section Resending
300
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.
304
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}. 
309
310
311 @node Bouncing
312 @section Bouncing
313
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. 
320
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\\):}.
325
326
327 @node Commands
328 @chapter Commands
329
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
338
339
340 @node Header Commands
341 @section Header Commands
342
343 All these commands move to the header in question.  If it doesn't exist,
344 it will be inserted.
345
346 @table @kbd
347
348 @item C-c ?
349 @kindex C-c ?
350 @findex message-goto-to
351 Describe the message mode.
352
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}).
357
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}).
362
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}).
367
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}).
372
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}).
377
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}).
382
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}).
387
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}).
392
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}).
397
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}).
402
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}).
407
408 @end table
409
410
411 @node Movement
412 @section Movement
413
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}). 
420
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}).
425
426 @end table
427
428
429 @node Insertion
430 @section Insertion
431
432 @table @kbd
433
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}). 
439
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.
448
449
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}).  
455
456 @end table
457
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.
464
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:
470
471 @example
472 Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
473 @end example
474
475 Point will be at the beginning of the body of the message when this
476 function is called.
477
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.
487
488 @item message-indentation-spaces
489 @vindex message-indentation-spaces
490 Number of spaces to indent yanked messages.
491
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.
504
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.
511
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.
519
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}.
524
525 @end table
526
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.
532
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.
536
537
538
539 @node Various Commands
540 @section Various Commands
541
542 @table @kbd
543
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.
551
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.
558
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}).
564
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}).
570
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.
575
576 Here's an example:
577
578 @example
579 > This is some quoted text.  And here's more quoted text.
580 @end example
581
582 If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
583
584 @example
585 > This is some quoted text.
586
587 *
588
589 > And here's more quoted text.
590 @end example
591
592 @samp{*} says where point will be placed.  
593
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}). 
600
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}).
607
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.
613
614 @end table
615
616
617 @node Sending
618 @section Sending
619
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}). 
626
627 @item C-c C-s
628 @kindex C-c C-s 
629 @findex message-send
630 Send the message (@code{message-send}). 
631
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}).
636
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}).
641
642 @end table
643
644
645
646 @node Mail Aliases
647 @section Mail Aliases
648 @cindex mail aliases
649 @cindex aliases
650
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.
656
657 @code{mailabbrev} works by parsing the @file{/etc/mailrc} and
658 @file{~/.mailrc} files.  These files look like:
659
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
664
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.
668
669 No expansion will be performed upon sending of the message---all
670 expansions have to be done explicitly.
671
672
673
674 @node Variables
675 @chapter Variables
676
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
688
689
690 @node Message Headers
691 @section Message Headers
692
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.
698
699 @table @code
700
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.  
705
706 @item message-from-style
707 @vindex message-from-style
708 Specifies how @code{From} headers should look.  There are four valid
709 values:
710
711 @table @code
712 @item nil
713 Just the address -- @samp{king@@grassland.com}.
714
715 @item parens
716 @samp{king@@grassland.com (Elvis Parsley)}.
717
718 @item angles
719 @samp{Elvis Parsley <king@@grassland.com>}.
720
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.
725
726 @end table
727
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.  
739
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.
744
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.
756
757 @end table
758
759
760 @node Mail Headers
761 @section Mail Headers
762
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.
769
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:}.
774
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.
779
780 @end table
781
782
783 @node Mail Variables
784 @section Mail Variables 
785
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}.
792
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.
800
801 @end table
802
803
804 @node News Headers
805 @section News Headers
806
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:
811
812 @table @code
813
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.
822
823 @item Subject
824 @cindex Subject
825 This required header will be prompted for if not present already. 
826
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.
831
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).
840
841 @item Lines
842 @cindex Lines
843 This optional header will be computed by Message.
844
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.
856
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.
861
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.
866
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.
870
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.
876
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.
882
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
893
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.
905
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}.
909
910 Other variables for customizing outgoing news articles:
911
912 @table @code
913
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
918
919 @lisp
920 (signature . disabled)
921 @end lisp
922
923 to this list.
924
925 Valid checks are:
926
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
974
975 All these conditions are checked by default.
976
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:}.
981
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.
986
987 @end table
988
989
990 @node News Variables
991 @section News Variables
992
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}. 
998
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.
1003
1004 @end table
1005
1006
1007 @node Various Message Variables
1008 @section Various Message Variables
1009
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. 
1015
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.
1020
1021 @item message-directory
1022 @vindex message-directory
1023 Directory used by many mailey things.  The default is @file{~/Mail/}. 
1024
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. 
1029
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.
1034
1035 @item message-header-setup-hook
1036 @vindex message-header-setup-hook
1037 Hook called narrowed to the headers after initializing the headers. 
1038
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:
1042
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"))))
1050
1051 (add-hook 'message-header-setup-hook
1052           'my-message-header-setup-hook)
1053 @end lisp
1054
1055 @item message-send-hook
1056 @vindex message-send-hook
1057 Hook run before sending messages.
1058
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
1062
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
1071
1072 This function won't add the header if the header is already present.
1073
1074 @item message-send-mail-hook
1075 @vindex message-send-mail-hook
1076 Hook run before sending mail messages.
1077
1078 @item message-send-news-hook
1079 @vindex message-send-news-hook
1080 Hook run before sending news messages.
1081
1082 @item message-sent-hook
1083 @vindex message-sent-hook
1084 Hook run after sending messages.
1085
1086 @item message-mode-syntax-table
1087 @vindex message-mode-syntax-table
1088 Syntax table used in message mode buffers.
1089
1090 @item message-send-method-alist
1091 @vindex message-send-method-alist
1092
1093 Alist of ways to send outgoing messages.  Each element has the form
1094
1095 @lisp
1096 (TYPE PREDICATE FUNCTION)
1097 @end lisp
1098
1099 @table @var
1100 @item type
1101 A symbol that names the method.
1102
1103 @item predicate
1104 A function called without any parameters to determine whether the
1105 message is a message of type @var{type}.
1106
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
1111
1112 @lisp
1113 ((news message-news-p message-send-via-news)
1114  (mail message-mail-p message-send-via-mail))
1115 @end lisp
1116
1117
1118
1119 @end table
1120
1121
1122
1123 @node Sending Variables
1124 @section Sending Variables
1125
1126 @table @code
1127
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.
1133
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"}. 
1142
1143 @end table
1144
1145
1146 @node Message Buffers
1147 @section Message Buffers
1148
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.
1153
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.
1161
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.
1168
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:
1176
1177 @lisp
1178 (setq message-send-rename-function 'ignore)
1179 @end lisp
1180
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.
1184
1185 @end table
1186
1187
1188 @node Message Actions
1189 @section Message Actions
1190
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.  
1195
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}.  
1208
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:
1213
1214 @lisp
1215   (message-add-action
1216    `(set-window-configuration ,(current-window-configuration))
1217    'exit 'postpone 'kill)
1218 @end lisp
1219
1220 This restores the Gnus window configuration when the message buffer is
1221 killed, postponed or exited.
1222
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.
1226
1227
1228 @node Compatibility
1229 @chapter Compatibility
1230 @cindex compatibility
1231
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:
1235
1236 @lisp
1237 (require 'messcompat)
1238 @end lisp
1239
1240 This will initialize many Message variables from the values in the
1241 corresponding mail variables.
1242
1243
1244 @node Appendices
1245 @chapter Appendices
1246
1247 @menu
1248 * Responses::          Standard rules for determining where responses go.
1249 @end menu
1250
1251
1252 @node Responses
1253 @section Responses
1254
1255 To determine where a message is to go, the following algorithm is used
1256 by default.
1257
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:
1264
1265 @table @code
1266 @item Reply-To
1267
1268 @item From
1269 @end table
1270
1271
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:
1277
1278 @table @code
1279 @item From
1280 (unless there's a @code{Reply-To}, in which case that is used instead).
1281
1282 @item Cc
1283
1284 @item To
1285 @end table
1286
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.
1290
1291
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:
1296
1297 @table @code
1298
1299 @item Followup-To
1300
1301 @item Newsgroups
1302
1303 @end table
1304
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}.
1308
1309 @end table
1310
1311
1312
1313 @node Index
1314 @chapter Index
1315 @printindex cp
1316
1317 @node Key Index
1318 @chapter Key Index
1319 @printindex ky
1320
1321 @summarycontents
1322 @contents
1323 @bye
1324
1325 @c End: