(filter-buffer-substring): Fix typo in docstring.
[emacs.git] / man / rmail.texi
blob091d1e60b745139578459e9b86f37e73d5c95367
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,1997,2001 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Rmail, Dired, Sending Mail, Top
5 @chapter Reading Mail with Rmail
6 @cindex Rmail
7 @cindex reading mail
8 @findex rmail
9 @findex rmail-mode
10 @vindex rmail-mode-hook
12   Rmail is an Emacs subsystem for reading and disposing of mail that you
13 receive.  Rmail stores mail messages in files called Rmail files.
14 Reading the message in an Rmail file is done in a special major mode,
15 Rmail mode, which redefines most letters to run commands for managing
16 mail.  The command @code{rmail-mode} is used to switch into Rmail mode,
17 and it runs the hook @code{rmail-mode-hook} as usual, but don't run this
18 command by hand; it can't do a reasonable job unless the buffer is
19 visiting a proper Rmail file.
21 @menu
22 * Basic: Rmail Basics.       Basic concepts of Rmail, and simple use.
23 * Scroll: Rmail Scrolling.   Scrolling through a message.
24 * Motion: Rmail Motion.      Moving to another message.
25 * Deletion: Rmail Deletion.  Deleting and expunging messages.
26 * Inbox: Rmail Inbox.        How mail gets into the Rmail file.
27 * Files: Rmail Files.        Using multiple Rmail files.
28 * Output: Rmail Output.      Copying message out to files.
29 * Labels: Rmail Labels.      Classifying messages by labeling them.
30 * Attrs: Rmail Attributes.   Certain standard labels, called attributes.
31 * Reply: Rmail Reply.        Sending replies to messages you are viewing.
32 * Summary: Rmail Summary.    Summaries show brief info on many messages.
33 * Sort: Rmail Sorting.       Sorting messages in Rmail.
34 * Display: Rmail Display.    How Rmail displays a message; customization.
35 * Coding: Rmail Coding.      How Rmail handles decoding character sets.
36 * Editing: Rmail Editing.    Editing message text and headers in Rmail.
37 * Digest: Rmail Digest.      Extracting the messages from a digest message.
38 * Out of Rmail::             Converting an Rmail file to mailbox format.
39 * Rot13: Rmail Rot13.        Reading messages encoded in the rot13 code.
40 * Movemail::                 More details of fetching new mail.
41 * Remote Mailboxes::         Retrieving Mail from Remote Mailboxes.
42 * Other Mailbox Formats::    Retrieving Mail from Local Mailboxes in
43                              Various Formats
44 @end menu
46 @node Rmail Basics
47 @section Basic Concepts of Rmail
49 @cindex primary Rmail file
50 @vindex rmail-file-name
51   Using Rmail in the simplest fashion, you have one Rmail file
52 @file{~/RMAIL} in which all of your mail is saved.  It is called your
53 @dfn{primary Rmail file}.  The command @kbd{M-x rmail} reads your primary
54 Rmail file, merges new mail in from your inboxes, displays the first
55 message you haven't read yet, and lets you begin reading.  The variable
56 @code{rmail-file-name} specifies the name of the primary Rmail file.
58   Rmail uses narrowing to hide all but one message in the Rmail file.
59 The message that is shown is called the @dfn{current message}.  Rmail
60 mode's special commands can do such things as delete the current
61 message, copy it into another file, send a reply, or move to another
62 message.  You can also create multiple Rmail files and use Rmail to move
63 messages between them.
65 @cindex message number
66   Within the Rmail file, messages are normally arranged sequentially in
67 order of receipt; you can specify other ways to sort them.  Messages are
68 assigned consecutive integers as their @dfn{message numbers}.  The
69 number of the current message is displayed in Rmail's mode line,
70 followed by the total number of messages in the file.  You can move to a
71 message by specifying its message number with the @kbd{j} key
72 (@pxref{Rmail Motion}).
74 @kindex s @r{(Rmail)}
75 @findex rmail-expunge-and-save
76   Following the usual conventions of Emacs, changes in an Rmail file
77 become permanent only when the file is saved.  You can save it with
78 @kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
79 messages from the file first (@pxref{Rmail Deletion}).  To save the
80 file without expunging, use @kbd{C-x C-s}.  Rmail also saves the Rmail
81 file after merging new mail from an inbox file (@pxref{Rmail Inbox}).
83 @kindex q @r{(Rmail)}
84 @findex rmail-quit
85 @kindex b @r{(Rmail)}
86 @findex rmail-bury
87   You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
88 and saves the Rmail file, then buries the Rmail buffer as well as its
89 summary buffer, if present (@pxref{Rmail Summary}).  But there is no
90 need to ``exit'' formally.  If you switch from Rmail to editing in
91 other buffers, and never happen to switch back, you have exited.  Just
92 make sure to save the Rmail file eventually (like any other file you
93 have changed).  @kbd{C-x s} is a good enough way to do this
94 (@pxref{Saving}).  The Rmail command @kbd{b}, @code{rmail-bury},
95 buries the Rmail buffer and its summary buffer without expunging and
96 saving the Rmail file.
98 @node Rmail Scrolling
99 @section Scrolling Within a Message
101   When Rmail displays a message that does not fit on the screen, you
102 must scroll through it to read the rest.  You could do this with
103 @kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
104 frequent that it deserves to be easier to type.
106 @table @kbd
107 @item @key{SPC}
108 Scroll forward (@code{scroll-up}).
109 @item @key{DEL}
110 Scroll backward (@code{scroll-down}).
111 @item .
112 Scroll to start of message (@code{rmail-beginning-of-message}).
113 @end table
115 @kindex SPC @r{(Rmail)}
116 @kindex DEL @r{(Rmail)}
117   Since the most common thing to do while reading a message is to scroll
118 through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
119 @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
121 @kindex . @r{(Rmail)}
122 @findex rmail-beginning-of-message
123   The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
124 beginning of the selected message.  This is not quite the same as @kbd{M-<}:
125 for one thing, it does not set the mark; for another, it resets the buffer
126 boundaries to the current message if you have changed them.
128 @node Rmail Motion
129 @section Moving Among Messages
131   The most basic thing to do with a message is to read it.  The way to
132 do this in Rmail is to make the message current.  The usual practice is
133 to move sequentially through the file, since this is the order of
134 receipt of messages.  When you enter Rmail, you are positioned at the
135 first message that you have not yet made current (that is, the first one
136 that has the @samp{unseen} attribute; @pxref{Rmail Attributes}).  Move
137 forward to see the other new messages; move backward to re-examine old
138 messages.
140 @table @kbd
141 @item n
142 Move to the next nondeleted message, skipping any intervening deleted
143 messages (@code{rmail-next-undeleted-message}).
144 @item p
145 Move to the previous nondeleted message
146 (@code{rmail-previous-undeleted-message}).
147 @item M-n
148 Move to the next message, including deleted messages
149 (@code{rmail-next-message}).
150 @item M-p
151 Move to the previous message, including deleted messages
152 (@code{rmail-previous-message}).
153 @item j
154 Move to the first message.  With argument @var{n}, move to
155 message number @var{n} (@code{rmail-show-message}).
156 @item >
157 Move to the last message (@code{rmail-last-message}).
158 @item <
159 Move to the first message (@code{rmail-first-message}).
161 @item M-s @var{regexp} @key{RET}
162 Move to the next message containing a match for @var{regexp}
163 (@code{rmail-search}).
165 @item - M-s @var{regexp} @key{RET}
166 Move to the previous message containing a match for @var{regexp}.
167 @end table
169 @kindex n @r{(Rmail)}
170 @kindex p @r{(Rmail)}
171 @kindex M-n @r{(Rmail)}
172 @kindex M-p @r{(Rmail)}
173 @findex rmail-next-undeleted-message
174 @findex rmail-previous-undeleted-message
175 @findex rmail-next-message
176 @findex rmail-previous-message
177   @kbd{n} and @kbd{p} are the usual way of moving among messages in
178 Rmail.  They move through the messages sequentially, but skip over
179 deleted messages, which is usually what you want to do.  Their command
180 definitions are named @code{rmail-next-undeleted-message} and
181 @code{rmail-previous-undeleted-message}.  If you do not want to skip
182 deleted messages---for example, if you want to move to a message to
183 undelete it---use the variants @kbd{M-n} and @kbd{M-p}
184 (@code{rmail-next-message} and @code{rmail-previous-message}).  A
185 numeric argument to any of these commands serves as a repeat
186 count.@refill
188   In Rmail, you can specify a numeric argument by typing just the
189 digits.  You don't need to type @kbd{C-u} first.
191 @kindex M-s @r{(Rmail)}
192 @findex rmail-search
193 @cindex searching in Rmail
194   The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of
195 search.  The usual incremental search command @kbd{C-s} works in Rmail,
196 but it searches only within the current message.  The purpose of
197 @kbd{M-s} is to search for another message.  It reads a regular
198 expression (@pxref{Regexps}) nonincrementally, then searches starting at
199 the beginning of the following message for a match.  It then selects
200 that message.  If @var{regexp} is empty, @kbd{M-s} reuses the regexp
201 used the previous time.
203   To search backward in the file for another message, give @kbd{M-s} a
204 negative argument.  In Rmail you can do this with @kbd{- M-s}.
206   It is also possible to search for a message based on labels.
207 @xref{Rmail Labels}.
209 @kindex j @r{(Rmail)}
210 @kindex > @r{(Rmail)}
211 @kindex < @r{(Rmail)}
212 @findex rmail-show-message
213 @findex rmail-last-message
214 @findex rmail-first-message
215   To move to a message specified by absolute message number, use @kbd{j}
216 (@code{rmail-show-message}) with the message number as argument.  With
217 no argument, @kbd{j} selects the first message.  @kbd{<}
218 (@code{rmail-first-message}) also selects the first message.  @kbd{>}
219 (@code{rmail-last-message}) selects the last message.
221 @node Rmail Deletion
222 @section Deleting Messages
224 @cindex deletion (Rmail)
225   When you no longer need to keep a message, you can @dfn{delete} it.  This
226 flags it as ignorable, and some Rmail commands pretend it is no longer
227 present; but it still has its place in the Rmail file, and still has its
228 message number.
230 @cindex expunging (Rmail)
231   @dfn{Expunging} the Rmail file actually removes the deleted messages.
232 The remaining messages are renumbered consecutively.  Expunging is the only
233 action that changes the message number of any message, except for
234 undigestifying (@pxref{Rmail Digest}).
236 @table @kbd
237 @item d
238 Delete the current message, and move to the next nondeleted message
239 (@code{rmail-delete-forward}).
240 @item C-d
241 Delete the current message, and move to the previous nondeleted
242 message (@code{rmail-delete-backward}).
243 @item u
244 Undelete the current message, or move back to a deleted message and
245 undelete it (@code{rmail-undelete-previous-message}).
246 @item x
247 Expunge the Rmail file (@code{rmail-expunge}).
248 @end table
250 @kindex d @r{(Rmail)}
251 @kindex C-d @r{(Rmail)}
252 @findex rmail-delete-forward
253 @findex rmail-delete-backward
254   There are two Rmail commands for deleting messages.  Both delete the
255 current message and select another message.  @kbd{d}
256 (@code{rmail-delete-forward}) moves to the following message, skipping
257 messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
258 moves to the previous nondeleted message.  If there is no nondeleted
259 message to move to in the specified direction, the message that was just
260 deleted remains current.  @kbd{d} with a numeric argument is
261 equivalent to @kbd{C-d}.
263 @vindex rmail-delete-message-hook
264   Whenever Rmail deletes a message, it runs the hook
265 @code{rmail-delete-message-hook}.  When the hook functions are invoked,
266 the message has been marked deleted, but it is still the current message
267 in the Rmail buffer.
269 @cindex undeletion (Rmail)
270 @kindex x @r{(Rmail)}
271 @findex rmail-expunge
272 @kindex u @r{(Rmail)}
273 @findex rmail-undelete-previous-message
274   To make all the deleted messages finally vanish from the Rmail file,
275 type @kbd{x} (@code{rmail-expunge}).  Until you do this, you can still
276 @dfn{undelete} the deleted messages.  The undeletion command, @kbd{u}
277 (@code{rmail-undelete-previous-message}), is designed to cancel the
278 effect of a @kbd{d} command in most cases.  It undeletes the current
279 message if the current message is deleted.  Otherwise it moves backward
280 to previous messages until a deleted message is found, and undeletes
281 that message.
283   You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u}
284 moves back to and undeletes the message that the @kbd{d} deleted.  But
285 this does not work when the @kbd{d} skips a few already-deleted messages
286 that follow the message being deleted; then the @kbd{u} command
287 undeletes the last of the messages that were skipped.  There is no clean
288 way to avoid this problem.  However, by repeating the @kbd{u} command,
289 you can eventually get back to the message that you intend to
290 undelete.  You can also select a particular deleted message with
291 the @kbd{M-p} command, then type @kbd{u} to undelete it.
293   A deleted message has the @samp{deleted} attribute, and as a result
294 @samp{deleted} appears in the mode line when the current message is
295 deleted.  In fact, deleting or undeleting a message is nothing more than
296 adding or removing this attribute.  @xref{Rmail Attributes}.
298 @node Rmail Inbox
299 @section Rmail Files and Inboxes
300 @cindex inbox file
302   When you receive mail locally, the operating system places incoming
303 mail for you in a file that we call your @dfn{inbox}.  When you start
304 up Rmail, it runs a C program called @code{movemail} to copy the new
305 messages from your local inbox into your primary Rmail file, which
306 also contains other messages saved from previous Rmail sessions.  It
307 is in this file that you actually read the mail with Rmail.  This
308 operation is called @dfn{getting new mail}.  You can get new mail at
309 any time in Rmail by typing @kbd{g}.
311 @vindex rmail-primary-inbox-list
312 @cindex @env{MAIL} environment variable
313   The variable @code{rmail-primary-inbox-list} contains a list of the
314 files which are inboxes for your primary Rmail file.  If you don't set
315 this variable explicitly, it is initialized from the @env{MAIL}
316 environment variable, or, as a last resort, set to @code{nil}, which
317 means to use the default inbox.  The default inbox is
318 @file{/var/mail/@var{username}}, @file{/usr/spool/mail/@var{username}},
319 or @file{/usr/mail/@var{username}}, depending on your operating system.
321   To see what the default is on your system, use @kbd{C-h v
322 rmail-primary-inbox-list @key{RET}}.  You can specify the inbox file(s) for
323 any Rmail file with the command @code{set-rmail-inbox-list}; see
324 @ref{Rmail Files}.
326   There are two reasons for having separate Rmail files and inboxes.
328 @enumerate
329 @item
330 The inbox file format varies between operating systems and according to
331 the other mail software in use.  Only one part of Rmail needs to know
332 about the alternatives, and it need only understand how to convert all
333 of them to Rmail's own format.
335 @item
336 It is very cumbersome to access an inbox file without danger of losing
337 mail, because it is necessary to interlock with mail delivery.
338 Moreover, different operating systems use different interlocking
339 techniques.  The strategy of moving mail out of the inbox once and for
340 all into a separate Rmail file avoids the need for interlocking in all
341 the rest of Rmail, since only Rmail operates on the Rmail file.
342 @end enumerate
344   Rmail was written to use Babyl format as its internal format.  Since
345 then, we have recognized that the usual inbox format on Unix and GNU
346 systems is adequate for the job, and we plan to change Rmail to use that
347 as its internal format.  However, the Rmail file will still be separate
348 from the inbox file, even on systems where their format is the same.
350 @vindex rmail-preserve-inbox
351   When getting new mail, Rmail first copies the new mail from the inbox
352 file to the Rmail file; then it saves the Rmail file; then it truncates
353 the inbox file.  This way, a system crash may cause duplication of mail
354 between the inbox and the Rmail file, but cannot lose mail.  If
355 @code{rmail-preserve-inbox} is non-@code{nil}, then Rmail will copy new
356 mail from the inbox file to the Rmail file without truncating the inbox
357 file.  You may wish to set this, for example, on a portable computer you
358 use to check your mail via POP while traveling, so that your mail will
359 remain on the server and you can save it later on your workstation.
361   In some cases, Rmail copies the new mail from the inbox file
362 indirectly.  First it runs the @code{movemail} program to move the mail
363 from the inbox to an intermediate file called
364 @file{~/.newmail-@var{inboxname}}.  Then Rmail merges the new mail from
365 that file, saves the Rmail file, and only then deletes the intermediate
366 file.  If there is a crash at the wrong time, this file continues to
367 exist, and Rmail will use it again the next time it gets new mail from
368 that inbox.
370   If Rmail is unable to convert the data in
371 @file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
372 to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
373 name unique) so that Rmail will not have trouble with the data again.
374 You should look at the file, find whatever message confuses Rmail
375 (probably one that includes the control-underscore character, octal code
376 037), and delete it.  Then you can use @kbd{1 g} to get new mail from
377 the corrected file.
379 @node Rmail Files
380 @section Multiple Rmail Files
382   Rmail operates by default on your @dfn{primary Rmail file}, which is named
383 @file{~/RMAIL} and receives your incoming mail from your system inbox file.
384 But you can also have other Rmail files and edit them with Rmail.  These
385 files can receive mail through their own inboxes, or you can move messages
386 into them with explicit Rmail commands (@pxref{Rmail Output}).
388 @table @kbd
389 @item i @var{file} @key{RET}
390 Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
392 @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
393 Specify inbox file names for current Rmail file to get mail from.
395 @item g
396 Merge new mail from current Rmail file's inboxes
397 (@code{rmail-get-new-mail}).
399 @item C-u g @var{file} @key{RET}
400 Merge new mail from inbox file @var{file}.
401 @end table
403 @kindex i @r{(Rmail)}
404 @findex rmail-input
405   To run Rmail on a file other than your primary Rmail file, you may use
406 the @kbd{i} (@code{rmail-input}) command in Rmail.  This visits the file
407 in Rmail mode.  You can use @kbd{M-x rmail-input} even when not in
408 Rmail.
410   The file you read with @kbd{i} should normally be a valid Rmail file.
411 If it is not, Rmail tries to decompose it into a stream of messages in
412 various known formats.  If it succeeds, it converts the whole file to an
413 Rmail file.  If you specify a file name that doesn't exist, @kbd{i}
414 initializes a new buffer for creating a new Rmail file.
416 @vindex rmail-secondary-file-directory
417 @vindex rmail-secondary-file-regexp
418   You can also select an Rmail file from a menu.  Choose first the menu
419 bar Classify item, then from the Classify menu choose the Input Rmail
420 File item; then choose the Rmail file you want.  The variables
421 @code{rmail-secondary-file-directory} and
422 @code{rmail-secondary-file-regexp} specify which files to offer in the
423 menu: the first variable says which directory to find them in; the
424 second says which files in that directory to offer (all those that match
425 the regular expression).  These variables also apply to choosing a file
426 for output (@pxref{Rmail Output}).
428 @findex set-rmail-inbox-list
429   Each Rmail file can contain a list of inbox file names; you can specify
430 this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
431 @key{RET}}.  The argument can contain any number of file names, separated
432 by commas.  It can also be empty, which specifies that this file should
433 have no inboxes.  Once a list of inboxes is specified, the Rmail file
434 remembers it permanently until you specify a different list.
436   As a special exception, if your primary Rmail file does not specify any
437 inbox files, it uses your standard system inbox.
439 @kindex g @r{(Rmail)}
440 @findex rmail-get-new-mail
441   The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the
442 current Rmail file from its specified inboxes.  If the Rmail file
443 has no inboxes, @kbd{g} does nothing.  The command @kbd{M-x rmail}
444 also merges new mail into your primary Rmail file.
446   To merge mail from a file that is not the usual inbox, give the
447 @kbd{g} key a numeric argument, as in @kbd{C-u g}.  Then it reads a file
448 name and merges mail from that file.  The inbox file is not deleted or
449 changed in any way when @kbd{g} with an argument is used.  This is,
450 therefore, a general way of merging one file of messages into another.
452 @node Rmail Output
453 @section Copying Messages Out to Files
455   These commands copy messages from an Rmail file into another file.
457 @table @kbd
458 @item o @var{file} @key{RET}
459 Append a copy of the current message to the file @var{file}, using Rmail
460 file format by default (@code{rmail-output-to-rmail-file}).
462 @item C-o @var{file} @key{RET}
463 Append a copy of the current message to the file @var{file}, using
464 system inbox file format by default (@code{rmail-output}).
466 @item w @var{file} @key{RET}
467 Output just the message body to the file @var{file}, taking the default
468 file name from the message @samp{Subject} header.
469 @end table
471 @kindex o @r{(Rmail)}
472 @findex rmail-output-to-rmail-file
473 @kindex C-o @r{(Rmail)}
474 @findex rmail-output
475   The commands @kbd{o} and @kbd{C-o} copy the current message into a
476 specified file.  This file may be an Rmail file or it may be in system
477 inbox format; the output commands ascertain the file's format and write
478 the copied message in that format.
480   The @kbd{o} and @kbd{C-o} commands differ in two ways: each has its
481 own separate default file name, and each specifies a choice of format to
482 use when the file does not already exist.  The @kbd{o} command uses
483 Rmail format when it creates a new file, while @kbd{C-o} uses system
484 inbox format for a new file.  The default file name for @kbd{o} is the
485 file name used last with @kbd{o}, and the default file name for
486 @kbd{C-o} is the file name used last with @kbd{C-o}.
488   If the output file is an Rmail file currently visited in an Emacs buffer,
489 the output commands copy the message into that buffer.  It is up to you
490 to save the buffer eventually in its file.
492 @kindex w @r{(Rmail)}
493 @findex rmail-output-body-to-file
494   Sometimes you may receive a message whose body holds the contents of a
495 file.  You can save the body to a file (excluding the message header)
496 with the @kbd{w} command (@code{rmail-output-body-to-file}).  Often
497 these messages contain the intended file name in the @samp{Subject}
498 field, so the @kbd{w} command uses the @samp{Subject} field as the
499 default for the output file name.  However, the file name is read using
500 the minibuffer, so you can specify a different name if you wish.
502   You can also output a message to an Rmail file chosen with a menu.
503 Choose first the menu bar Classify item, then from the Classify menu
504 choose the Output Rmail File menu item; then choose the Rmail file you want.
505 This outputs the current message to that file, like the @kbd{o} command.
506 The variables @code{rmail-secondary-file-directory} and
507 @code{rmail-secondary-file-regexp} specify which files to offer in the
508 menu: the first variable says which directory to find them in; the
509 second says which files in that directory to offer (all those that match
510 the regular expression).
512 @vindex rmail-delete-after-output
513   Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
514 of the message the @samp{filed} attribute, so that @samp{filed}
515 appears in the mode line when such a message is current.  @kbd{w}
516 gives it the @samp{stored} attribute.  If you like to keep just a
517 single copy of every mail message, set the variable
518 @code{rmail-delete-after-output} to @code{t}; then the @kbd{o},
519 @kbd{C-o} and @kbd{w} commands delete the original message after
520 copying it.  (You can undelete the original afterward if you wish.)
522   Copying messages into files in system inbox format uses the header
523 fields that are displayed in Rmail at the time.  Thus, if you use the
524 @kbd{t} command to view the entire header and then copy the message, the
525 entire header is copied.  @xref{Rmail Display}.
527 @vindex rmail-output-file-alist
528   The variable @code{rmail-output-file-alist} lets you specify
529 intelligent defaults for the output file, based on the contents of the
530 current message.  The value should be a list whose elements have this
531 form:
533 @example
534 (@var{regexp} . @var{name-exp})
535 @end example
537 @noindent
538 If there's a match for @var{regexp} in the current message, then the
539 default file name for output is @var{name-exp}.  If multiple elements
540 match the message, the first matching element decides the default file
541 name.  The subexpression @var{name-exp} may be a string constant giving
542 the file name to use, or more generally it may be any Lisp expression
543 that returns a file name as a string.  @code{rmail-output-file-alist}
544 applies to both @kbd{o} and @kbd{C-o}.
546 @node Rmail Labels
547 @section Labels
548 @cindex label (Rmail)
549 @cindex attribute (Rmail)
551   Each message can have various @dfn{labels} assigned to it as a means
552 of classification.  Each label has a name; different names are different
553 labels.  Any given label is either present or absent on a particular
554 message.  A few label names have standard meanings and are given to
555 messages automatically by Rmail when appropriate; these special labels
556 are called @dfn{attributes}.
557 @ifinfo
558 (@xref{Rmail Attributes}.)
559 @end ifinfo
560 All other labels are assigned only by users.
562 @table @kbd
563 @item a @var{label} @key{RET}
564 Assign the label @var{label} to the current message (@code{rmail-add-label}).
565 @item k @var{label} @key{RET}
566 Remove the label @var{label} from the current message (@code{rmail-kill-label}).
567 @item C-M-n @var{labels} @key{RET}
568 Move to the next message that has one of the labels @var{labels}
569 (@code{rmail-next-labeled-message}).
570 @item C-M-p @var{labels} @key{RET}
571 Move to the previous message that has one of the labels @var{labels}
572 (@code{rmail-previous-labeled-message}).
573 @item l @var{labels} @key{RET}
574 @itemx C-M-l @var{labels} @key{RET}
575 Make a summary of all messages containing any of the labels @var{labels}
576 (@code{rmail-summary-by-labels}).
577 @end table
579 @kindex a @r{(Rmail)}
580 @kindex k @r{(Rmail)}
581 @findex rmail-add-label
582 @findex rmail-kill-label
583   The @kbd{a} (@code{rmail-add-label}) and @kbd{k}
584 (@code{rmail-kill-label}) commands allow you to assign or remove any
585 label on the current message.  If the @var{label} argument is empty, it
586 means to assign or remove the same label most recently assigned or
587 removed.
589   Once you have given messages labels to classify them as you wish, there
590 are two ways to use the labels: in moving and in summaries.
592 @kindex C-M-n @r{(Rmail)}
593 @kindex C-M-p @r{(Rmail)}
594 @findex rmail-next-labeled-message
595 @findex rmail-previous-labeled-message
596   The command @kbd{C-M-n @var{labels} @key{RET}}
597 (@code{rmail-next-labeled-message}) moves to the next message that has
598 one of the labels @var{labels}.  The argument @var{labels} specifies one
599 or more label names, separated by commas.  @kbd{C-M-p}
600 (@code{rmail-previous-labeled-message}) is similar, but moves backwards
601 to previous messages.  A numeric argument to either command serves as a
602 repeat count.
604   The command @kbd{C-M-l @var{labels} @key{RET}}
605 (@code{rmail-summary-by-labels}) displays a summary containing only the
606 messages that have at least one of a specified set of labels.  The
607 argument @var{labels} is one or more label names, separated by commas.
608 @xref{Rmail Summary}, for information on summaries.@refill
610   If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or
611 @kbd{C-M-l} is empty, it means to use the last set of labels specified
612 for any of these commands.
614 @node Rmail Attributes
615 @section Rmail Attributes
617   Some labels such as @samp{deleted} and @samp{filed} have built-in
618 meanings and are assigned to or removed from messages automatically at
619 appropriate times; these labels are called @dfn{attributes}.  Here is a
620 list of Rmail attributes:
622 @table @samp
623 @item unseen
624 Means the message has never been current.  Assigned to messages when
625 they come from an inbox file, and removed when a message is made
626 current.  When you start Rmail, it initially shows the first message
627 that has this attribute.
628 @item deleted
629 Means the message is deleted.  Assigned by deletion commands and
630 removed by undeletion commands (@pxref{Rmail Deletion}).
631 @item filed
632 Means the message has been copied to some other file.  Assigned by the
633 @kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
634 @item stored
635 Assigned by the @kbd{w} file output command (@pxref{Rmail Output}).
636 @item answered
637 Means you have mailed an answer to the message.  Assigned by the @kbd{r}
638 command (@code{rmail-reply}).  @xref{Rmail Reply}.
639 @item forwarded
640 Means you have forwarded the message.  Assigned by the @kbd{f} command
641 (@code{rmail-forward}).  @xref{Rmail Reply}.
642 @item edited
643 Means you have edited the text of the message within Rmail.
644 @xref{Rmail Editing}.
645 @item resent
646 Means you have resent the message.  Assigned by the command @kbd{M-x
647 rmail-resend}.  @xref{Rmail Reply}.
648 @end table
650   All other labels are assigned or removed only by the user, and have no
651 standard meaning.
653 @node Rmail Reply
654 @section Sending Replies
656   Rmail has several commands that use Mail mode to send outgoing mail.
657 @xref{Sending Mail}, for information on using Mail mode, including
658 certain features meant to work with Rmail.  What this section documents
659 are the special commands of Rmail for entering Mail mode.  Note that the
660 usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5
661 m}---are available in Rmail mode and work just as they usually do.
663 @table @kbd
664 @item m
665 Send a message (@code{rmail-mail}).
666 @item c
667 Continue editing the already started outgoing message (@code{rmail-continue}).
668 @item r
669 Send a reply to the current Rmail message (@code{rmail-reply}).
670 @item f
671 Forward the current message to other users (@code{rmail-forward}).
672 @item C-u f
673 Resend the current message to other users (@code{rmail-resend}).
674 @item M-m
675 Try sending a bounced message a second time (@code{rmail-retry-failure}).
676 @end table
678 @kindex r @r{(Rmail)}
679 @findex rmail-reply
680 @cindex reply to a message
681   The most common reason to send a message while in Rmail is to reply to
682 the message you are reading.  To do this, type @kbd{r}
683 (@code{rmail-reply}).  This displays the @samp{*mail*} buffer in another
684 window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
685 @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
686 message you are replying to.  The @samp{To} field starts out as the
687 address of the person who sent the message you received, and the
688 @samp{CC} field starts out with all the other recipients of that
689 message.
691 @vindex rmail-dont-reply-to-names
692   You can exclude certain recipients from being placed automatically in
693 the @samp{CC}, using the variable @code{rmail-dont-reply-to-names}.  Its
694 value should be a regular expression (as a string); any recipient that
695 the regular expression matches, is excluded from the @samp{CC} field.
696 The default value matches your own name, and any name starting with
697 @samp{info-}.  (Those names are excluded because there is a convention
698 of using them for large mailing lists to broadcast announcements.)
700   To omit the @samp{CC} field completely for a particular reply, enter
701 the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.
703   Once the @samp{*mail*} buffer has been initialized, editing and
704 sending the mail goes as usual (@pxref{Sending Mail}).  You can edit the
705 presupplied header fields if they are not right for you.  You can also
706 use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c
707 C-y} which yanks in the message that you are replying to.  You can
708 switch to the Rmail buffer, select a different message there, switch
709 back, and yank the new current message.
711 @kindex M-m @r{(Rmail)}
712 @findex rmail-retry-failure
713 @cindex retrying a failed message
714 @vindex rmail-retry-ignored-headers
715   Sometimes a message does not reach its destination.  Mailers usually
716 send the failed message back to you, enclosed in a @dfn{failure
717 message}.  The Rmail command @kbd{M-m} (@code{rmail-retry-failure})
718 prepares to send the same message a second time: it sets up a
719 @samp{*mail*} buffer with the same text and header fields as before.  If
720 you type @kbd{C-c C-c} right away, you send the message again exactly
721 the same as the first time.  Alternatively, you can edit the text or
722 headers and then send it.  The variable
723 @code{rmail-retry-ignored-headers}, in the same format as
724 @code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
725 headers are stripped from the failed message when retrying it.
727 @kindex f @r{(Rmail)}
728 @findex rmail-forward
729 @cindex forwarding a message
730   Another frequent reason to send mail in Rmail is to @dfn{forward} the
731 current message to other users.  @kbd{f} (@code{rmail-forward}) makes
732 this easy by preinitializing the @samp{*mail*} buffer with the current
733 message as the text, and a subject designating a forwarded message.  All
734 you have to do is fill in the recipients and send.  When you forward a
735 message, recipients get a message which is ``from'' you, and which has
736 the original message in its contents.
738 @findex unforward-rmail-message
739   Forwarding a message encloses it between two delimiter lines.  It also
740 modifies every line that starts with a dash, by inserting @w{@samp{- }}
741 at the start of the line.  When you receive a forwarded message, if it
742 contains something besides ordinary text---for example, program source
743 code---you might find it useful to undo that transformation.  You can do
744 this by selecting the forwarded message and typing @kbd{M-x
745 unforward-rmail-message}.  This command extracts the original forwarded
746 message, deleting the inserted @w{@samp{- }} strings, and inserts it
747 into the Rmail file as a separate message immediately following the
748 current one.
750 @findex rmail-resend
751   @dfn{Resending} is an alternative similar to forwarding; the
752 difference is that resending sends a message that is ``from'' the
753 original sender, just as it reached you---with a few added header fields
754 @samp{Resent-From} and @samp{Resent-To} to indicate that it came via
755 you.  To resend a message in Rmail, use @kbd{C-u f}.  (@kbd{f} runs
756 @code{rmail-forward}, which is programmed to invoke @code{rmail-resend}
757 if you provide a numeric argument.)
759 @kindex m @r{(Rmail)}
760 @findex rmail-mail
761   The @kbd{m} (@code{rmail-mail}) command is used to start editing an
762 outgoing message that is not a reply.  It leaves the header fields empty.
763 Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
764 accessible for @kbd{C-c C-y}, just as @kbd{r} does.  Thus, @kbd{m} can be
765 used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
766 can do.@refill
768 @kindex c @r{(Rmail)}
769 @findex rmail-continue
770   The @kbd{c} (@code{rmail-continue}) command resumes editing the
771 @samp{*mail*} buffer, to finish editing an outgoing message you were
772 already composing, or to alter a message you have sent.@refill
774 @vindex rmail-mail-new-frame
775   If you set the variable @code{rmail-mail-new-frame} to a
776 non-@code{nil} value, then all the Rmail commands to start sending a
777 message create a new frame to edit it in.  This frame is deleted when
778 you send the message, or when you use the @samp{Cancel} item in the
779 @samp{Mail} menu.
781   All the Rmail commands to send a message use the mail-composition
782 method that you have chosen (@pxref{Mail Methods}).
784 @node Rmail Summary
785 @section Summaries
786 @cindex summary (Rmail)
788   A @dfn{summary} is a buffer containing one line per message to give
789 you an overview of the mail in an Rmail file.  Each line shows the
790 message number and date, the sender, the line count, the labels, and
791 the subject.  Moving point in the summary buffer selects messages as
792 you move to their summary lines.  Almost all Rmail commands are valid
793 in the summary buffer also; when used there, they apply to the message
794 described by the current line of the summary.
796   A summary buffer applies to a single Rmail file only; if you are
797 editing multiple Rmail files, each one can have its own summary buffer.
798 The summary buffer name is made by appending @samp{-summary} to the
799 Rmail buffer's name.  Normally only one summary buffer is displayed at a
800 time.
802 @menu
803 * Rmail Make Summary::       Making various sorts of summaries.
804 * Rmail Summary Edit::       Manipulating messages from the summary.
805 @end menu
807 @node Rmail Make Summary
808 @subsection Making Summaries
810   Here are the commands to create a summary for the current Rmail file.
811 Once the Rmail file has a summary buffer, changes in the Rmail file
812 (such as deleting or expunging messages, and getting new mail)
813 automatically update the summary.
815 @table @kbd
816 @item h
817 @itemx C-M-h
818 Summarize all messages (@code{rmail-summary}).
819 @item l @var{labels} @key{RET}
820 @itemx C-M-l @var{labels} @key{RET}
821 Summarize messages that have one or more of the specified labels
822 (@code{rmail-summary-by-labels}).
823 @item C-M-r @var{rcpts} @key{RET}
824 Summarize messages that have one or more of the specified recipients
825 (@code{rmail-summary-by-recipients}).
826 @item C-M-t @var{topic} @key{RET}
827 Summarize messages that have a match for the specified regexp
828 @var{topic} in their subjects (@code{rmail-summary-by-topic}).
829 @item C-M-s @var{regexp}
830 Summarize messages whose headers and the subject line match the
831 specified regular expression @var{regexp}
832 (@code{rmail-summary-by-regexp}).
833 @end table
835 @kindex h @r{(Rmail)}
836 @findex rmail-summary
837   The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
838 for the current Rmail file with a summary of all the messages in the file.
839 It then displays and selects the summary buffer in another window.
841 @kindex l @r{(Rmail)}
842 @kindex C-M-l @r{(Rmail)}
843 @findex rmail-summary-by-labels
844   @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
845 a partial summary mentioning only the messages that have one or more of the
846 labels @var{labels}.  @var{labels} should contain label names separated by
847 commas.@refill
849 @kindex C-M-r @r{(Rmail)}
850 @findex rmail-summary-by-recipients
851   @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
852 makes a partial summary mentioning only the messages that have one or more
853 of the recipients @var{rcpts}.  @var{rcpts} should contain mailing
854 addresses separated by commas.@refill
856 @kindex C-M-t @r{(Rmail)}
857 @findex rmail-summary-by-topic
858   @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic})
859 makes a partial summary mentioning only the messages whose subjects have
860 a match for the regular expression @var{topic}.
862 @kindex C-M-s @r{(Rmail)}
863 @findex rmail-summary-by-regexp
864   @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
865 makes a partial summary which mentions only the messages whose headers
866 (including the date and the subject lines) match the regular
867 expression @var{regexp}.
869   Note that there is only one summary buffer for any Rmail file; making one
870 kind of summary discards any previously made summary.
872 @vindex rmail-summary-window-size
873 @vindex rmail-summary-line-count-flag
874   The variable @code{rmail-summary-window-size} says how many lines to
875 use for the summary window.  The variable
876 @code{rmail-summary-line-count-flag} controls whether the summary line
877 for a message should include the line count of the message.
879 @node Rmail Summary Edit
880 @subsection Editing in Summaries
882   You can use the Rmail summary buffer to do almost anything you can do
883 in the Rmail buffer itself.  In fact, once you have a summary buffer,
884 there's no need to switch back to the Rmail buffer.
886   You can select and display various messages in the Rmail buffer, from
887 the summary buffer, just by moving point in the summary buffer to
888 different lines.  It doesn't matter what Emacs command you use to move
889 point; whichever line point is on at the end of the command, that
890 message is selected in the Rmail buffer.
892   Almost all Rmail commands work in the summary buffer as well as in the
893 Rmail buffer.  Thus, @kbd{d} in the summary buffer deletes the current
894 message, @kbd{u} undeletes, and @kbd{x} expunges.  (However, in the
895 summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u}
896 serves as a repeat count.  A negative argument reverses the meaning of
897 @kbd{d} and @kbd{C-d}.)  @kbd{o} and @kbd{C-o} output the current
898 message to a file; @kbd{r} starts a reply to it.  You can scroll the
899 current message while remaining in the summary buffer using @key{SPC}
900 and @key{DEL}.
902   The Rmail commands to move between messages also work in the summary
903 buffer, but with a twist: they move through the set of messages included
904 in the summary.  They also ensure the Rmail buffer appears on the screen
905 (unlike cursor motion commands, which update the contents of the Rmail
906 buffer but don't display it in a window unless it already appears).
907 Here is a list of these commands:
909 @table @kbd
910 @item n
911 Move to next line, skipping lines saying `deleted', and select its
912 message.
913 @item p
914 Move to previous line, skipping lines saying `deleted', and select
915 its message.
916 @item M-n
917 Move to next line and select its message.
918 @item M-p
919 Move to previous line and select its message.
920 @item >
921 Move to the last line, and select its message.
922 @item <
923 Move to the first line, and select its message.
924 @item j
925 @itemx @key{RET}
926 Select the message on the current line (ensuring that the RMAIL buffer
927 appears on the screen).  With argument @var{n}, select message number
928 @var{n} and move to its line in the summary buffer; this signals an
929 error if the message is not listed in the summary buffer.
930 @item M-s @var{pattern} @key{RET}
931 Search through messages for @var{pattern} starting with the current
932 message; select the message found, and move point in the summary buffer
933 to that message's line.
934 @end table
936 @vindex rmail-redisplay-summary
937   Deletion, undeletion, and getting new mail, and even selection of a
938 different message all update the summary buffer when you do them in the
939 Rmail buffer.  If the variable @code{rmail-redisplay-summary} is
940 non-@code{nil}, these actions also bring the summary buffer back onto
941 the screen.
943 @kindex Q @r{(Rmail summary)}
944 @findex rmail-summary-wipe
945 @kindex q @r{(Rmail summary)}
946 @findex rmail-summary-quit
947   When you are finished using the summary, type @kbd{Q}
948 (@code{rmail-summary-wipe}) to delete the summary buffer's window.  You
949 can also exit Rmail while in the summary: @kbd{q}
950 (@code{rmail-summary-quit}) deletes the summary window, then exits from
951 Rmail by saving the Rmail file and switching to another buffer.
953 @node Rmail Sorting
954 @section Sorting the Rmail File
956 @table @kbd
957 @item M-x rmail-sort-by-date
958 Sort messages of current Rmail file by date.
960 @item M-x rmail-sort-by-subject
961 Sort messages of current Rmail file by subject.
963 @item M-x rmail-sort-by-author
964 Sort messages of current Rmail file by author's name.
966 @item M-x rmail-sort-by-recipient
967 Sort messages of current Rmail file by recipient's names.
969 @item M-x rmail-sort-by-correspondent
970 Sort messages of current Rmail file by the name of the other
971 correspondent.
973 @item M-x rmail-sort-by-lines
974 Sort messages of current Rmail file by size (number of lines).
976 @item M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET}
977 Sort messages of current Rmail file by labels.  The argument
978 @var{labels} should be a comma-separated list of labels.  The order of
979 these labels specifies the order of messages; messages with the first
980 label come first, messages with the second label come second, and so on.
981 Messages which have none of these labels come last.
982 @end table
984   The Rmail sort commands perform a @emph{stable sort}: if there is no
985 reason to prefer either one of two messages, their order remains
986 unchanged.  You can use this to sort by more than one criterion.  For
987 example, if you use @code{rmail-sort-by-date} and then
988 @code{rmail-sort-by-author}, messages from the same author appear in
989 order by date.
991   With a numeric argument, all these commands reverse the order of
992 comparison.  This means they sort messages from newest to oldest, from
993 biggest to smallest, or in reverse alphabetical order.
995 @node Rmail Display
996 @section Display of Messages
998   Rmail reformats the header of each message before displaying it for
999 the first time.  Reformatting hides uninteresting header fields to
1000 reduce clutter.  You can use the @kbd{t} command to show the entire
1001 header or to repeat the header reformatting operation.
1003 @table @kbd
1004 @item t
1005 Toggle display of complete header (@code{rmail-toggle-header}).
1006 @end table
1008 @vindex rmail-ignored-headers
1009   Reformatting the header involves deleting most header fields, on the
1010 grounds that they are not interesting.  The variable
1011 @code{rmail-ignored-headers} holds a regular expression that specifies
1012 which header fields to hide in this way---if it matches the beginning of
1013 a header field, that whole field is hidden.
1015 @kindex t @r{(Rmail)}
1016 @findex rmail-toggle-header
1017   Rmail saves the complete original header before reformatting; to see
1018 it, use the @kbd{t} command (@code{rmail-toggle-header}).  This
1019 discards the reformatted headers of the current message and displays it
1020 with the original header.  Repeating @kbd{t} reformats the message
1021 again.  Selecting the message again also reformats.
1023   One consequence of this is that if you edit the reformatted header
1024 (using @kbd{e}; @pxref{Rmail Editing}), subsequent use of @kbd{t} will
1025 discard your edits.  On the other hand, if you use @kbd{e} after
1026 @kbd{t}, to edit the original (unreformatted) header, those changes are
1027 permanent.
1029   When the @kbd{t} command has a prefix argument, a positive argument
1030 means to show the reformatted header, and a zero or negative argument
1031 means to show the full header.
1033 @vindex rmail-highlighted-headers
1034   When the terminal supports multiple fonts or colors, Rmail
1035 highlights certain header fields that are especially interesting---by
1036 default, the @samp{From} and @samp{Subject} fields.  The variable
1037 @code{rmail-highlighted-headers} holds a regular expression that
1038 specifies the header fields to highlight; if it matches the beginning
1039 of a header field, that whole field is highlighted.
1041   If you specify unusual colors for your text foreground and
1042 background, the colors used for highlighting may not go well with
1043 them.  If so, specify different colors for the face
1044 @code{rmail-highlight-face}.  @xref{Faces}, for how to do this.  To
1045 turn off highlighting entirely in Rmail, set
1046 @code{rmail-highlighted-headers} to @code{nil}.
1048   You can highlight and activate URLs in incoming messages by adding
1049 the function @code{goto-address} to the hook
1050 @code{rmail-show-message-hook}.  Then you can browse these URLs by
1051 clicking on them with @kbd{Mouse-2} (or @kbd{Mouse-1} quickly) or by
1052 moving to one and typing @kbd{C-c @key{RET}}.  @xref{Goto-address,
1053 Activating URLs, Activating URLs}.
1055 @node Rmail Coding
1056 @section Rmail and Coding Systems
1058 @cindex decoding mail messages (Rmail)
1059   Rmail automatically decodes messages which contain non-@acronym{ASCII}
1060 characters, just as Emacs does with files you visit and with subprocess
1061 output.  Rmail uses the standard @samp{charset=@var{charset}} header in
1062 the message, if any, to determine how the message was encoded by the
1063 sender.  It maps @var{charset} into the corresponding Emacs coding
1064 system (@pxref{Coding Systems}), and uses that coding system to decode
1065 message text.  If the message header doesn't have the @samp{charset}
1066 specification, or if @var{charset} is not recognized,
1067 Rmail chooses the coding system with the usual Emacs heuristics and
1068 defaults (@pxref{Recognize Coding}).
1070 @cindex fixing incorrectly decoded mail messages
1071   Occasionally, a message is decoded incorrectly, either because Emacs
1072 guessed the wrong coding system in the absence of the @samp{charset}
1073 specification, or because the specification was inaccurate.  For
1074 example, a misconfigured mailer could send a message with a
1075 @samp{charset=iso-8859-1} header when the message is actually encoded
1076 in @code{koi8-r}.  When you see the message text garbled, or some of
1077 its characters displayed as empty boxes, this may have happened.
1079 @findex rmail-redecode-body
1080   You can correct the problem by decoding the message again using the
1081 right coding system, if you can figure out or guess which one is
1082 right.  To do this, invoke the @kbd{M-x rmail-redecode-body} command.
1083 It reads the name of a coding system, encodes the message body using
1084 whichever coding system was used to decode it before, then redecodes
1085 it using the coding system you specified.  If you specified the right
1086 coding system, the result should be readable.
1088   Decoding and encoding using the wrong coding system is lossless for
1089 most encodings, in particular with 8-bit encodings such as iso-8859 or
1090 koi8.  So, if the initial attempt to redecode the message didn't
1091 result in a legible text, you can try other coding systems until you
1092 succeed.
1094   With some coding systems, notably those from the iso-2022 family,
1095 information can be lost in decoding, so that encoding the message
1096 again won't bring back the original incoming text.  In such a case,
1097 @code{rmail-redecode-body} cannot work.  However, the problems that
1098 call for use of @code{rmail-redecode-body} rarely occur with those
1099 coding systems.  So in practice the command works when you need it.
1101 @node Rmail Editing
1102 @section Editing Within a Message
1104   Most of the usual Emacs commands are available in Rmail mode, though a
1105 few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
1106 other purposes.  However, the Rmail buffer is normally read only, and
1107 most of the letters are redefined as Rmail commands.  If you want to
1108 edit the text of a message, you must use the Rmail command @kbd{e}.
1110 @table @kbd
1111 @item e
1112 Edit the current message as ordinary text.
1113 @end table
1115 @kindex e @r{(Rmail)}
1116 @findex rmail-edit-current-message
1117   The @kbd{e} command (@code{rmail-edit-current-message}) switches from
1118 Rmail mode into Rmail Edit mode, another major mode which is nearly the
1119 same as Text mode.  The mode line indicates this change.
1121   In Rmail Edit mode, letters insert themselves as usual and the Rmail
1122 commands are not available.  When you are finished editing the message and
1123 are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
1124 Rmail mode.  Alternatively, you can return to Rmail mode but cancel all the
1125 editing that you have done, by typing @kbd{C-c C-]}.
1127 @vindex rmail-edit-mode-hook
1128   Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then it
1129 runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}).  It adds the
1130 attribute @samp{edited} to the message.  It also displays the full
1131 headers of the message, so that you can edit the headers as well as the
1132 body of the message, and your changes in the headers will be
1133 permanent.
1135 @node Rmail Digest
1136 @section Digest Messages
1137 @cindex digest message
1138 @cindex undigestify
1140   A @dfn{digest message} is a message which exists to contain and carry
1141 several other messages.  Digests are used on some moderated mailing
1142 lists; all the messages that arrive for the list during a period of time
1143 such as one day are put inside a single digest which is then sent to the
1144 subscribers.  Transmitting the single digest uses much less computer
1145 time than transmitting the individual messages even though the total
1146 size is the same, because the per-message overhead in network mail
1147 transmission is considerable.
1149 @findex undigestify-rmail-message
1150   When you receive a digest message, the most convenient way to read it is
1151 to @dfn{undigestify} it: to turn it back into many individual messages.
1152 Then you can read and delete the individual messages as it suits you.
1153 To do this, select the digest message and type the command @kbd{M-x
1154 undigestify-rmail-message}.  This extracts the submessages as separate
1155 Rmail messages, and inserts them following the digest.  The digest
1156 message itself is flagged as deleted.
1158 @node Out of Rmail
1159 @section Converting an Rmail File to Inbox Format
1160 @cindex Babyl format to Inbox format
1161 @cindex converting Rmail file to mailbox format
1163 @findex unrmail
1164   The command @kbd{M-x unrmail} converts a file in Rmail format to inbox
1165 format (also known as the system mailbox, or mbox, format), so that
1166 you can use it with other mail-editing tools.  You must specify two
1167 arguments, the name of the Rmail file and the name to use for the
1168 converted file.  @kbd{M-x unrmail} does not alter the Rmail file itself.
1170 @pindex b2m
1171   @kbd{M-x unrmail} is useful if you can run Emacs on the machine
1172 where the Rmail file resides, or can access the Rmail file remotely
1173 (@pxref{Remote Files}) from a machine where Emacs is installed.  If
1174 accessing Rmail files from Emacs is impossible, you can use the
1175 @command{b2m} program instead.  @command{b2m} is part of the Emacs
1176 distribution, it is installed into the same directory where all the
1177 other auxiliary programs (@command{etags} etc.) are installed, and its
1178 source is available in the Emacs source distribution, so that you
1179 could copy the source to the target machine and compile it there.
1181   To convert a file @file{@var{babyl-file}} into @file{@var{mbox-file}},
1182 invoke @command{b2m} like this:
1184 @example
1185  b2m < @var{babyl-file} > @var{mbox-file}
1186 @end example
1188 @node Rmail Rot13
1189 @section Reading Rot13 Messages
1190 @cindex rot13 code
1192   Mailing list messages that might offend some readers are sometimes
1193 encoded in a simple code called @dfn{rot13}---so named because it
1194 rotates the alphabet by 13 letters.  This code is not for secrecy, as it
1195 provides none; rather, it enables those who might be offended to avoid
1196 ever seeing the real text of the message.
1198 @findex rot13-other-window
1199   To view a buffer using the rot13 code, use the command @kbd{M-x
1200 rot13-other-window}.  This displays the current buffer in another window
1201 which applies the code when displaying the text.
1203 @node Movemail
1204 @section @code{movemail} program
1205 @cindex @code{movemail} program
1207   When invoked for the first time, Rmail attempts to locate the
1208 @code{movemail} program and determine its version.  There are two
1209 versions of @code{movemail} program: the native one, shipped with GNU
1210 Emacs (the ``emacs version'') and the one included in GNU mailutils
1211 (the ``mailutils version,'' @pxref{movemail,,,mailutils,GNU
1212 mailutils}).  They support the same command line syntax and the same
1213 basic subset of options.  However, the @samp{mailutils} version offers
1214 additional features.
1216   The Emacs version of @code{movemail} is able to retrieve mail from
1217 usual UNIX mailbox formats and from remote mailboxes using the POP3
1218 protocol.
1220   The Mailutils version is able to handle a wide set of mailbox
1221 formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
1222 mailboxes, etc.  It is able to retrieve remote mail using POP3 or
1223 IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
1224 channel.  It also accepts mailbox argument in the @acronym{URL} form.
1225 The detailed description of mailbox @acronym{URL}s can be found in
1226 @ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a @acronym{URL}
1229 @smallexample
1230 @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
1231 @end smallexample
1233 @noindent
1234 where square brackets denote optional elements.
1236 @table @var
1237 @item proto
1238 Specifies the @dfn{mailbox protocol}, or @dfn{format} to
1239 use.  The exact semantics of the rest of @acronym{URL} elements depends
1240 on the actual value of @var{proto}.
1242 @item user
1243 User name to access the remote mailbox.
1245 @item password
1246 User password to access the remote mailbox.
1248 @item host-or-file-name
1249 Hostname of the remote server for remote mailboxes or file name of a
1250 local mailbox.
1251 @end table
1253 @var{Proto} can be one of:
1255 @table @asis
1256 @item mbox
1257 Usual UNIX mailbox format.  In this case, neither @var{user} nor
1258 @var{pass} are used, and @var{host-or-file-name} denotes the file name of
1259 the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
1261 @item mh
1262 A local mailbox in the @acronym{MH} format.  @var{User} and
1263 @var{pass} are not used.  @var{Host-or-file-name} denotes the name of
1264 @acronym{MH} folder, e.g., @code{mh://Mail/inbox}.
1266 @item maildir
1267 A local mailbox in the @acronym{maildir} format.  @var{User} and
1268 @var{pass} are not used, and @var{host-or-file-name} denotes the name of
1269 @code{maildir} mailbox, e.g., @code{maildir://mail/inbox}.
1271 @item file
1272 Any local mailbox format.  Its actual format is detected automatically
1273 by @code{movemail}.
1275 @item pop
1276 A remote mailbox to be accessed via POP3 protocol.  @var{User}
1277 specifies the remote user name to use, @var{pass} may be used to
1278 specify the user password, @var{host-or-file-name} is the name or IP
1279 address of the remote mail server to connect to; e.g.,
1280 @code{pop://smith:guessme@@remote.server.net}.
1282 @item imap
1283 A remote mailbox to be accessed via IMAP4 protocol.  @var{User}
1284 specifies the remote user name to use, @var{pass} may be used to
1285 specify the user password, @var{host-or-file-name} is the name or IP
1286 address of the remote mail server to connect to;
1287 e.g., @code{imap://smith:guessme@@remote.server.net}.
1288 @end table
1290   Alternatively, you can specify the file name of the mailbox to use.
1291 This is equivalent to specifying the @samp{file} protocol:
1293 @smallexample
1294 /var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user}
1295 @end smallexample
1297 @vindex rmail-movemail-program
1298 @vindex rmail-movemail-search-path
1299   The variable @code{rmail-movemail-program} controls which version of
1300 @code{movemail} to use.  If that is a string, it specifies the
1301 absolute file name of the @code{movemail} executable.  If it is
1302 @code{nil}, Rmail searches for @code{movemail} in the directories
1303 listed in @code{rmail-movemail-search-path} and @code{exec-path}, then
1304 in @code{exec-directory}.
1306 @node Remote Mailboxes
1307 @section Retrieving Mail from Remote Mailboxes
1308 @pindex movemail
1310   Some sites use a method called POP for accessing users' inbox data
1311 instead of storing the data in inbox files.  The @code{Emacs
1312 movemail} can work with POP if you compile it with the macro
1313 @code{MAIL_USE_POP} defined.  (You can achieve that by specifying
1314 @samp{--with-pop} when you run @code{configure} during the
1315 installation of Emacs.)
1317 The @code{Mailutils movemail} by default supports POP, unless configured
1318 with @samp{--disable-pop} option.
1320 Both versions of @code{movemail} only work with POP3, not with older
1321 versions of POP.
1323 @cindex @env{MAILHOST} environment variable
1324 @cindex POP mailboxes
1325   No matter which flavor of @code{movemail} you use, you can specify
1326 POP inbox by using POP @dfn{URL} (@pxref{Movemail}).  A POP
1327 @acronym{URL} is a ``file name'' of the form
1328 @samp{pop://@var{username}@@@var{hostname}}, where
1329 @var{hostname} is the host name or IP address of the remote mail
1330 server and @var{username} is the user name on that server.
1331 Additionally, you may specify the password in the mailbox @acronym{URL}:
1332 @samp{pop://@var{username}:@var{password}@@@var{hostname}}.  In this
1333 case, @var{password} takes preference over the one set by
1334 @code{rmail-remote-password}.  This is especially useful if you have
1335 several remote mailboxes with different passwords.
1337   For backward compatibility Rmail also supports two alternative ways
1338 of specifying remote POP mailboxes.  Specifying inbox name in the form
1339 @samp{po:@var{username}:@var{hostname}} is equivalent to
1340 @samp{pop://@var{username}@@@var{hostname}}.  Alternatively, you may set
1341 a ``file name'' of @samp{po:@var{username}} in the inbox list of an
1342 Rmail file.  @code{Movemail} will handle such a name by opening a
1343 connection to the POP server.  The @env{MAILHOST} environment variable
1344 will in this case specify the machine to look for the server on.
1346 @cindex IMAP mailboxes
1347   Another method for accessing remote mailboxes is IMAP.  This method is
1348 supported only by the @code{mailutils movemail}.  To specify an IMAP
1349 mailbox in the inbox list, use the following mailbox @acronym{URL}:
1350 @samp{imap://@var{username}[:@var{password}]@@@var{hostname}}.  The
1351 @var{password} part is optional, as described above.
1353 @vindex rmail-remote-password
1354 @vindex rmail-remote-password-required
1355 @vindex rmail-pop-password
1356 @vindex rmail-pop-password-required
1357   Accessing a remote mailbox may require a password.  Rmail uses the
1358 following algorithm to retrieve it:
1360 @enumerate
1361 @item
1362 If the @var{password} is present in mailbox URL (see above), it is
1363 used.
1364 @item
1365 If the variable @code{rmail-remote-password} is non-@code{nil}, its
1366 value is used.
1367 @item
1368 Otherwise, if @code{rmail-remote-password-required} is non-@code{nil},
1369 then Rmail will ask you for the password to use.
1370 @item
1371 Otherwise, Rmail assumes no password is required.
1372 @end enumerate
1374   For compatibility with previous versions, @code{rmail-pop-password}
1375 and @code{rmail-pop-password-required} may be used instead of
1376 @code{rmail-remote-password} and @code{rmail-remote-password-required}.
1378 @vindex rmail-movemail-flags
1379   If you need to pass additional command-line flags to @code{movemail},
1380 set the variable @code{rmail-movemail-flags} a list of the flags you
1381 wish to use.  Do not use this variable to pass the @samp{-p} flag to
1382 preserve your inbox contents; use @code{rmail-preserve-inbox} instead.
1384 @cindex Kerberos POP authentication
1385   The @code{movemail} program installed at your site may support
1386 Kerberos authentication.  If it is
1387 supported, it is used by default whenever you attempt to retrieve
1388 POP mail when @code{rmail-pop-password} and
1389 @code{rmail-pop-password-required} are unset.
1391 @cindex reverse order in POP inboxes
1392   Some POP servers store messages in reverse order.  If your server does
1393 this, and you would rather read your mail in the order in which it was
1394 received, you can tell @code{movemail} to reverse the order of
1395 downloaded messages by adding the @samp{-r} flag to
1396 @code{rmail-movemail-flags}.
1398 @cindex TLS encryption (Rmail)
1399   @code{Mailutils movemail} supports TLS encryption.  If you wish to
1400 use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
1402 @node Other Mailbox Formats
1403 @section Retrieving Mail from Local Mailboxes in Various Formats
1405   If your incoming mail is stored on a local machine in a format other
1406 than UNIX mailbox, you will need the @code{mailutils movemail} to retrieve
1407 it.  @xref{Movemail}, for the detailed description of @code{movemail}
1408 versions.
1410   For example, to retrieve mail from a @code{maildir} inbox located in
1411 @file{/var/spool/mail/in}, you would set the following in Rmail inbox list:
1413 @smallexample
1414 maildir://var/spool/mail/in
1415 @end smallexample
1417 @ignore
1418    arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23
1419 @end ignore