b86c01e54f9343d143def806bde14eecb02ee5cf
[gnus] / texi / message.texi
1 \input texinfo                  @c -*-texinfo-*-
2
3 @include gnus-overrides.texi
4
5 @setfilename message.info
6 @settitle Message Manual
7 @include docstyle.texi
8 @synindex fn cp
9 @synindex vr cp
10 @synindex pg cp
11 @copying
12 This file documents Message, the Emacs message composition mode.
13
14 Copyright @copyright{} 1996--2016 Free Software Foundation, Inc.
15
16 @quotation
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
21 and with the Back-Cover Texts as in (a) below.  A copy of the license
22 is included in the section entitled ``GNU Free Documentation License''.
23
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.''
26 @end quotation
27 @end copying
28
29 @dircategory Emacs network features
30 @direntry
31 * Message: (message).           Mail and news composition mode that
32                                   goes with Gnus.
33 @end direntry
34 @iftex
35 @finalout
36 @end iftex
37
38 @titlepage
39 @ifset WEBHACKDEVEL
40 @title Message Manual (DEVELOPMENT VERSION)
41 @end ifset
42 @ifclear WEBHACKDEVEL
43 @title Message Manual
44 @end ifclear
45
46 @author by Lars Magne Ingebrigtsen
47 @page
48
49 @vskip 0pt plus 1filll
50 @insertcopying
51 @end titlepage
52
53 @summarycontents
54 @contents
55
56 @node Top
57 @top Message
58
59 @ifnottex
60 @insertcopying
61 @end ifnottex
62
63 All message composition from Gnus (both mail and news) takes place in
64 Message mode buffers.
65
66 @menu
67 * Interface::         Setting up message buffers.
68 * Commands::          Commands you can execute in message mode buffers.
69 * Variables::         Customizing the message buffers.
70 * Compatibility::     Making Message backwards compatible.
71 * Appendices::        More technical things.
72 * GNU Free Documentation License:: The license for this documentation.
73 * Index::             Variable, function and concept index.
74 * Key Index::         List of Message mode keys.
75 @end menu
76
77 @c Adjust ../Makefile.in if you change the following lines:
78 Message is distributed with Gnus.  The Gnus distribution
79 @c
80 corresponding to this manual is Ma Gnus v0.14
81
82
83 @node Interface
84 @chapter Interface
85
86 When a program (or a person) wants to respond to a message---reply,
87 follow up, forward, cancel---the program (or person) should just put
88 point in the buffer where the message is and call the required command.
89 @code{Message} will then pop up a new @code{message} mode buffer with
90 appropriate headers filled out, and the user can edit the message before
91 sending it.
92
93 @menu
94 * New Mail Message::     Editing a brand new mail message.
95 * New News Message::     Editing a brand new news message.
96 * Reply::                Replying via mail.
97 * Wide Reply::           Responding to all people via mail.
98 * Followup::             Following up via news.
99 * Canceling News::       Canceling a news article.
100 * Superseding::          Superseding a message.
101 * Forwarding::           Forwarding a message via news or mail.
102 * Resending::            Resending a mail message.
103 * Bouncing::             Bouncing a mail message.
104 * Mailing Lists::        Send mail to mailing lists.
105 @end menu
106
107 You can customize the Message Mode tool bar, see @kbd{M-x
108 customize-apropos RET message-tool-bar}.  This feature is only available
109 in Emacs.
110
111 @node New Mail Message
112 @section New Mail Message
113
114 @findex message-mail
115 The @code{message-mail} command pops up a new message buffer.
116
117 Two optional parameters are accepted: The first will be used as the
118 @code{To} header and the second as the @code{Subject} header.  If these
119 are @code{nil}, those two headers will be empty.
120
121
122 @node New News Message
123 @section New News Message
124
125 @findex message-news
126 The @code{message-news} command pops up a new message buffer.
127
128 This function accepts two optional parameters.  The first will be used
129 as the @code{Newsgroups} header and the second as the @code{Subject}
130 header.  If these are @code{nil}, those two headers will be empty.
131
132
133 @node Reply
134 @section Reply
135
136 @findex message-reply
137 The @code{message-reply} function pops up a message buffer that's a
138 reply to the message in the current buffer.
139
140 @vindex message-reply-to-function
141 Message uses the normal methods to determine where replies are to go
142 (@pxref{Responses}), but you can change the behavior to suit your needs
143 by fiddling with the @code{message-reply-to-function} variable.
144
145 If you want the replies to go to the @code{Sender} instead of the
146 @code{From}, you could do something like this:
147
148 @lisp
149 (setq message-reply-to-function
150       (lambda ()
151        (cond ((equal (mail-fetch-field "from") "somebody")
152                (list (cons 'To (mail-fetch-field "sender"))))
153              (t
154               nil))))
155 @end lisp
156
157 This function will be called narrowed to the head of the article that is
158 being replied to.
159
160 As you can see, this function should return a list.  In this case, it
161 returns @code{((To . "Whom"))} if it has an opinion as to what the To
162 header should be.  If it does not, it should just return @code{nil}, and
163 the normal methods for determining the To header will be used.
164
165 Each list element should be a cons, where the @sc{car} should be the
166 name of a header (e.g., @code{Cc}) and the @sc{cdr} should be the header
167 value (e.g., @samp{larsi@@ifi.uio.no}).  All these headers will be
168 inserted into the head of the outgoing mail.
169
170
171 @node Wide Reply
172 @section Wide Reply
173
174 @findex message-wide-reply
175 The @code{message-wide-reply} pops up a message buffer that's a wide
176 reply to the message in the current buffer.  A @dfn{wide reply} is a
177 reply that goes out to all people listed in the @code{To}, @code{From}
178 (or @code{Reply-to}) and @code{Cc} headers.
179
180 @vindex message-wide-reply-to-function
181 Message uses the normal methods to determine where wide replies are to go,
182 but you can change the behavior to suit your needs by fiddling with the
183 @code{message-wide-reply-to-function}.  It is used in the same way as
184 @code{message-reply-to-function} (@pxref{Reply}).
185
186 @vindex message-dont-reply-to-names
187 Addresses that match the @code{message-dont-reply-to-names} regular
188 expression (or list of regular expressions) will be removed from the
189 @code{Cc} header. A value of @code{nil} means exclude your name only.
190
191 @vindex message-prune-recipient-rules
192 @code{message-prune-recipient-rules} is used to prune the addresses
193 used when doing a wide reply.  It's meant to be used to remove
194 duplicate addresses and the like.  It's a list of lists, where the
195 first element is a regexp to match the address to trigger the rule,
196 and the second is a regexp that will be expanded based on the first,
197 to match addresses to be pruned.
198
199 It's complicated to explain, but it's easy to use.
200
201 For instance, if you get an email from @samp{foo@@example.org}, but
202 @samp{foo@@zot.example.org} is also in the @code{Cc} list, then your
203 wide reply will go out to both these addresses, since they are unique.
204
205 To avoid this, do something like the following:
206
207 @lisp
208 (setq message-prune-recipient-rules
209       '(("^\\([^@@]+\\)@@\\(.*\\)" "\\1@@.*[.]\\2")))
210 @end lisp
211
212 If, for instance, you want all wide replies that involve messages from
213 @samp{cvs@@example.org} to go to that address, and nowhere else (i.e.,
214 remove all other recipients if @samp{cvs@@example.org} is in the
215 recipient list:
216
217 @lisp
218 (setq message-prune-recipient-rules
219       '(("cvs@@example.org" ".")))
220 @end lisp
221
222 @vindex message-wide-reply-confirm-recipients
223 If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you
224 will be asked to confirm that you want to reply to multiple
225 recipients.  The default is @code{nil}.
226
227 @node Followup
228 @section Followup
229
230 @findex message-followup
231 The @code{message-followup} command pops up a message buffer that's a
232 followup to the message in the current buffer.
233
234 @vindex message-followup-to-function
235 Message uses the normal methods to determine where followups are to go,
236 but you can change the behavior to suit your needs by fiddling with the
237 @code{message-followup-to-function}.  It is used in the same way as
238 @code{message-reply-to-function} (@pxref{Reply}).
239
240 @vindex message-use-followup-to
241 The @code{message-use-followup-to} variable says what to do about
242 @code{Followup-To} headers.  If it is @code{use}, always use the value.
243 If it is @code{ask} (which is the default), ask whether to use the
244 value.  If it is @code{t}, use the value unless it is @samp{poster}.  If
245 it is @code{nil}, don't use the value.
246
247
248 @node Canceling News
249 @section Canceling News
250
251 @findex message-cancel-news
252 The @code{message-cancel-news} command cancels the article in the
253 current buffer.
254
255 @vindex message-cancel-message
256 The value of @code{message-cancel-message} is inserted in the body of
257 the cancel message.  The default is @samp{I am canceling my own
258 article.}.
259
260 @cindex Cancel Locks
261 @vindex message-insert-canlock
262 @cindex canlock
263 When Message posts news messages, it inserts @code{Cancel-Lock}
264 headers by default.  This is a cryptographic header that ensures that
265 only you can cancel your own messages, which is nice.  The downside
266 is that if you lose your @file{.emacs} file (which is where Gnus
267 stores the secret cancel lock password (which is generated
268 automatically the first time you use this feature)), you won't be
269 able to cancel your message.  If you want to manage a password yourself,
270 you can put something like the following in your @file{~/.gnus.el} file:
271
272 @lisp
273 (setq canlock-password "geheimnis"
274       canlock-password-for-verify canlock-password)
275 @end lisp
276
277 Whether to insert the header or not is controlled by the
278 @code{message-insert-canlock} variable.
279
280 Not many news servers respect the @code{Cancel-Lock} header yet, but
281 this is expected to change in the future.
282
283
284 @node Superseding
285 @section Superseding
286
287 @findex message-supersede
288 The @code{message-supersede} command pops up a message buffer that will
289 supersede the message in the current buffer.
290
291 @vindex message-ignored-supersedes-headers
292 Headers matching the @code{message-ignored-supersedes-headers} are
293 removed before popping up the new message buffer.  The default is@*
294 @samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@*
295 ^Received:\\|^X-From-Line:\\|^X-Trace:\\|^X-Complaints-To:\\|@*
296 Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@*
297 ^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@*
298 ^X-Payment:\\|^Approved:}.
299
300
301
302 @node Forwarding
303 @section Forwarding
304
305 @findex message-forward
306 The @code{message-forward} command pops up a message buffer to forward
307 the message in the current buffer.  If given a prefix, forward using
308 news.
309
310 @table @code
311 @item message-forward-ignored-headers
312 @vindex message-forward-ignored-headers
313 In non-@code{nil}, all headers that match this regexp will be deleted
314 when forwarding a message.
315
316 @item message-forward-included-headers
317 @vindex message-forward-included-headers
318 In non-@code{nil}, only headers that match this regexp will be kept
319 when forwarding a message.
320
321 @item message-make-forward-subject-function
322 @vindex message-make-forward-subject-function
323 A list of functions that are called to generate a subject header for
324 forwarded messages.  The subject generated by the previous function is
325 passed into each successive function.
326
327 The provided functions are:
328
329 @table @code
330 @item message-forward-subject-author-subject
331 @findex message-forward-subject-author-subject
332 Source of article (author or newsgroup), in brackets followed by the
333 subject.
334
335 @item message-forward-subject-fwd
336 Subject of article with @samp{Fwd:} prepended to it.
337 @end table
338
339 @item message-wash-forwarded-subjects
340 @vindex message-wash-forwarded-subjects
341 If this variable is @code{t}, the subjects of forwarded messages have
342 the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:},
343 @samp{(fwd)}) removed before the new subject is
344 constructed.  The default value is @code{nil}.
345
346 @item message-forward-as-mime
347 @vindex message-forward-as-mime
348 If this variable is @code{t} (the default), forwarded messages are
349 included as inline @acronym{MIME} RFC822 parts.  If it's @code{nil}, forwarded
350 messages will just be copied inline to the new message, like previous,
351 non @acronym{MIME}-savvy versions of Gnus would do.
352
353 @item message-forward-before-signature
354 @vindex message-forward-before-signature
355 If non-@code{nil}, put forwarded message before signature, else after.
356
357 @end table
358
359
360 @node Resending
361 @section Resending
362
363 @findex message-resend
364 The @code{message-resend} command will prompt the user for an address
365 and resend the message in the current buffer to that address.
366
367 @vindex message-ignored-resent-headers
368 Headers that match the @code{message-ignored-resent-headers} regexp will
369 be removed before sending the message.
370
371
372 @node Bouncing
373 @section Bouncing
374
375 @findex message-bounce
376 The @code{message-bounce} command will, if the current buffer contains a
377 bounced mail message, pop up a message buffer stripped of the bounce
378 information.  A @dfn{bounced message} is typically a mail you've sent
379 out that has been returned by some @code{mailer-daemon} as
380 undeliverable.
381
382 @vindex message-ignored-bounced-headers
383 Headers that match the @code{message-ignored-bounced-headers} regexp
384 will be removed before popping up the buffer.  The default is
385 @samp{^\\(Received\\|Return-Path\\|Delivered-To\\):}.
386
387
388 @node Mailing Lists
389 @section Mailing Lists
390
391 @cindex Mail-Followup-To
392 Sometimes while posting to mailing lists, the poster needs to direct
393 followups to the post to specific places.  The Mail-Followup-To (MFT)
394 was created to enable just this.  Three example scenarios where this is
395 useful:
396
397 @itemize @bullet
398 @item
399 A mailing list poster can use MFT to express that responses should be
400 sent to just the list, and not the poster as well.  This will happen
401 if the poster is already subscribed to the list.
402
403 @item
404 A mailing list poster can use MFT to express that responses should be
405 sent to the list and the poster as well.  This will happen if the poster
406 is not subscribed to the list.
407
408 @item
409 If a message is posted to several mailing lists, MFT may also be used
410 to direct the following discussion to one list only, because
411 discussions that are spread over several lists tend to be fragmented
412 and very difficult to follow.
413
414 @end itemize
415
416 Gnus honors the MFT header in other's messages (i.e., while following
417 up to someone else's post) and also provides support for generating
418 sensible MFT headers for outgoing messages as well.
419
420 @c @menu
421 @c * Honoring an MFT post::        What to do when one already exists
422 @c * Composing with a MFT header:: Creating one from scratch.
423 @c @end menu
424
425 @c @node Composing with a MFT header
426 @subsection  Composing a correct MFT header automagically
427
428 The first step in getting Gnus to automagically generate a MFT header
429 in posts you make is to give Gnus a list of the mailing lists
430 addresses you are subscribed to.  You can do this in more than one
431 way.  The following variables would come in handy.
432
433 @table @code
434
435 @vindex message-subscribed-addresses
436 @item message-subscribed-addresses
437 This should be a list of addresses the user is subscribed to.  Its
438 default value is @code{nil}.  Example:
439 @lisp
440 (setq message-subscribed-addresses
441       '("ding@@gnus.org" "bing@@noose.org"))
442 @end lisp
443
444 @vindex message-subscribed-regexps
445 @item message-subscribed-regexps
446 This should be a list of regexps denoting the addresses of mailing
447 lists subscribed to.  Default value is @code{nil}.  Example: If you
448 want to achieve the same result as above:
449 @lisp
450 (setq message-subscribed-regexps
451       '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org")
452 @end lisp
453
454 @vindex message-subscribed-address-functions
455 @item message-subscribed-address-functions
456 This can be a list of functions to be called (one at a time!!) to
457 determine the value of MFT headers.  It is advisable that these
458 functions not take any arguments.  Default value is @code{nil}.
459
460 There is a pre-defined function in Gnus that is a good candidate for
461 this variable.  @code{gnus-find-subscribed-addresses} is a function
462 that returns a list of addresses corresponding to the groups that have
463 the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters,
464 gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value.
465 This is how you would do it.
466
467 @lisp
468 (setq message-subscribed-address-functions
469       '(gnus-find-subscribed-addresses))
470 @end lisp
471
472 @vindex message-subscribed-address-file
473 @item message-subscribed-address-file
474 You might be one organized human freak and have a list of addresses of
475 all subscribed mailing lists in a separate file!  Then you can just
476 set this variable to the name of the file and life would be good.
477
478 @end table
479
480 You can use one or more of the above variables.  All their values are
481 ``added'' in some way that works :-)
482
483 Now you are all set.  Just start composing a message as you normally do.
484 And just send it; as always.  Just before the message is sent out, Gnus'
485 MFT generation thingy kicks in and checks if the message already has a
486 MFT field.  If there is one, it is left alone.  (Except if it's empty;
487 in that case, the field is removed and is not replaced with an
488 automatically generated one.  This lets you disable MFT generation on a
489 per-message basis.)  If there is none, then the list of recipient
490 addresses (in the To: and Cc: headers) is checked to see if one of them
491 is a list address you are subscribed to.  If none of them is a list
492 address, then no MFT is generated; otherwise, a MFT is added to the
493 other headers and set to the value of all addresses in To: and Cc:
494
495 @kindex C-c C-f C-a
496 @findex message-generate-unsubscribed-mail-followup-to
497 @kindex C-c C-f C-m
498 @findex message-goto-mail-followup-to
499 Hm.  ``So'', you ask, ``what if I send an email to a list I am not
500 subscribed to?  I want my MFT to say that I want an extra copy.''  (This
501 is supposed to be interpreted by others the same way as if there were no
502 MFT, but you can use an explicit MFT to override someone else's
503 to-address group parameter.)  The function
504 @code{message-generate-unsubscribed-mail-followup-to} might come in
505 handy.  It is bound to @kbd{C-c C-f C-a} by default.  In any case, you
506 can insert a MFT of your own choice; @kbd{C-c C-f C-m}
507 (@code{message-goto-mail-followup-to}) will help you get started.
508
509 @c @node Honoring an MFT post
510 @subsection Honoring an MFT post
511
512 @vindex message-use-mail-followup-to
513 When you followup to a post on a mailing list, and the post has a MFT
514 header, Gnus' action will depend on the value of the variable
515 @code{message-use-mail-followup-to}.  This variable can be one of:
516
517 @table @code
518 @item use
519  Always honor MFTs.  The To: and Cc: headers in your followup will be
520  derived from the MFT header of the original post.  This is the default.
521
522 @item nil
523  Always dishonor MFTs (just ignore the darned thing)
524
525 @item ask
526 Gnus will prompt you for an action.
527
528 @end table
529
530 It is considered good netiquette to honor MFT, as it is assumed the
531 fellow who posted a message knows where the followups need to go
532 better than you do.
533
534 @node Commands
535 @chapter Commands
536
537 @menu
538 * Buffer Entry::        Commands after entering a Message buffer.
539 * Header Commands::     Commands for moving headers or changing headers.
540 * Movement::            Moving around in message buffers.
541 * Insertion::           Inserting things into message buffers.
542 * MIME::                @acronym{MIME} considerations.
543 * IDNA::                Non-@acronym{ASCII} domain name considerations.
544 * Security::            Signing and encrypting messages.
545 * Various Commands::    Various things.
546 * Sending::             Actually sending the message.
547 * Mail Aliases::        How to use mail aliases.
548 * Spelling::            Having Emacs check your spelling.
549 @end menu
550
551
552 @node Buffer Entry
553 @section Buffer Entry
554 @cindex undo
555 @kindex C-_
556
557 You most often end up in a Message buffer when responding to some other
558 message of some sort.  Message does lots of handling of quoted text, and
559 may remove signatures, reformat the text, or the like---depending on
560 which used settings you're using.  Message usually gets things right,
561 but sometimes it stumbles.  To help the user unwind these stumblings,
562 Message sets the undo boundary before each major automatic action it
563 takes.  If you press the undo key (usually located at @kbd{C-_}) a few
564 times, you will get back the un-edited message you're responding to.
565
566
567 @node Header Commands
568 @section Header Commands
569
570 @subsection Commands for moving to headers
571
572 These following commands move to the header in question.  If it doesn't
573 exist, it will be inserted.
574
575 @table @kbd
576
577 @item C-c ?
578 @kindex C-c ?
579 @findex describe-mode
580 Describe the message mode.
581
582 @item C-c C-f C-t
583 @kindex C-c C-f C-t
584 @findex message-goto-to
585 Go to the @code{To} header (@code{message-goto-to}).
586
587 @item C-c C-f C-o
588 @kindex C-c C-f C-o
589 @findex message-goto-from
590 Go to the @code{From} header (@code{message-goto-from}).  (The ``o''
591 in the key binding is for Originator.)
592
593 @item C-c C-f C-b
594 @kindex C-c C-f C-b
595 @findex message-goto-bcc
596 Go to the @code{Bcc} header (@code{message-goto-bcc}).
597
598 @item C-c C-f C-w
599 @kindex C-c C-f C-w
600 @findex message-goto-fcc
601 Go to the @code{Fcc} header (@code{message-goto-fcc}).
602
603 @item C-c C-f C-c
604 @kindex C-c C-f C-c
605 @findex message-goto-cc
606 Go to the @code{Cc} header (@code{message-goto-cc}).
607
608 @item C-c C-f C-s
609 @kindex C-c C-f C-s
610 @findex message-goto-subject
611 Go to the @code{Subject} header (@code{message-goto-subject}).
612
613 @item C-c C-f C-r
614 @kindex C-c C-f C-r
615 @findex message-goto-reply-to
616 Go to the @code{Reply-To} header (@code{message-goto-reply-to}).
617
618 @item C-c C-f C-n
619 @kindex C-c C-f C-n
620 @findex message-goto-newsgroups
621 Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}).
622
623 @item C-c C-f C-d
624 @kindex C-c C-f C-d
625 @findex message-goto-distribution
626 Go to the @code{Distribution} header (@code{message-goto-distribution}).
627
628 @item C-c C-f C-f
629 @kindex C-c C-f C-f
630 @findex message-goto-followup-to
631 Go to the @code{Followup-To} header (@code{message-goto-followup-to}).
632
633 @item C-c C-f C-k
634 @kindex C-c C-f C-k
635 @findex message-goto-keywords
636 Go to the @code{Keywords} header (@code{message-goto-keywords}).
637
638 @item C-c C-f C-u
639 @kindex C-c C-f C-u
640 @findex message-goto-summary
641 Go to the @code{Summary} header (@code{message-goto-summary}).
642
643 @item C-c C-f C-i
644 @kindex C-c C-f C-i
645 @findex message-insert-or-toggle-importance
646 This inserts the @samp{Importance:} header with a value of
647 @samp{high}.  This header is used to signal the importance of the
648 message to the receiver.  If the header is already present in the
649 buffer, it cycles between the three valid values according to RFC
650 1376: @samp{low}, @samp{normal} and @samp{high}.
651
652 @item C-c C-f C-a
653 @kindex C-c C-f C-a
654 @findex message-generate-unsubscribed-mail-followup-to
655 Insert a reasonable @samp{Mail-Followup-To:} header
656 (@pxref{Mailing Lists}) in a post to an
657 unsubscribed list.  When making original posts to a mailing list you are
658 not subscribed to, you have to type in a @samp{Mail-Followup-To:} header
659 by hand.  The contents, usually, are the addresses of the list and your
660 own address.  This function inserts such a header automatically.  It
661 fetches the contents of the @samp{To:} header in the current mail
662 buffer, and appends the current @code{user-mail-address}.
663
664 If the optional argument @code{include-cc} is non-@code{nil}, the
665 addresses in the @samp{Cc:} header are also put into the
666 @samp{Mail-Followup-To:} header.
667
668 @end table
669
670 @subsection  Commands to change headers
671
672 @table @kbd
673
674 @item C-c C-o
675 @kindex C-c C-o
676 @findex message-sort-headers
677 @vindex message-header-format-alist
678 Sort headers according to @code{message-header-format-alist}
679 (@code{message-sort-headers}).
680
681 @item C-c C-t
682 @kindex C-c C-t
683 @findex message-insert-to
684 Insert a @code{To} header that contains the @code{Reply-To} or
685 @code{From} header of the message you're following up
686 (@code{message-insert-to}).
687
688 @item C-c C-n
689 @kindex C-c C-n
690 @findex message-insert-newsgroups
691 Insert a @code{Newsgroups} header that reflects the @code{Followup-To}
692 or @code{Newsgroups} header of the article you're replying to
693 (@code{message-insert-newsgroups}).
694
695 @item C-c C-l
696 @kindex C-c C-l
697 @findex message-to-list-only
698 Send a message to the list only.  Remove all addresses but the list
699 address from @code{To:} and @code{Cc:} headers.
700
701 @item C-c M-n
702 @kindex C-c M-n
703 @findex message-insert-disposition-notification-to
704 Insert a request for a disposition
705 notification.  (@code{message-insert-disposition-notification-to}).
706 This means that if the recipient supports RFC 2298 she might send you a
707 notification that she received the message.
708
709 @item M-x message-insert-importance-high
710 @kindex M-x message-insert-importance-high
711 @findex message-insert-importance-high
712 @cindex Importance
713 Insert an @samp{Importance} header with a value of @samp{high},
714 deleting headers if necessary.
715
716 @item M-x message-insert-importance-low
717 @kindex M-x message-insert-importance-low
718 @findex message-insert-importance-low
719 @cindex Importance
720 Insert an @samp{Importance} header with a value of @samp{low}, deleting
721 headers if necessary.
722
723 @item C-c C-f s
724 @kindex C-c C-f s
725 @findex message-change-subject
726 @cindex Subject
727 Change the current @samp{Subject} header.  Ask for new @samp{Subject}
728 header and append @samp{(was: <Old Subject>)}.  The old subject can be
729 stripped on replying, see @code{message-subject-trailing-was-query}
730 (@pxref{Message Headers}).
731
732 @item C-c C-f x
733 @kindex C-c C-f x
734 @findex message-cross-post-followup-to
735 @vindex message-cross-post-default
736 @vindex message-cross-post-note-function
737 @cindex X-Post
738 @cindex cross-post
739 Set up the @samp{FollowUp-To} header with a target newsgroup for a
740 cross-post, add that target newsgroup to the @samp{Newsgroups} header if
741 it is not a member of @samp{Newsgroups}, and insert a note in the body.
742 If @code{message-cross-post-default} is @code{nil} or if this command is
743 called with a prefix-argument, only the @samp{FollowUp-To} header will
744 be set but the target newsgroup will not be added to the
745 @samp{Newsgroups} header.  The function to insert a note is controlled
746 by the @code{message-cross-post-note-function} variable.
747
748 @item C-c C-f t
749 @kindex C-c C-f t
750 @findex message-reduce-to-to-cc
751 Replace contents of @samp{To} header with contents of @samp{Cc}
752 header (or the @samp{Bcc} header, if there is no @samp{Cc} header).
753
754 @item C-c C-f w
755 @kindex C-c C-f w
756 @findex message-insert-wide-reply
757 Insert @samp{To} and @samp{Cc} headers as if you were doing a wide
758 reply even if the message was not made for a wide reply first.
759
760 @item C-c C-f a
761 @kindex C-c C-f a
762 @findex message-add-archive-header
763 @vindex message-archive-header
764 @vindex message-archive-note
765 @cindex X-No-Archive
766 Insert @samp{X-No-Archive: Yes} in the header and a note in the body.
767 The header and the note can be customized using
768 @code{message-archive-header} and @code{message-archive-note}.  When
769 called with a prefix argument, ask for a text to insert.  If you don't
770 want the note in the body, set @code{message-archive-note} to
771 @code{nil}.
772
773 @end table
774
775
776 @node Movement
777 @section Movement
778
779 @table @kbd
780 @item C-c C-b
781 @kindex C-c C-b
782 @findex message-goto-body
783 Move to the beginning of the body of the message
784 (@code{message-goto-body}).
785
786 @item C-c C-i
787 @kindex C-c C-i
788 @findex message-goto-signature
789 Move to the signature of the message (@code{message-goto-signature}).
790
791 @item C-a
792 @kindex C-a
793 @findex message-beginning-of-line
794 @vindex message-beginning-of-line
795 If at beginning of header value, go to beginning of line, else go to
796 beginning of header value.  (The header value comes after the header
797 name and the colon.)  This behavior can be disabled by toggling
798 the variable @code{message-beginning-of-line}.
799
800 @end table
801
802
803 @node Insertion
804 @section Insertion
805
806 @table @kbd
807
808 @item C-c C-y
809 @kindex C-c C-y
810 @findex message-yank-original
811 Yank the message that's being replied to into the message buffer
812 (@code{message-yank-original}).
813
814 @item C-c C-M-y
815 @kindex C-c C-M-y
816 @findex message-yank-buffer
817 Prompt for a buffer name and yank the contents of that buffer into the
818 message buffer (@code{message-yank-buffer}).
819
820 @item C-c C-q
821 @kindex C-c C-q
822 @findex message-fill-yanked-message
823 Fill the yanked message (@code{message-fill-yanked-message}).  Warning:
824 Can severely mess up the yanked text if its quoting conventions are
825 strange.  You'll quickly get a feel for when it's safe, though.  Anyway,
826 just remember that @kbd{C-x u} (@code{undo}) is available and you'll be
827 all right.
828
829 @item C-c C-w
830 @kindex C-c C-w
831 @findex message-insert-signature
832 Insert a signature at the end of the buffer
833 (@code{message-insert-signature}).
834
835 @item C-c M-h
836 @kindex C-c M-h
837 @findex message-insert-headers
838 Insert the message headers (@code{message-insert-headers}).
839
840 @item C-c M-m
841 @kindex C-c M-m
842 @findex message-mark-inserted-region
843 Mark some region in the current article with enclosing tags.  See
844 @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
845 When called with a prefix argument, use slrn style verbatim marks
846 (@samp{#v+} and @samp{#v-}).
847
848 @item C-c M-f
849 @kindex C-c M-f
850 @findex message-mark-insert-file
851 Insert a file in the current article with enclosing tags.
852 See @code{message-mark-insert-begin} and @code{message-mark-insert-end}.
853 When called with a prefix argument, use slrn style verbatim marks
854 (@samp{#v+} and @samp{#v-}).
855
856 @end table
857
858
859 @node MIME
860 @section MIME
861 @cindex MML
862 @cindex MIME
863 @cindex multipart
864 @cindex attachment
865
866 Message is a @acronym{MIME}-compliant posting agent.  The user generally
867 doesn't have to do anything to make the @acronym{MIME} happen---Message will
868 automatically add the @code{Content-Type} and
869 @code{Content-Transfer-Encoding} headers.
870
871 @findex mml-attach-file
872 @kindex C-c C-a
873 The most typical thing users want to use the multipart things in
874 @acronym{MIME} for is to add ``attachments'' to mail they send out.
875 This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}),
876 which will prompt for a file name and a @acronym{MIME} type.
877
878 @vindex mml-dnd-protocol-alist
879 @vindex mml-dnd-attach-options
880 If your Emacs supports drag and drop, you can also drop the file in the
881 Message buffer.  The variable @code{mml-dnd-protocol-alist} specifies
882 what kind of action is done when you drop a file into the Message
883 buffer.  The variable @code{mml-dnd-attach-options} controls which
884 @acronym{MIME} options you want to specify when dropping a file.  If it
885 is a list, valid members are @code{type}, @code{description} and
886 @code{disposition}.  @code{disposition} implies @code{type}.  If it is
887 @code{nil}, don't ask for options.  If it is @code{t}, ask the user
888 whether or not to specify options.
889
890 You can also create arbitrarily complex multiparts using the @acronym{MML}
891 language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME
892 Manual}).
893
894 @node IDNA
895 @section IDNA
896 @cindex IDNA
897 @cindex internationalized domain names
898 @cindex non-ascii domain names
899
900 @acronym{IDNA} is a standard way to encode non-@acronym{ASCII} domain
901 names into a readable @acronym{ASCII} string.  The details can be
902 found in RFC 3490.
903
904 Message is a @acronym{IDNA}-compliant posting agent.  The user
905 generally doesn't have to do anything to make the @acronym{IDNA}
906 happen---Message will encode non-@acronym{ASCII} domain names in @code{From},
907 @code{To}, and @code{Cc} headers automatically.
908
909 Until @acronym{IDNA} becomes more well known, Message queries you
910 whether @acronym{IDNA} encoding of the domain name really should
911 occur.  Some users might not be aware that domain names can contain
912 non-@acronym{ASCII} now, so this gives them a safety net if they accidentally
913 typed a non-@acronym{ASCII} domain name.
914
915 @vindex message-use-idna
916 The @code{message-use-idna} variable control whether @acronym{IDNA} is
917 used.  If the variable is @code{nil} no @acronym{IDNA} encoding will
918 ever happen, if it is set to the symbol @code{ask} the user will be
919 queried, and if set to @code{t} (which is the default if @acronym{IDNA}
920 is fully available) @acronym{IDNA} encoding happens automatically.
921
922 @findex message-idna-to-ascii-rhs
923 If you want to experiment with the @acronym{IDNA} encoding, you can
924 invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer
925 to have the non-@acronym{ASCII} domain names encoded while you edit
926 the message.
927
928 Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU
929 Libidn} installed in order to use this functionality.
930
931 @node Security
932 @section Security
933 @cindex Security
934 @cindex S/MIME
935 @cindex PGP
936 @cindex PGP/MIME
937 @cindex sign
938 @cindex encrypt
939 @cindex secure
940
941 Using the @acronym{MML} language, Message is able to create digitally
942 signed and digitally encrypted messages.  Message (or rather
943 @acronym{MML}) currently support @acronym{PGP} (RFC 1991),
944 @acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}.
945
946 @menu
947 * Signing and encryption::      Signing and encrypting commands.
948 * Using S/MIME::                Using S/MIME
949 * Using PGP/MIME::              Using PGP/MIME
950 * PGP Compatibility::           Compatibility with older implementations
951 @end menu
952
953 @node Signing and encryption
954 @subsection Signing and encrypting commands
955
956 Instructing @acronym{MML} to perform security operations on a
957 @acronym{MIME} part is done using the @kbd{C-c C-m s} key map for
958 signing and the @kbd{C-c C-m c} key map for encryption, as follows.
959 @table @kbd
960
961 @item C-c C-m s s
962 @kindex C-c C-m s s
963 @findex mml-secure-message-sign-smime
964
965 Digitally sign current message using @acronym{S/MIME}.
966
967 @item C-c C-m s o
968 @kindex C-c C-m s o
969 @findex mml-secure-message-sign-pgp
970
971 Digitally sign current message using @acronym{PGP}.
972
973 @item C-c C-m s p
974 @kindex C-c C-m s p
975 @findex mml-secure-message-sign-pgpmime
976
977 Digitally sign current message using @acronym{PGP/MIME}.
978
979 @item C-c C-m c s
980 @kindex C-c C-m c s
981 @findex mml-secure-message-encrypt-smime
982
983 Digitally encrypt current message using @acronym{S/MIME}.
984
985 @item C-c C-m c o
986 @kindex C-c C-m c o
987 @findex mml-secure-message-encrypt-pgp
988
989 Digitally encrypt current message using @acronym{PGP}.
990
991 @item C-c C-m c p
992 @kindex C-c C-m c p
993 @findex mml-secure-message-encrypt-pgpmime
994
995 Digitally encrypt current message using @acronym{PGP/MIME}.
996
997 @item C-c C-m C-n
998 @kindex C-c C-m C-n
999 @findex mml-unsecure-message
1000 Remove security related @acronym{MML} tags from message.
1001
1002 @end table
1003
1004 These commands do not immediately sign or encrypt the message, they
1005 merely insert the proper @acronym{MML} secure tag to instruct the
1006 @acronym{MML} engine to perform that operation when the message is
1007 actually sent.  They may perform other operations too, such as locating
1008 and retrieving a @acronym{S/MIME} certificate of the person you wish to
1009 send encrypted mail to.  When the mml parsing engine converts your
1010 @acronym{MML} into a properly encoded @acronym{MIME} message, the secure
1011 tag will be replaced with either a part or a multipart tag.  If your
1012 message contains other mml parts, a multipart tag will be used; if no
1013 other parts are present in your message a single part tag will be used.
1014 This way, message mode will do the Right Thing (TM) with
1015 signed/encrypted multipart messages.
1016
1017 Since signing and especially encryption often is used when sensitive
1018 information is sent, you may want to have some way to ensure that your
1019 mail is actually signed or encrypted.  After invoking the above
1020 sign/encrypt commands, it is possible to preview the raw article by
1021 using @kbd{C-u C-c RET P} (@code{mml-preview}).  Then you can
1022 verify that your long rant about what your ex-significant other or
1023 whomever actually did with that funny looking person at that strange
1024 party the other night, actually will be sent encrypted.
1025
1026 @emph{Note!}  Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs
1027 RFC822 headers.  They only operate on the @acronym{MIME} object.  Keep this
1028 in mind before sending mail with a sensitive Subject line.
1029
1030 By default, when encrypting a message, Gnus will use the
1031 ``signencrypt'' mode, which means the message is both signed and
1032 encrypted.  If you would like to disable this for a particular
1033 message, give the @code{mml-secure-message-encrypt-*} command a prefix
1034 argument, e.g., @kbd{C-u C-c C-m c p}.
1035
1036 Actually using the security commands above is not very difficult.  At
1037 least not compared with making sure all involved programs talk with each
1038 other properly.  Thus, we now describe what external libraries or
1039 programs are required to make things work, and some small general hints.
1040
1041 @node Using S/MIME
1042 @subsection Using S/MIME
1043
1044 @emph{Note!}  This section assume you have a basic familiarity with
1045 modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and
1046 so on.
1047
1048 The @acronym{S/MIME} support in Message (and @acronym{MML}) require
1049 OpenSSL@.  OpenSSL performs the actual @acronym{S/MIME} sign/encrypt
1050 operations.  OpenSSL can be found at @uref{http://www.openssl.org/}.
1051 OpenSSL 0.9.6 and later should work.  Version 0.9.5a cannot extract mail
1052 addresses from certificates, and it insert a spurious CR character into
1053 @acronym{MIME} separators so you may wish to avoid it if you would like
1054 to avoid being regarded as someone who send strange mail.  (Although by
1055 sending @acronym{S/MIME} messages you've probably already lost that
1056 contest.)
1057
1058 To be able to send encrypted mail, a personal certificate is not
1059 required.  Message (@acronym{MML}) need a certificate for the person to whom you
1060 wish to communicate with though.  You're asked for this when you type
1061 @kbd{C-c C-m c s}.  Currently there are two ways to retrieve this
1062 certificate, from a local file or from DNS@.  If you chose a local
1063 file, it need to contain a X.509 certificate in @acronym{PEM} format.
1064 If you chose DNS, you're asked for the domain name where the
1065 certificate is stored, the default is a good guess.  To my belief,
1066 Message (@acronym{MML}) is the first mail agent in the world to support
1067 retrieving @acronym{S/MIME} certificates from DNS, so you're not
1068 likely to find very many certificates out there.  At least there
1069 should be one, stored at the domain @code{simon.josefsson.org}.  LDAP
1070 is a more popular method of distributing certificates, support for it
1071 is planned.  (Meanwhile, you can use @code{ldapsearch} from the
1072 command line to retrieve a certificate into a file and use it.)
1073
1074 As for signing messages, OpenSSL can't perform signing operations
1075 without some kind of configuration.  Especially, you need to tell it
1076 where your private key and your certificate is stored.  @acronym{MML}
1077 uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it
1078 contain a @code{custom} group used for this configuration.  So, try
1079 @kbd{M-x customize-group RET smime RET} and look around.
1080
1081 Currently there is no support for talking to a CA (or RA) to create
1082 your own certificate.  None is planned either.  You need to do this
1083 manually with OpenSSL or using some other program.  I used Netscape
1084 and got a free @acronym{S/MIME} certificate from one of the big CA's on the
1085 net.  Netscape is able to export your private key and certificate in
1086 PKCS #12 format.  Use OpenSSL to convert this into a plain X.509
1087 certificate in PEM format as follows.
1088
1089 @example
1090 $ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem
1091 @end example
1092
1093 The @file{key+cert.pem} file should be pointed to from the
1094 @code{smime-keys} variable.  You should now be able to send signed mail.
1095
1096 @emph{Note!}  Your private key is now stored unencrypted in the file,
1097 so take care in handling it.  Storing encrypted keys on the disk are
1098 supported, and Gnus will ask you for a passphrase before invoking
1099 OpenSSL@.  Read the OpenSSL documentation for how to achieve this.  If
1100 you use unencrypted keys (e.g., if they are on a secure storage, or if
1101 you are on a secure single user machine) simply press @code{RET} at
1102 the passphrase prompt.
1103
1104 @node Using PGP/MIME
1105 @subsection Using PGP/MIME
1106
1107 @acronym{PGP/MIME} requires an external OpenPGP implementation, such
1108 as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
1109 implementations such as PGP 2.x and PGP 5.x are also supported.  The
1110 default Emacs interface to the PGP implementation is EasyPG
1111 (@pxref{Top,,EasyPG Assistant User's Manual, epa, EasyPG Assistant
1112 User's Manual}), but PGG (@pxref{Top, ,PGG, pgg, PGG Manual}) and
1113 Mailcrypt are also supported.  @xref{PGP Compatibility}.
1114
1115 @cindex gpg-agent
1116 Message internally calls GnuPG (the @command{gpg} command) to perform
1117 data encryption, and in certain cases (decrypting or signing for
1118 example), @command{gpg} requires user's passphrase.  Currently the
1119 recommended way to supply your passphrase to @command{gpg} is to use the
1120 @command{gpg-agent} program.
1121
1122 To use @command{gpg-agent} in Emacs, you need to run the following
1123 command from the shell before starting Emacs.
1124
1125 @example
1126 eval `gpg-agent --daemon`
1127 @end example
1128
1129 This will invoke @command{gpg-agent} and set the environment variable
1130 @code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it.
1131 It might be good idea to put this command in your @file{.xsession} or
1132 @file{.bash_profile}.  @xref{Invoking GPG-AGENT, , , gnupg, Using the
1133 GNU Privacy Guard}.
1134
1135 Once your @command{gpg-agent} is set up, it will ask you for a
1136 passphrase as needed for @command{gpg}.  Under the X Window System,
1137 you will see a new passphrase input dialog appear.  The dialog is
1138 provided by PIN Entry (the @command{pinentry} command), and as of
1139 version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a
1140 single tty.  So, if you are using a text console, you may need to put
1141 a passphrase into gpg-agent's cache beforehand.  The following command
1142 does the trick.
1143
1144 @example
1145 gpg --use-agent --sign < /dev/null > /dev/null
1146 @end example
1147
1148 @node PGP Compatibility
1149 @subsection Compatibility with older implementations
1150
1151 @vindex gpg-temp-directory
1152 Note, if you are using the @code{gpg.el} you must make sure that the
1153 directory specified by @code{gpg-temp-directory} have permissions
1154 0700.
1155
1156 Creating your own key is described in detail in the documentation of
1157 your PGP implementation, so we refer to it.
1158
1159 If you have imported your old PGP 2.x key into GnuPG, and want to send
1160 signed and encrypted messages to your fellow PGP 2.x users, you'll
1161 discover that the receiver cannot understand what you send. One
1162 solution is to use PGP 2.x instead (e.g., if you use @code{pgg}, set
1163 @code{pgg-default-scheme} to @code{pgp}). You could also convince your
1164 fellow PGP 2.x users to convert to GnuPG@.
1165 @vindex mml-signencrypt-style-alist
1166 As a final workaround, you can make the sign and encryption work in
1167 two steps; separately sign, then encrypt a message.  If you would like
1168 to change this behavior you can customize the
1169 @code{mml-signencrypt-style-alist} variable.  For example:
1170
1171 @lisp
1172 (setq mml-signencrypt-style-alist '(("smime" separate)
1173                                     ("pgp" separate)
1174                                     ("pgpauto" separate)
1175                                     ("pgpmime" separate)))
1176 @end lisp
1177
1178 This causes to sign and encrypt in two passes, thus generating a
1179 message that can be understood by PGP version 2.
1180
1181 (Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more
1182 information about the problem.)
1183
1184 @node Various Commands
1185 @section Various Commands
1186
1187 @table @kbd
1188
1189 @item C-c C-r
1190 @kindex C-c C-r
1191 @findex message-caesar-buffer-body
1192 Caesar rotate (aka. rot13) the current message
1193 (@code{message-caesar-buffer-body}).  If narrowing is in effect, just
1194 rotate the visible portion of the buffer.  A numerical prefix says how
1195 many places to rotate the text.  The default is 13.
1196
1197 @item C-c C-e
1198 @kindex C-c C-e
1199 @findex message-elide-region
1200 @vindex message-elide-ellipsis
1201 Elide the text between point and mark (@code{message-elide-region}).
1202 The text is killed and replaced with the contents of the variable
1203 @code{message-elide-ellipsis}.  The default value is to use an ellipsis
1204 (@samp{[...]}).
1205
1206 This is a format-spec string, and you can use @samp{%l} to say how
1207 many lines were removed, and @samp{%c} to say how many characters were
1208 removed.
1209
1210 @item C-c M-k
1211 @kindex C-c M-k
1212 @findex message-kill-address
1213 Kill the address under point.
1214
1215 @item C-c C-z
1216 @kindex C-c C-z
1217 @findex message-kill-to-signature
1218 Kill all the text up to the signature, or if that's missing, up to the
1219 end of the message (@code{message-kill-to-signature}).
1220
1221 @item C-c C-v
1222 @kindex C-c C-v
1223 @findex message-delete-not-region
1224 Delete all text in the body of the message that is outside the region
1225 (@code{message-delete-not-region}).
1226
1227 @item M-RET
1228 @kindex M-RET
1229 @findex message-newline-and-reformat
1230 Insert four newlines, and then reformat if inside quoted text.
1231
1232 Here's an example:
1233
1234 @example
1235 > This is some quoted text.  And here's more quoted text.
1236 @end example
1237
1238 If point is before @samp{And} and you press @kbd{M-RET}, you'll get:
1239
1240 @example
1241 > This is some quoted text.
1242
1243 *
1244
1245 > And here's more quoted text.
1246 @end example
1247
1248 @samp{*} says where point will be placed.
1249
1250 @item C-c M-r
1251 @kindex C-c M-r
1252 @findex message-rename-buffer
1253 Rename the buffer (@code{message-rename-buffer}).  If given a prefix,
1254 prompt for a new buffer name.
1255
1256 @item TAB
1257 @kindex TAB
1258 @findex message-tab
1259 @vindex message-tab-body-function
1260 If @code{message-tab-body-function} is non-@code{nil}, execute the
1261 function it specifies.  Otherwise use the function bound to @kbd{TAB} in
1262 @code{text-mode-map} or @code{global-map}.
1263
1264 @end table
1265
1266
1267 @node Sending
1268 @section Sending
1269
1270 @table @kbd
1271 @item C-c C-c
1272 @kindex C-c C-c
1273 @findex message-send-and-exit
1274 Send the message and bury the current buffer
1275 (@code{message-send-and-exit}).
1276
1277 @item C-c C-s
1278 @kindex C-c C-s
1279 @findex message-send
1280 Send the message (@code{message-send}).
1281
1282 @item C-c C-d
1283 @kindex C-c C-d
1284 @findex message-dont-send
1285 Bury the message buffer and exit (@code{message-dont-send}).
1286
1287 @item C-c C-k
1288 @kindex C-c C-k
1289 @findex message-kill-buffer
1290 Kill the message buffer and exit (@code{message-kill-buffer}).
1291
1292 @end table
1293
1294
1295
1296 @node Mail Aliases
1297 @section Mail Aliases
1298 @cindex mail aliases
1299 @cindex aliases
1300 @cindex completion
1301 @cindex ecomplete
1302
1303 @vindex message-mail-alias-type
1304 The @code{message-mail-alias-type} variable controls what type of mail
1305 alias expansion to use.  Currently two forms are supported:
1306 @code{mailabbrev} and @code{ecomplete}.  If this variable is
1307 @code{nil}, no mail alias expansion will be performed.
1308
1309 @code{mailabbrev} works by parsing the @file{/etc/mailrc} and
1310 @file{~/.mailrc} files.  These files look like:
1311
1312 @example
1313 alias lmi "Lars Magne Ingebrigtsen <larsi@@ifi.uio.no>"
1314 alias ding "ding@@ifi.uio.no (ding mailing list)"
1315 @end example
1316
1317 After adding lines like this to your @file{~/.mailrc} file, you should
1318 be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so
1319 on) headers and press @kbd{SPC} to expand the alias.
1320
1321 No expansion will be performed upon sending of the message---all
1322 expansions have to be done explicitly.
1323
1324 If you're using @code{ecomplete}, all addresses from @code{To} and
1325 @code{Cc} headers will automatically be put into the
1326 @file{~/.ecompleterc} file.  When you enter text in the @code{To} and
1327 @code{Cc} headers, @code{ecomplete} will check out the values stored
1328 there and ``electrically'' say what completions are possible.  To
1329 choose one of these completions, use the @kbd{M-n} command to move
1330 down to the list.  Use @kbd{M-n} and @kbd{M-p} to move down and up the
1331 list, and @kbd{RET} to choose a completion.
1332
1333 @node Spelling
1334 @section Spelling
1335 @cindex spelling
1336 @findex ispell-message
1337
1338 There are two popular ways to have Emacs spell-check your messages:
1339 @code{ispell} and @code{flyspell}.  @code{ispell} is the older and
1340 probably more popular package.  You typically first write the message,
1341 and then run the entire thing through @code{ispell} and fix all the
1342 typos.  To have this happen automatically when you send a message, put
1343 something like the following in your @file{.emacs} file:
1344
1345 @lisp
1346 (add-hook 'message-send-hook 'ispell-message)
1347 @end lisp
1348
1349 @vindex ispell-message-dictionary-alist
1350 If you're in the habit of writing in different languages, this can be
1351 controlled by the @code{ispell-message-dictionary-alist} variable:
1352
1353 @lisp
1354 (setq ispell-message-dictionary-alist
1355       '(("^Newsgroups:.*\\bde\\." . "deutsch8")
1356         (".*" . "default")))
1357 @end lisp
1358
1359 @code{ispell} depends on having the external @samp{ispell} command
1360 installed.
1361
1362 The other popular method is using @code{flyspell}.  This package checks
1363 your spelling while you're writing, and marks any mis-spelled words in
1364 various ways.
1365
1366 To use @code{flyspell}, put something like the following in your
1367 @file{.emacs} file:
1368
1369 @lisp
1370 (defun my-message-setup-routine ()
1371   (flyspell-mode 1))
1372 (add-hook 'message-setup-hook 'my-message-setup-routine)
1373 @end lisp
1374
1375 @code{flyspell} depends on having the external @samp{ispell} command
1376 installed.
1377
1378
1379 @node Variables
1380 @chapter Variables
1381
1382 @menu
1383 * Message Headers::             General message header stuff.
1384 * Mail Headers::                Customizing mail headers.
1385 * Mail Variables::              Other mail variables.
1386 * News Headers::                Customizing news headers.
1387 * News Variables::              Other news variables.
1388 * Insertion Variables::         Customizing how things are inserted.
1389 * Various Message Variables::   Other message variables.
1390 * Sending Variables::           Variables for sending.
1391 * Message Buffers::             How Message names its buffers.
1392 * Message Actions::             Actions to be performed when exiting.
1393 @end menu
1394
1395
1396 @node Message Headers
1397 @section Message Headers
1398
1399 Message is quite aggressive on the message generation front.  It has to
1400 be---it's a combined news and mail agent.  To be able to send combined
1401 messages, it has to generate all headers itself (instead of letting the
1402 mail/news system do it) to ensure that mail and news copies of messages
1403 look sufficiently similar.
1404
1405 @table @code
1406
1407 @item message-generate-headers-first
1408 @vindex message-generate-headers-first
1409 If @code{t}, generate all required headers before starting to
1410 compose the message.  This can also be a list of headers to generate:
1411
1412 @lisp
1413 (setq message-generate-headers-first
1414       '(References))
1415 @end lisp
1416
1417 @vindex message-required-headers
1418 The variables @code{message-required-headers},
1419 @code{message-required-mail-headers} and
1420 @code{message-required-news-headers} specify which headers are
1421 required.
1422
1423 Note that some headers will be removed and re-generated before posting,
1424 because of the variable @code{message-deletable-headers} (see below).
1425
1426 @item message-draft-headers
1427 @vindex message-draft-headers
1428 When running Message from Gnus, the message buffers are associated
1429 with a draft group.  @code{message-draft-headers} says which headers
1430 should be generated when a draft is written to the draft group.
1431
1432 @item message-from-style
1433 @vindex message-from-style
1434 Specifies how @code{From} headers should look.  There are four valid
1435 values:
1436
1437 @table @code
1438 @item nil
1439 Just the address---@samp{king@@grassland.com}.
1440
1441 @item parens
1442 @samp{king@@grassland.com (Elvis Parsley)}.
1443
1444 @item angles
1445 @samp{Elvis Parsley <king@@grassland.com>}.
1446
1447 @item default
1448 Look like @code{angles} if that doesn't require quoting, and
1449 @code{parens} if it does.  If even @code{parens} requires quoting, use
1450 @code{angles} anyway.
1451
1452 @end table
1453
1454 @item message-deletable-headers
1455 @vindex message-deletable-headers
1456 Headers in this list that were previously generated by Message will be
1457 deleted before posting.  Let's say you post an article.  Then you decide
1458 to post it again to some other group, you naughty boy, so you jump back
1459 to the @file{*post-buf*} buffer, edit the @code{Newsgroups} line, and
1460 ship it off again.  By default, this variable makes sure that the old
1461 generated @code{Message-ID} is deleted, and a new one generated.  If
1462 this isn't done, the entire empire would probably crumble, anarchy would
1463 prevail, and cats would start walking on two legs and rule the world.
1464 Allegedly.
1465
1466 @item message-default-headers
1467 @vindex message-default-headers
1468 Header lines to be inserted in outgoing messages before you edit the
1469 message, so you can edit or delete their lines. If set to a string, it
1470 is directly inserted. If set to a function, it is called and its
1471 result is inserted.
1472
1473 @item message-subject-re-regexp
1474 @vindex message-subject-re-regexp
1475 @cindex Aw
1476 @cindex Sv
1477 @cindex Re
1478 Responses to messages have subjects that start with @samp{Re: }.  This
1479 is @emph{not} an abbreviation of the English word ``response'', but is
1480 Latin, and means ``in response to''.  Some illiterate nincompoops have
1481 failed to grasp this fact, and have ``internationalized'' their software
1482 to use abominations like @samp{Aw: } (``antwort'') or @samp{Sv: }
1483 (``svar'') instead, which is meaningless and evil.  However, you may
1484 have to deal with users that use these evil tools, in which case you may
1485 set this variable to a regexp that matches these prefixes.  Myself, I
1486 just throw away non-compliant mail.
1487
1488 Here's an example of a value to deal with these headers when
1489 responding to a message:
1490
1491 @lisp
1492 (setq message-subject-re-regexp
1493       (concat
1494        "^[ \t]*"
1495          "\\("
1496            "\\("
1497              "[Aa][Nn][Tt][Ww]\\.?\\|"     ; antw
1498              "[Aa][Ww]\\|"                 ; aw
1499              "[Ff][Ww][Dd]?\\|"            ; fwd
1500              "[Oo][Dd][Pp]\\|"             ; odp
1501              "[Rr][Ee]\\|"                 ; re
1502              "[Rr][\311\351][Ff]\\.?\\|"   ; ref
1503              "[Ss][Vv]"                    ; sv
1504            "\\)"
1505            "\\(\\[[0-9]*\\]\\)"
1506            "*:[ \t]*"
1507          "\\)"
1508        "*[ \t]*"
1509        ))
1510 @end lisp
1511
1512 @item message-subject-trailing-was-query
1513 @vindex message-subject-trailing-was-query
1514 @vindex message-subject-trailing-was-ask-regexp
1515 @vindex message-subject-trailing-was-regexp
1516 Controls what to do with trailing @samp{(was: <old subject>)} in subject
1517 lines.  If @code{nil}, leave the subject unchanged.  If it is the symbol
1518 @code{ask}, query the user what to do.  In this case, the subject is
1519 matched against @code{message-subject-trailing-was-ask-regexp}.  If
1520 @code{message-subject-trailing-was-query} is @code{t}, always strip the
1521 trailing old subject.  In this case,
1522 @code{message-subject-trailing-was-regexp} is used.
1523
1524 @item message-alternative-emails
1525 @vindex message-alternative-emails
1526 Regexp matching alternative email addresses.  The first address in the
1527 To, Cc or From headers of the original article matching this variable is
1528 used as the From field of outgoing messages, replacing the default From
1529 value.
1530
1531 For example, if you have two secondary email addresses john@@home.net
1532 and john.doe@@work.com and want to use them in the From field when
1533 composing a reply to a message addressed to one of them, you could set
1534 this variable like this:
1535
1536 @lisp
1537 (setq message-alternative-emails
1538       (regexp-opt '("john@@home.net" "john.doe@@work.com")))
1539 @end lisp
1540
1541 This variable has precedence over posting styles and anything that runs
1542 off @code{message-setup-hook}.
1543
1544 @item message-allow-no-recipients
1545 @vindex message-allow-no-recipients
1546 Specifies what to do when there are no recipients other than
1547 @code{Gcc} or @code{Fcc}.  If it is @code{always}, the posting is
1548 allowed.  If it is @code{never}, the posting is not allowed.  If it is
1549 @code{ask} (the default), you are prompted.
1550
1551 @item message-hidden-headers
1552 @vindex message-hidden-headers
1553 A regexp, a list of regexps, or a list where the first element is
1554 @code{not} and the rest are regexps.  It says which headers to keep
1555 hidden when composing a message.
1556
1557 @lisp
1558 (setq message-hidden-headers
1559       '(not "From" "Subject" "To" "Cc" "Newsgroups"))
1560 @end lisp
1561
1562 Headers are hidden using narrowing, you can use @kbd{M-x widen} to
1563 expose them in the buffer.
1564
1565 @item message-header-synonyms
1566 @vindex message-header-synonyms
1567 A list of lists of header synonyms.  E.g., if this list contains a
1568 member list with elements @code{Cc} and @code{To}, then
1569 @code{message-carefully-insert-headers} will not insert a @code{To}
1570 header when the message is already @code{Cc}ed to the recipient.
1571
1572 @end table
1573
1574
1575 @node Mail Headers
1576 @section Mail Headers
1577
1578 @table @code
1579 @item message-required-mail-headers
1580 @vindex message-required-mail-headers
1581 @xref{News Headers}, for the syntax of this variable.  It is
1582 @code{(From Subject Date (optional . In-Reply-To) Message-ID
1583 (optional . User-Agent))} by default.
1584
1585 @item message-ignored-mail-headers
1586 @vindex message-ignored-mail-headers
1587 Regexp of headers to be removed before mailing.  The default is@*
1588 @samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@*
1589 ^X-Gnus-Agent-Meta-Information:}.
1590
1591 @item message-default-mail-headers
1592 @vindex message-default-mail-headers
1593 This string is inserted at the end of the headers in all message
1594 buffers that are initialized as mail.
1595
1596 @item message-generate-hashcash
1597 @vindex message-generate-hashcash
1598 Variable that indicates whether @samp{X-Hashcash} headers
1599 should be computed for the message.  @xref{Hashcash, ,Hashcash,gnus,
1600 The Gnus Manual}.  If @code{opportunistic}, only generate the headers
1601 when it doesn't lead to the user having to wait.
1602
1603 @end table
1604
1605
1606 @node Mail Variables
1607 @section Mail Variables
1608
1609 @table @code
1610 @item message-send-mail-function
1611 @vindex message-send-mail-function
1612 @findex message-send-mail-function
1613 @findex message-send-mail-with-sendmail
1614 @findex message-send-mail-with-mh
1615 @findex message-send-mail-with-qmail
1616 @findex message-smtpmail-send-it
1617 @findex smtpmail-send-it
1618 @findex feedmail-send-it
1619 @findex message-send-mail-with-mailclient
1620 Function used to send the current buffer as mail.  The default is
1621 @code{message-send-mail-with-sendmail}, or @code{smtpmail-send-it}
1622 according to the system.  Other valid values include
1623 @code{message-send-mail-with-mailclient},
1624 @code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail},
1625 @code{message-smtpmail-send-it} and @code{feedmail-send-it}.
1626
1627 The function
1628 @code{message-send-mail-with-sendmail} pipes your article to the
1629 @code{sendmail} binary for further queuing and sending.  When your local
1630 system is not configured for sending mail using @code{sendmail}, and you
1631 have access to a remote @acronym{SMTP} server, you can set
1632 @code{message-send-mail-function} to @code{smtpmail-send-it} and make
1633 sure to setup the @code{smtpmail} package correctly.  An example:
1634
1635 @lisp
1636 (setq message-send-mail-function 'smtpmail-send-it
1637       smtpmail-default-smtp-server "YOUR SMTP HOST")
1638 @end lisp
1639
1640 To the thing similar to this, there is
1641 @code{message-smtpmail-send-it}.  It is useful if your @acronym{ISP}
1642 requires the @acronym{POP}-before-@acronym{SMTP} authentication.
1643 @xref{POP before SMTP, , POP before SMTP, gnus, The Gnus Manual}.
1644
1645 @cindex X-Message-SMTP-Method
1646 If you have a complex @acronym{SMTP} setup, and want some messages to
1647 go via one mail server, and other messages to go through another, you
1648 can use the @samp{X-Message-SMTP-Method} header.  These are the
1649 supported values:
1650
1651 @table @samp
1652 @item smtpmail
1653
1654 @example
1655 X-Message-SMTP-Method: smtp smtp.fsf.org 587
1656 @end example
1657
1658 This will send the message via @samp{smtp.fsf.org}, using port 587.
1659
1660 @example
1661 X-Message-SMTP-Method: smtp smtp.fsf.org 587 other-user
1662 @end example
1663
1664 This is the same as the above, but uses @samp{other-user} as the user
1665 name when authenticating.  This is handy if you have several
1666 @acronym{SMTP} accounts on the same server.
1667
1668 @item sendmail
1669
1670 @example
1671 X-Message-SMTP-Method: sendmail
1672 @end example
1673
1674 This will send the message via the locally installed sendmail/exim/etc
1675 installation.
1676
1677 @end table
1678
1679 @item message-mh-deletable-headers
1680 @vindex message-mh-deletable-headers
1681 Most versions of MH doesn't like being fed messages that contain the
1682 headers in this variable.  If this variable is non-@code{nil} (which is
1683 the default), these headers will be removed before mailing when sending
1684 messages via MH@.  Set it to @code{nil} if your MH can handle these
1685 headers.
1686
1687 @item message-qmail-inject-program
1688 @vindex message-qmail-inject-program
1689 @cindex qmail
1690 Location of the qmail-inject program.
1691
1692 @item message-qmail-inject-args
1693 @vindex message-qmail-inject-args
1694 Arguments passed to qmail-inject programs.
1695 This should be a list of strings, one string for each argument.  It
1696 may also be a function.
1697
1698 E.g., if you wish to set the envelope sender address so that bounces
1699 go to the right place or to deal with listserv's usage of that address, you
1700 might set this variable to @code{'("-f" "you@@some.where")}.
1701
1702 @item message-sendmail-f-is-evil
1703 @vindex message-sendmail-f-is-evil
1704 @cindex sendmail
1705 Non-@code{nil} means don't add @samp{-f username} to the sendmail
1706 command line.  Doing so would be even more evil than leaving it out.
1707
1708 @item message-sendmail-envelope-from
1709 @vindex message-sendmail-envelope-from
1710 When @code{message-sendmail-f-is-evil} is @code{nil}, this specifies
1711 the address to use in the @acronym{SMTP} envelope.  If it is
1712 @code{nil}, use @code{user-mail-address}.  If it is the symbol
1713 @code{header}, use the @samp{From} header of the message.
1714
1715 @item message-mailer-swallows-blank-line
1716 @vindex message-mailer-swallows-blank-line
1717 Set this to non-@code{nil} if the system's mailer runs the header and
1718 body together.  (This problem exists on SunOS 4 when sendmail is run
1719 in remote mode.)  The value should be an expression to test whether
1720 the problem will actually occur.
1721
1722 @item message-send-mail-partially-limit
1723 @vindex message-send-mail-partially-limit
1724 @cindex split large message
1725 The limitation of messages sent as message/partial.  The lower bound
1726 of message size in characters, beyond which the message should be sent
1727 in several parts.  If it is @code{nil} (which is the default), the
1728 size is unlimited.
1729
1730 @end table
1731
1732
1733 @node News Headers
1734 @section News Headers
1735
1736 @vindex message-required-news-headers
1737 @code{message-required-news-headers} a list of header symbols.  These
1738 headers will either be automatically generated, or, if that's
1739 impossible, they will be prompted for.  The following symbols are valid:
1740
1741 @table @code
1742
1743 @item From
1744 @cindex From
1745 @findex user-full-name
1746 @findex user-mail-address
1747 This required header will be filled out with the result of the
1748 @code{message-make-from} function, which depends on the
1749 @code{message-from-style}, @code{user-full-name},
1750 @code{user-mail-address} variables.
1751
1752 @item Subject
1753 @cindex Subject
1754 This required header will be prompted for if not present already.
1755
1756 @item Newsgroups
1757 @cindex Newsgroups
1758 This required header says which newsgroups the article is to be posted
1759 to.  If it isn't present already, it will be prompted for.
1760
1761 @item Organization
1762 @cindex organization
1763 @vindex message-user-organization
1764 @vindex message-user-organization-file
1765 This optional header will be filled out depending on the
1766 @code{message-user-organization} variable.
1767 @code{message-user-organization-file} will be used if this variable is
1768 @code{t}.  This variable can also be a string (in which case this string
1769 will be used), or it can be a function (which will be called with no
1770 parameters and should return a string to be used).
1771
1772 @item Lines
1773 @cindex Lines
1774 This optional header will be computed by Message.
1775
1776 @item Message-ID
1777 @cindex Message-ID
1778 @vindex message-user-fqdn
1779 @vindex mail-host-address
1780 @vindex user-mail-address
1781 @findex system-name
1782 @cindex Sun
1783 @cindex i-did-not-set--mail-host-address--so-tickle-me
1784 This required header will be generated by Message.  A unique ID will be
1785 created based on the date, time, user name (for the local part) and the
1786 domain part.  For the domain part, message will look (in this order) at
1787 @code{message-user-fqdn}, @code{system-name}, @code{mail-host-address}
1788 and @code{message-user-mail-address} (i.e., @code{user-mail-address})
1789 until a probably valid fully qualified domain name (FQDN) was found.
1790
1791 @item User-Agent
1792 @cindex User-Agent
1793 This optional header will be filled out according to the
1794 @code{message-newsreader} local variable.
1795
1796 @item In-Reply-To
1797 This optional header is filled out using the @code{Date} and @code{From}
1798 header of the article being replied to.
1799
1800 @item Expires
1801 @cindex Expires
1802 @vindex message-expires
1803 This extremely optional header will be inserted according to the
1804 @code{message-expires} variable.  It is highly deprecated and shouldn't
1805 be used unless you know what you're doing.
1806
1807 @item Distribution
1808 @cindex Distribution
1809 @vindex message-distribution-function
1810 This optional header is filled out according to the
1811 @code{message-distribution-function} variable.  It is a deprecated and
1812 much misunderstood header.
1813
1814 @item Path
1815 @cindex path
1816 @vindex message-user-path
1817 This extremely optional header should probably never be used.
1818 However, some @emph{very} old servers require that this header is
1819 present.  @code{message-user-path} further controls how this
1820 @code{Path} header is to look.  If it is @code{nil}, use the server name
1821 as the leaf node.  If it is a string, use the string.  If it is neither
1822 a string nor @code{nil}, use the user name only.  However, it is highly
1823 unlikely that you should need to fiddle with this variable at all.
1824 @end table
1825
1826 @cindex Mime-Version
1827 In addition, you can enter conses into this list.  The @sc{car} of this cons
1828 should be a symbol.  This symbol's name is the name of the header, and
1829 the @sc{cdr} can either be a string to be entered verbatim as the value of
1830 this header, or it can be a function to be called.  This function should
1831 take no arguments, and return a string to be inserted.  For
1832 instance, if you want to insert @code{Mime-Version: 1.0}, you should
1833 enter @code{(Mime-Version . "1.0")} into the list.
1834
1835 If the list contains a cons where the @sc{car} of the cons is
1836 @code{optional}, the @sc{cdr} of this cons will only be inserted if it is
1837 non-@code{nil}.
1838
1839 If you want to delete an entry from this list, the following Lisp
1840 snippet might be useful.  Adjust accordingly if you want to remove
1841 another element.
1842
1843 @lisp
1844 (setq message-required-news-headers
1845       (delq 'Message-ID message-required-news-headers))
1846 @end lisp
1847
1848 Other variables for customizing outgoing news articles:
1849
1850 @table @code
1851
1852 @item message-syntax-checks
1853 @vindex message-syntax-checks
1854 Controls what syntax checks should not be performed on outgoing posts.
1855 To disable checking of long signatures, for instance, add
1856
1857 @lisp
1858 (signature . disabled)
1859 @end lisp
1860
1861 to this list.
1862
1863 Valid checks are:
1864
1865 @table @code
1866 @item approved
1867 @cindex approved
1868 Check whether the article has an @code{Approved} header, which is
1869 something only moderators should include.
1870 @item continuation-headers
1871 Check whether there are continuation header lines that don't begin with
1872 whitespace.
1873 @item control-chars
1874 Check for invalid characters.
1875 @item empty
1876 Check whether the article is empty.
1877 @item existing-newsgroups
1878 Check whether the newsgroups mentioned in the @code{Newsgroups} and
1879 @code{Followup-To} headers exist.
1880 @item from
1881 Check whether the @code{From} header seems nice.
1882 @item illegible-text
1883 Check whether there is any non-printable character in the body.
1884 @item invisible-text
1885 Check whether there is any invisible text in the buffer.
1886 @item long-header-lines
1887 Check for too long header lines.
1888 @item long-lines
1889 @cindex long lines
1890 Check for too long lines in the body.
1891 @item message-id
1892 Check whether the @code{Message-ID} looks syntactically ok.
1893 @item multiple-headers
1894 Check for the existence of multiple equal headers.
1895 @item new-text
1896 Check whether there is any new text in the messages.
1897 @item newsgroups
1898 Check whether the @code{Newsgroups} header exists and is not empty.
1899 @item quoting-style
1900 Check whether text follows last quoted portion.
1901 @item repeated-newsgroups
1902 Check whether the @code{Newsgroups} and @code{Followup-to} headers
1903 contains repeated group names.
1904 @item reply-to
1905 Check whether the @code{Reply-To} header looks ok.
1906 @item sender
1907 @cindex Sender
1908 Insert a new @code{Sender} header if the @code{From} header looks odd.
1909 @item sendsys
1910 @cindex sendsys
1911 Check for the existence of version and sendsys commands.
1912 @item shoot
1913 Check whether the domain part of the @code{Message-ID} header looks ok.
1914 @item shorten-followup-to
1915 Check whether to add a @code{Followup-to} header to shorten the number
1916 of groups to post to.
1917 @item signature
1918 Check the length of the signature.
1919 @item size
1920 Check for excessive size.
1921 @item subject
1922 Check whether the @code{Subject} header exists and is not empty.
1923 @item subject-cmsg
1924 Check the subject for commands.
1925 @item valid-newsgroups
1926 Check whether the @code{Newsgroups} and @code{Followup-to} headers
1927 are valid syntactically.
1928 @end table
1929
1930 All these conditions are checked by default, except for @code{sender}
1931 for which the check is disabled by default if
1932 @code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}).
1933
1934 @item message-ignored-news-headers
1935 @vindex message-ignored-news-headers
1936 Regexp of headers to be removed before posting.  The default is@*
1937 @samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@*
1938 ^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}.
1939
1940 @item message-default-news-headers
1941 @vindex message-default-news-headers
1942 This string is inserted at the end of the headers in all message
1943 buffers that are initialized as news.
1944
1945 @end table
1946
1947
1948 @node News Variables
1949 @section News Variables
1950
1951 @table @code
1952 @item message-send-news-function
1953 @vindex message-send-news-function
1954 Function used to send the current buffer as news.  The default is
1955 @code{message-send-news}.
1956
1957 @item message-post-method
1958 @vindex message-post-method
1959 Gnusish @dfn{select method} (see the Gnus manual for details) used for
1960 posting a prepared news message.
1961
1962 @end table
1963
1964
1965 @node Insertion Variables
1966 @section Insertion Variables
1967
1968 @table @code
1969 @item message-cite-style
1970 @vindex message-cite-style
1971 The overall style to be used when replying to messages. This controls
1972 things like where the reply should be put relative to the original,
1973 how the citation is formatted, where the signature goes, etc.
1974
1975 Value is either @code{nil} (no variable overrides) or a let-style list
1976 of pairs @code{(VARIABLE VALUE)} to override default values.
1977
1978 See @code{gnus-posting-styles} to set this variable for specific
1979 groups. Presets to impersonate popular mail agents are available in the
1980 @code{message-cite-style-*} variables.
1981
1982 @item message-cite-reply-position
1983 @vindex message-cite-reply-position
1984 Where the reply should be positioned. Available styles are
1985 @code{traditional} to reply inline, @code{above} for top-posting, and
1986 @code{below} for bottom-posting
1987
1988 @item message-ignored-cited-headers
1989 @vindex message-ignored-cited-headers
1990 All headers that match this regexp will be removed from yanked
1991 messages.  The default is @samp{.}, which means that all headers will be
1992 removed.
1993
1994 @item message-cite-prefix-regexp
1995 @vindex message-cite-prefix-regexp
1996 Regexp matching the longest possible citation prefix on a line.
1997
1998 @item message-citation-line-function
1999 @vindex message-citation-line-function
2000 @cindex attribution line
2001 Function called to insert the citation line.  The default is
2002 @code{message-insert-citation-line}, which will lead to citation lines
2003 that look like:
2004
2005 @example
2006 Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
2007 @end example
2008
2009 @c FIXME: Add 'message-insert-formatted-citation-line' and
2010 @c 'message-citation-line-format'.
2011
2012 Point will be at the beginning of the body of the message when this
2013 function is called.
2014
2015 Note that Gnus provides a feature where clicking on @samp{writes:} hides the
2016 cited text.  If you change the citation line too much, readers of your
2017 messages will have to adjust their Gnus, too.  See the variable
2018 @code{gnus-cite-attribution-suffix}.  @xref{Article Highlighting, ,
2019 Article Highlighting, gnus, The Gnus Manual}, for details.
2020
2021 @item message-yank-prefix
2022 @vindex message-yank-prefix
2023 @cindex yanking
2024 @cindex quoting
2025 When you are replying to or following up an article, you normally want
2026 to quote the person you are answering.  Inserting quoted text is done by
2027 @dfn{yanking}, and each line you yank will have
2028 @code{message-yank-prefix} prepended to it (except for quoted lines
2029 which use @code{message-yank-cited-prefix} and empty lines which use
2030 @code{message-yank-empty-prefix}).  The default is @samp{> }.
2031
2032 @item message-yank-cited-prefix
2033 @vindex message-yank-cited-prefix
2034 @cindex yanking
2035 @cindex cited
2036 @cindex quoting
2037 When yanking text from an article which contains already cited text,
2038 each line will be prefixed with the contents of this variable.  The
2039 default is @samp{>}.  See also @code{message-yank-prefix}.
2040
2041 @item message-yank-empty-prefix
2042 @vindex message-yank-empty-prefix
2043 @cindex yanking
2044 @cindex quoting
2045 When yanking text from an article, each empty line will be prefixed with
2046 the contents of this variable.  The default is @samp{>}.  You can set
2047 this variable to an empty string to split the cited text into paragraphs
2048 automatically.  See also @code{message-yank-prefix}.
2049
2050 @item message-indentation-spaces
2051 @vindex message-indentation-spaces
2052 Number of spaces to indent yanked messages.
2053
2054 @item message-cite-function
2055 @vindex message-cite-function
2056 @findex message-cite-original
2057 @findex message-cite-original-without-signature
2058 Function for citing an original message.  The default is
2059 @code{message-cite-original}, which simply inserts the original message
2060 and prepends @samp{> } to each line.
2061 @code{message-cite-original-without-signature} does the same, but elides
2062 the signature.
2063
2064 @item message-indent-citation-function
2065 @vindex message-indent-citation-function
2066 Function for modifying a citation just inserted in the mail buffer.
2067 This can also be a list of functions.  Each function can find the
2068 citation between @code{(point)} and @code{(mark t)}.  And each function
2069 should leave point and mark around the citation text as modified.
2070
2071 @item message-mark-insert-begin
2072 @vindex message-mark-insert-begin
2073 String to mark the beginning of some inserted text.
2074
2075 @item message-mark-insert-end
2076 @vindex message-mark-insert-end
2077 String to mark the end of some inserted text.
2078
2079 @item message-signature
2080 @vindex message-signature
2081 String to be inserted at the end of the message buffer.  If @code{t}
2082 (which is the default), the @code{message-signature-file} file will be
2083 inserted instead.  If a function, the result from the function will be
2084 used instead.  If a form, the result from the form will be used instead.
2085 If this variable is @code{nil}, no signature will be inserted at all.
2086
2087 @item message-signature-file
2088 @vindex message-signature-file
2089 File containing the signature to be inserted at the end of the buffer.
2090 If a path is specified, the value of
2091 @code{message-signature-directory} is ignored, even if set.
2092 The default is @file{~/.signature}.
2093
2094 @item message-signature-directory
2095 @vindex message-signature-directory
2096 Name of directory containing signature files.  Comes in handy if you
2097 have many such files, handled via Gnus posting styles for instance.
2098 If @code{nil} (the default), @code{message-signature-file} is expected
2099 to specify the directory if needed.
2100
2101
2102 @item message-signature-insert-empty-line
2103 @vindex message-signature-insert-empty-line
2104 If @code{t} (the default value) an empty line is inserted before the
2105 signature separator.
2106
2107 @end table
2108
2109 Note that RFC1036bis says that a signature should be preceded by the three
2110 characters @samp{-- } on a line by themselves.  This is to make it
2111 easier for the recipient to automatically recognize and process the
2112 signature.  So don't remove those characters, even though you might feel
2113 that they ruin your beautiful design, like, totally.
2114
2115 Also note that no signature should be more than four lines long.
2116 Including @acronym{ASCII} graphics is an efficient way to get
2117 everybody to believe that you are silly and have nothing important to
2118 say.
2119
2120
2121 @node Various Message Variables
2122 @section Various Message Variables
2123
2124 @table @code
2125 @item message-default-charset
2126 @vindex message-default-charset
2127 @cindex charset
2128 Symbol naming a @acronym{MIME} charset.  Non-@acronym{ASCII} characters
2129 in messages are assumed to be encoded using this charset.  The default
2130 is @code{iso-8859-1} on non-@sc{mule} Emacsen; otherwise @code{nil},
2131 which means ask the user.  (This variable is used only on non-@sc{mule}
2132 Emacsen.)  @xref{Charset Translation, , Charset Translation, emacs-mime,
2133 Emacs MIME Manual}, for details on the @sc{mule}-to-@acronym{MIME}
2134 translation process.
2135
2136 @item message-fill-column
2137 @vindex message-fill-column
2138 @cindex auto-fill
2139 Local value for the column beyond which automatic line-wrapping should
2140 happen for message buffers.  If non-@code{nil} (the default), also turn on
2141 auto-fill in message buffers.
2142
2143 @item message-signature-separator
2144 @vindex message-signature-separator
2145 Regexp matching the signature separator.  It is @samp{^-- *$} by
2146 default.
2147
2148 @item mail-header-separator
2149 @vindex mail-header-separator
2150 String used to separate the headers from the body.  It is @samp{--text
2151 follows this line--} by default.
2152
2153 @item message-directory
2154 @vindex message-directory
2155 Directory used by many mailish things.  The default is @file{~/Mail/}.
2156 All other mail file variables are derived from @code{message-directory}.
2157
2158 @item message-auto-save-directory
2159 @vindex message-auto-save-directory
2160 Directory where Message auto-saves buffers if Gnus isn't running.  If
2161 @code{nil}, Message won't auto-save.  The default is @file{~/Mail/drafts/}.
2162
2163 @item message-signature-setup-hook
2164 @vindex message-signature-setup-hook
2165 Hook run when initializing the message buffer.  It is run after the
2166 headers have been inserted but before the signature has been inserted.
2167
2168 @item message-setup-hook
2169 @vindex message-setup-hook
2170 Hook run as the last thing when the message buffer has been initialized,
2171 but before yanked text is inserted.
2172
2173 @item message-header-setup-hook
2174 @vindex message-header-setup-hook
2175 Hook called narrowed to the headers after initializing the headers.
2176
2177 For instance, if you're running Gnus and wish to insert a
2178 @samp{Mail-Copies-To} header in all your news articles and all messages
2179 you send to mailing lists, you could do something like the following:
2180
2181 @lisp
2182 (defun my-message-header-setup-hook ()
2183   (let ((group (or gnus-newsgroup-name "")))
2184     (when (or (message-fetch-field "newsgroups")
2185               (gnus-group-find-parameter group 'to-address)
2186               (gnus-group-find-parameter group 'to-list))
2187       (insert "Mail-Copies-To: never\n"))))
2188
2189 (add-hook 'message-header-setup-hook
2190           'my-message-header-setup-hook)
2191 @end lisp
2192
2193 @item message-send-hook
2194 @vindex message-send-hook
2195 Hook run before sending messages.
2196
2197 If you want to add certain headers before sending, you can use the
2198 @code{message-add-header} function in this hook.  For instance:
2199 @findex message-add-header
2200
2201 @lisp
2202 (add-hook 'message-send-hook 'my-message-add-content)
2203 (defun my-message-add-content ()
2204   (message-add-header "X-In-No-Sense: Nonsense")
2205   (message-add-header "X-Whatever: no"))
2206 @end lisp
2207
2208 This function won't add the header if the header is already present.
2209
2210 @item message-send-mail-hook
2211 @vindex message-send-mail-hook
2212 Hook run before sending mail messages.  This hook is run very late:
2213 just before the message is actually sent as mail.
2214
2215 @item message-send-news-hook
2216 @vindex message-send-news-hook
2217 Hook run before sending news messages.  This hook is run very late:
2218 just before the message is actually sent as news.
2219
2220 @item message-sent-hook
2221 @vindex message-sent-hook
2222 Hook run after sending messages.
2223
2224 @item message-cancel-hook
2225 @vindex message-cancel-hook
2226 Hook run when canceling news articles.
2227
2228 @item message-mode-syntax-table
2229 @vindex message-mode-syntax-table
2230 Syntax table used in message mode buffers.
2231
2232 @item message-cite-articles-with-x-no-archive
2233 @vindex message-cite-articles-with-x-no-archive
2234 If non-@code{nil}, don't strip quoted text from articles that have
2235 @samp{X-No-Archive} set.  Even if this variable isn't set, you can
2236 undo the stripping by hitting the @code{undo} keystroke.
2237
2238 @item message-strip-special-text-properties
2239 @vindex message-strip-special-text-properties
2240 Emacs has a number of special text properties which can break message
2241 composing in various ways.  If this option is set, message will strip
2242 these properties from the message composition buffer.  However, some
2243 packages requires these properties to be present in order to work.  If
2244 you use one of these packages, turn this option off, and hope the
2245 message composition doesn't break too bad.
2246
2247 @item message-send-method-alist
2248 @vindex message-send-method-alist
2249 @findex message-mail-p
2250 @findex message-news-p
2251 @findex message-send-via-mail
2252 @findex message-send-via-news
2253 Alist of ways to send outgoing messages.  Each element has the form:
2254
2255 @lisp
2256 (@var{type} @var{predicate} @var{function})
2257 @end lisp
2258
2259 @table @var
2260 @item type
2261 A symbol that names the method.
2262
2263 @item predicate
2264 A function called without any parameters to determine whether the
2265 message is a message of type @var{type}.  The function will be called in
2266 the buffer where the message is.
2267
2268 @item function
2269 A function to be called if @var{predicate} returns non-@code{nil}.
2270 @var{function} is called with one parameter---the prefix.
2271 @end table
2272
2273 The default is:
2274
2275 @lisp
2276 ((news message-news-p message-send-via-news)
2277  (mail message-mail-p message-send-via-mail))
2278 @end lisp
2279
2280 The @code{message-news-p} function returns non-@code{nil} if the message
2281 looks like news, and the @code{message-send-via-news} function sends the
2282 message according to the @code{message-send-news-function} variable
2283 (@pxref{News Variables}).  The @code{message-mail-p} function returns
2284 non-@code{nil} if the message looks like mail, and the
2285 @code{message-send-via-mail} function sends the message according to the
2286 @code{message-send-mail-function} variable (@pxref{Mail Variables}).
2287
2288 All the elements in this alist will be tried in order, so a message
2289 containing both a valid @samp{Newsgroups} header and a valid @samp{To}
2290 header, for example, will be sent as news, and then as mail.
2291 @end table
2292
2293
2294
2295 @node Sending Variables
2296 @section Sending Variables
2297
2298 @table @code
2299
2300 @item message-fcc-handler-function
2301 @vindex message-fcc-handler-function
2302 A function called to save outgoing articles.  This function will be
2303 called with the name of the file to store the article in.  The default
2304 function is @code{message-output} which saves in Unix mailbox format.
2305
2306 @item message-courtesy-message
2307 @vindex message-courtesy-message
2308 When sending combined messages, this string is inserted at the start of
2309 the mailed copy.  If the string contains the format spec @samp{%s}, the
2310 newsgroups the article has been posted to will be inserted there.  If
2311 this variable is @code{nil}, no such courtesy message will be added.
2312 The default value is @samp{"The following message is a courtesy copy of
2313 an article\\nthat has been posted to %s as well.\\n\\n"}.
2314
2315 @item message-fcc-externalize-attachments
2316 @vindex message-fcc-externalize-attachments
2317 If @code{nil}, attach files as normal parts in Fcc copies; if it is
2318 non-@code{nil}, attach local files as external parts.
2319
2320 @item message-interactive
2321 @vindex message-interactive
2322 If non-@code{nil} wait for and display errors when sending a message;
2323 if @code{nil} let the mailer mail back a message to report errors.
2324
2325 @item message-confirm-send
2326 @vindex message-confirm-send
2327 When non-@code{nil}, Gnus will ask for confirmation when sending a
2328 message.
2329
2330 @end table
2331
2332
2333 @node Message Buffers
2334 @section Message Buffers
2335
2336 Message will generate new buffers with unique buffer names when you
2337 request a message buffer.  When you send the message, the buffer isn't
2338 normally killed off.  Its name is changed and a certain number of old
2339 message buffers are kept alive.
2340
2341 @table @code
2342 @item message-generate-new-buffers
2343 @vindex message-generate-new-buffers
2344 Controls whether to create a new message buffer to compose a message.
2345 Valid values include:
2346
2347 @table @code
2348 @item nil
2349 Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail
2350 to whom*, *news on group*, etc.)@: and continue editing in the existing
2351 buffer of that name.  If there is no such buffer, it will be newly
2352 created.
2353
2354 @item unique
2355 @item t
2356 Create the new buffer with the name generated in the Message way.
2357
2358 @item unsent
2359 Similar to @code{unique} but the buffer name begins with "*unsent ".
2360
2361 @item standard
2362 Similar to @code{nil} but the buffer name is simpler like *mail
2363 message*.
2364 @end table
2365 @table @var
2366 @item function
2367 If this is a function, call that function with three parameters: The
2368 type, the To address and the group name (any of these may be
2369 @code{nil}).  The function should return the new buffer name.
2370 @end table
2371
2372 The default value is @code{unsent}.
2373
2374 @item message-max-buffers
2375 @vindex message-max-buffers
2376 This variable says how many old message buffers to keep.  If there are
2377 more message buffers than this, the oldest buffer will be killed.  The
2378 default is 10.  If this variable is @code{nil}, no old message buffers
2379 will ever be killed.
2380
2381 @item message-send-rename-function
2382 @vindex message-send-rename-function
2383 After sending a message, the buffer is renamed from, for instance,
2384 @samp{*reply to Lars*} to @samp{*sent reply to Lars*}.  If you don't
2385 like this, set this variable to a function that renames the buffer in a
2386 manner you like.  If you don't want to rename the buffer at all, you can
2387 say:
2388
2389 @lisp
2390 (setq message-send-rename-function 'ignore)
2391 @end lisp
2392
2393 @item message-kill-buffer-on-exit
2394 @findex message-kill-buffer-on-exit
2395 If non-@code{nil}, kill the buffer immediately on exit.
2396
2397 @end table
2398
2399
2400 @node Message Actions
2401 @section Message Actions
2402
2403 When Message is being used from a news/mail reader, the reader is likely
2404 to want to perform some task after the message has been sent.  Perhaps
2405 return to the previous window configuration or mark an article as
2406 replied.
2407
2408 @vindex message-kill-actions
2409 @vindex message-postpone-actions
2410 @vindex message-exit-actions
2411 @vindex message-send-actions
2412 The user may exit from the message buffer in various ways.  The most
2413 common is @kbd{C-c C-c}, which sends the message and exits.  Other
2414 possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c
2415 C-d} which postpones the message editing and buries the message buffer,
2416 and @kbd{C-c C-k} which kills the message buffer.  Each of these actions
2417 have lists associated with them that contains actions to be executed:
2418 @code{message-send-actions}, @code{message-exit-actions},
2419 @code{message-postpone-actions}, and @code{message-kill-actions}.
2420
2421 Message provides a function to interface with these lists:
2422 @code{message-add-action}.  The first parameter is the action to be
2423 added, and the rest of the arguments are which lists to add this action
2424 to.  Here's an example from Gnus:
2425
2426 @lisp
2427   (message-add-action
2428    `(set-window-configuration ,(current-window-configuration))
2429    'exit 'postpone 'kill)
2430 @end lisp
2431
2432 This restores the Gnus window configuration when the message buffer is
2433 killed, postponed or exited.
2434
2435 An @dfn{action} can be either: a normal function, or a list where the
2436 @sc{car} is a function and the @sc{cdr} is the list of arguments, or
2437 a form to be @code{eval}ed.
2438
2439
2440 @node Compatibility
2441 @chapter Compatibility
2442 @cindex compatibility
2443
2444 Message uses virtually only its own variables---older @code{mail-}
2445 variables aren't consulted.  To force Message to take those variables
2446 into account, you can put the following in your @file{.emacs} file:
2447
2448 @lisp
2449 (require 'messcompat)
2450 @end lisp
2451
2452 This will initialize many Message variables from the values in the
2453 corresponding mail variables.
2454
2455
2456 @node Appendices
2457 @chapter Appendices
2458
2459 @menu
2460 * Responses::          Standard rules for determining where responses go.
2461 @end menu
2462
2463
2464 @node Responses
2465 @section Responses
2466
2467 To determine where a message is to go, the following algorithm is used
2468 by default.
2469
2470 @table @dfn
2471 @item reply
2472 A @dfn{reply} is when you want to respond @emph{just} to the person who
2473 sent the message via mail.  There will only be one recipient.  To
2474 determine who the recipient will be, the following headers are
2475 consulted, in turn:
2476
2477 @table @code
2478 @item Reply-To
2479
2480 @item From
2481 @end table
2482
2483
2484 @item wide reply
2485 A @dfn{wide reply} is a mail response that includes @emph{all} entities
2486 mentioned in the message you are responding to.  All mailboxes from the
2487 following headers will be concatenated to form the outgoing
2488 @code{To}/@code{Cc} headers:
2489
2490 @table @code
2491 @item From
2492 (unless there's a @code{Reply-To}, in which case that is used instead).
2493
2494 @item Cc
2495
2496 @item To
2497 @end table
2498
2499 If a @code{Mail-Copies-To} header is present, it will also be included
2500 in the list of mailboxes.  If this header is @samp{never}, that means
2501 that the @code{From} (or @code{Reply-To}) mailbox will be suppressed.
2502
2503
2504 @item followup
2505 A @dfn{followup} is a response sent via news.  The following headers
2506 (listed in order of precedence) determine where the response is to be
2507 sent:
2508
2509 @table @code
2510
2511 @item Followup-To
2512
2513 @item Newsgroups
2514
2515 @end table
2516
2517 If a @code{Mail-Copies-To} header is present, it will be used as the
2518 basis of the new @code{Cc} header, except if this header is
2519 @samp{never}.
2520
2521 @end table
2522
2523
2524 @node GNU Free Documentation License
2525 @chapter GNU Free Documentation License
2526 @include doclicense.texi
2527
2528 @node Index
2529 @chapter Index
2530 @printindex cp
2531
2532 @node Key Index
2533 @chapter Key Index
2534 @printindex ky
2535
2536 @bye
2537
2538 @c End: