@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1985,86,87,93,94,95,1997,2001 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Rmail, Dired, Sending Mail, Top
@chapter Reading Mail with Rmail
* Summary: Rmail Summary. Summaries show brief info on many messages.
* Sort: Rmail Sorting. Sorting messages in Rmail.
* Display: Rmail Display. How Rmail displays a message; customization.
+* Coding: Rmail Coding. How Rmail handles decoding character sets.
* Editing: Rmail Editing. Editing message text and headers in Rmail.
* Digest: Rmail Digest. Extracting the messages from a digest message.
* Out of Rmail:: Converting an Rmail file to mailbox format.
* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.
-* Movemail: Movemail. More details of fetching new mail.
+* Movemail:: More details of fetching new mail.
+* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes.
+* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in
+ Various Formats
@end menu
@node Rmail Basics
(@pxref{Rmail Motion}).
@kindex s @r{(Rmail)}
-@findex rmail-save
+@findex rmail-expunge-and-save
Following the usual conventions of Emacs, changes in an Rmail file
become permanent only when the file is saved. You can save it with
-@kbd{s} (@code{rmail-save}), which also expunges deleted messages from
-the file first (@pxref{Rmail Deletion}). To save the file without
-expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail file after
-merging new mail from an inbox file (@pxref{Rmail Inbox}).
+@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted
+messages from the file first (@pxref{Rmail Deletion}). To save the
+file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail
+file after merging new mail from an inbox file (@pxref{Rmail Inbox}).
@kindex q @r{(Rmail)}
@findex rmail-quit
@kindex b @r{(Rmail)}
@findex rmail-bury
- You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and
-saves the Rmail file and then switches to another buffer. But there is
-no need to `exit' formally. If you switch from Rmail to editing in
-other buffers, and never happen to switch back, you have exited. (The
-Rmail command @kbd{b}, @code{rmail-bury}, does this for you.) Just make
-sure to save the Rmail file eventually (like any other file you have
-changed). @kbd{C-x s} is a good enough way to do this
-(@pxref{Saving}).
+ You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges
+and saves the Rmail file, then buries the Rmail buffer as well as its
+summary buffer, if present (@pxref{Rmail Summary}). But there is no
+need to ``exit'' formally. If you switch from Rmail to editing in
+other buffers, and never happen to switch back, you have exited. Just
+make sure to save the Rmail file eventually (like any other file you
+have changed). @kbd{C-x s} is a good enough way to do this
+(@pxref{Saving}). The Rmail command @kbd{b}, @code{rmail-bury},
+buries the Rmail buffer and its summary buffer without expunging and
+saving the Rmail file.
@node Rmail Scrolling
@section Scrolling Within a Message
When Rmail displays a message that does not fit on the screen, you
-must scroll through it to read the rest. You could do this with
+must scroll through it to read the rest. You could do this with
@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so
frequent that it deserves to be easier to type.
receipt of messages. When you enter Rmail, you are positioned at the
first message that you have not yet made current (that is, the first one
that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move
-forward to see the other new messages; move backward to reexamine old
+forward to see the other new messages; move backward to re-examine old
messages.
@table @kbd
messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward})
moves to the previous nondeleted message. If there is no nondeleted
message to move to in the specified direction, the message that was just
-deleted remains current. A numeric argument to either command reverses
-the direction of motion after deletion.
+deleted remains current. @kbd{d} with a numeric argument is
+equivalent to @kbd{C-d}.
@vindex rmail-delete-message-hook
- Whenever Rmail deletes a message, it invokes the function(s) listed in
+ Whenever Rmail deletes a message, it runs the hook
@code{rmail-delete-message-hook}. When the hook functions are invoked,
the message has been marked deleted, but it is still the current message
in the Rmail buffer.
@section Rmail Files and Inboxes
@cindex inbox file
- The operating system places incoming mail for you in a file that we
-call your @dfn{inbox}. When you start up Rmail, it runs a C program
-called @code{movemail} to copy the new messages from your inbox into
-your primary Rmail file, which also contains other messages saved from
-previous Rmail sessions. It is in this file that you actually read the
-mail with Rmail. This operation is called @dfn{getting new mail}. You
-can get new mail at any time in Rmail by typing @kbd{g}.
+ When you receive mail locally, the operating system places incoming
+mail for you in a file that we call your @dfn{inbox}. When you start
+up Rmail, it runs a C program called @code{movemail} to copy the new
+messages from your local inbox into your primary Rmail file, which
+also contains other messages saved from previous Rmail sessions. It
+is in this file that you actually read the mail with Rmail. This
+operation is called @dfn{getting new mail}. You can get new mail at
+any time in Rmail by typing @kbd{g}.
@vindex rmail-primary-inbox-list
@cindex @env{MAIL} environment variable
or @file{/usr/mail/@var{username}}, depending on your operating system.
To see what the default is on your system, use @kbd{C-h v
-rmail-primary-inbox @key{RET}}. You can specify the inbox file(s) for
+rmail-primary-inbox-list @key{RET}}. You can specify the inbox file(s) for
any Rmail file with the command @code{set-rmail-inbox-list}; see
@ref{Rmail Files}.
as its internal format. However, the Rmail file will still be separate
from the inbox file, even on systems where their format is the same.
+@vindex rmail-preserve-inbox
+ When getting new mail, Rmail first copies the new mail from the inbox
+file to the Rmail file; then it saves the Rmail file; then it truncates
+the inbox file. This way, a system crash may cause duplication of mail
+between the inbox and the Rmail file, but cannot lose mail. If
+@code{rmail-preserve-inbox} is non-@code{nil}, then Rmail will copy new
+mail from the inbox file to the Rmail file without truncating the inbox
+file. You may wish to set this, for example, on a portable computer you
+use to check your mail via POP while traveling, so that your mail will
+remain on the server and you can save it later on your workstation.
+
+ In some cases, Rmail copies the new mail from the inbox file
+indirectly. First it runs the @code{movemail} program to move the mail
+from the inbox to an intermediate file called
+@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from
+that file, saves the Rmail file, and only then deletes the intermediate
+file. If there is a crash at the wrong time, this file continues to
+exist, and Rmail will use it again the next time it gets new mail from
+that inbox.
+
+ If Rmail is unable to convert the data in
+@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
+to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
+name unique) so that Rmail will not have trouble with the data again.
+You should look at the file, find whatever message confuses Rmail
+(probably one that includes the control-underscore character, octal code
+037), and delete it. Then you can use @kbd{1 g} to get new mail from
+the corrected file.
+
@node Rmail Files
@section Multiple Rmail Files
inbox format; the output commands ascertain the file's format and write
the copied message in that format.
- When copying a message to a file in Unix mail file format, these
-commands include whichever header fields are currently visible. Use the
-@kbd{t} command first, if you wish, to specify which headers to show
-(and copy).
-
The @kbd{o} and @kbd{C-o} commands differ in two ways: each has its
own separate default file name, and each specifies a choice of format to
use when the file does not already exist. The @kbd{o} command uses
the regular expression).
@vindex rmail-delete-after-output
- Copying a message gives the original copy of the message the
-@samp{filed} attribute, so that @samp{filed} appears in the mode line
-when such a message is current. If you like to keep just a single copy
-of every mail message, set the variable @code{rmail-delete-after-output}
-to @code{t}; then the @kbd{o} and @kbd{C-o} commands delete the original
-message after copying it. (You can undelete the original afterward if
-you wish.)
+ Copying a message with @kbd{o} or @kbd{C-o} gives the original copy
+of the message the @samp{filed} attribute, so that @samp{filed}
+appears in the mode line when such a message is current. @kbd{w}
+gives it the @samp{stored} attribute. If you like to keep just a
+single copy of every mail message, set the variable
+@code{rmail-delete-after-output} to @code{t}; then the @kbd{o},
+@kbd{C-o} and @kbd{w} commands delete the original message after
+copying it. (You can undelete the original afterward if you wish.)
Copying messages into files in system inbox format uses the header
fields that are displayed in Rmail at the time. Thus, if you use the
@item C-M-p @var{labels} @key{RET}
Move to the previous message that has one of the labels @var{labels}
(@code{rmail-previous-labeled-message}).
-@item C-M-l @var{labels} @key{RET}
+@item l @var{labels} @key{RET}
+@itemx C-M-l @var{labels} @key{RET}
Make a summary of all messages containing any of the labels @var{labels}
(@code{rmail-summary-by-labels}).
@end table
removed by undeletion commands (@pxref{Rmail Deletion}).
@item filed
Means the message has been copied to some other file. Assigned by the
-file output commands (@pxref{Rmail Files}).
+@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}).
+@item stored
+Assigned by the @kbd{w} file output command (@pxref{Rmail Output}).
@item answered
Means you have mailed an answer to the message. Assigned by the @kbd{r}
command (@code{rmail-reply}). @xref{Rmail Reply}.
headers and then send it. The variable
@code{rmail-retry-ignored-headers}, in the same format as
@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which
-headers are stripped from the failed message when retrying it; it
-defaults to @code{nil}.
+headers are stripped from the failed message when retrying it.
@kindex f @r{(Rmail)}
@findex rmail-forward
@dfn{Resending} is an alternative similar to forwarding; the
difference is that resending sends a message that is ``from'' the
original sender, just as it reached you---with a few added header fields
-@samp{Resent-from} and @samp{Resent-to} to indicate that it came via
+@samp{Resent-From} and @samp{Resent-To} to indicate that it came via
you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs
@code{rmail-forward}, which is programmed to invoke @code{rmail-resend}
if you provide a numeric argument.)
If you set the variable @code{rmail-mail-new-frame} to a
non-@code{nil} value, then all the Rmail commands to start sending a
message create a new frame to edit it in. This frame is deleted when
-you send the message, or when you use the @samp{Don't Send} item in the
+you send the message, or when you use the @samp{Cancel} item in the
@samp{Mail} menu.
All the Rmail commands to send a message use the mail-composition
A @dfn{summary} is a buffer containing one line per message to give
you an overview of the mail in an Rmail file. Each line shows the
-message number, the sender, the labels, and the subject. Almost all
-Rmail commands are valid in the summary buffer also; these apply to the
-message described by the current line of the summary. Moving point in
-the summary buffer selects messages as you move to their summary lines.
+message number and date, the sender, the line count, the labels, and
+the subject. Moving point in the summary buffer selects messages as
+you move to their summary lines. Almost all Rmail commands are valid
+in the summary buffer also; when used there, they apply to the message
+described by the current line of the summary.
A summary buffer applies to a single Rmail file only; if you are
editing multiple Rmail files, each one can have its own summary buffer.
@item C-M-t @var{topic} @key{RET}
Summarize messages that have a match for the specified regexp
@var{topic} in their subjects (@code{rmail-summary-by-topic}).
+@item C-M-s @var{regexp}
+Summarize messages whose headers and the subject line match the
+specified regular expression @var{regexp}
+(@code{rmail-summary-by-regexp}).
@end table
@kindex h @r{(Rmail)}
makes a partial summary mentioning only the messages whose subjects have
a match for the regular expression @var{topic}.
+@kindex C-M-s @r{(Rmail)}
+@findex rmail-summary-by-regexp
+ @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp})
+makes a partial summary which mentions only the messages whose headers
+(including the date and the subject lines) match the regular
+expression @var{regexp}.
+
Note that there is only one summary buffer for any Rmail file; making one
kind of summary discards any previously made summary.
Almost all Rmail commands work in the summary buffer as well as in the
Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current
-message, @kbd{u} undeletes, and @kbd{x} expunges. @kbd{o} and @kbd{C-o}
-output the current message to a file; @kbd{r} starts a reply to it. You
-can scroll the current message while remaining in the summary buffer
-using @key{SPC} and @key{DEL}.
+message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the
+summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u}
+serves as a repeat count. A negative argument reverses the meaning of
+@kbd{d} and @kbd{C-d}.) @kbd{o} and @kbd{C-o} output the current
+message to a file; @kbd{r} starts a reply to it. You can scroll the
+current message while remaining in the summary buffer using @key{SPC}
+and @key{DEL}.
The Rmail commands to move between messages also work in the summary
buffer, but with a twist: they move through the set of messages included
Move to the last line, and select its message.
@item <
Move to the first line, and select its message.
+@item j
+@itemx @key{RET}
+Select the message on the current line (ensuring that the RMAIL buffer
+appears on the screen). With argument @var{n}, select message number
+@var{n} and move to its line in the summary buffer; this signals an
+error if the message is not listed in the summary buffer.
@item M-s @var{pattern} @key{RET}
Search through messages for @var{pattern} starting with the current
message; select the message found, and move point in the summary buffer
means to show the full header.
@vindex rmail-highlighted-headers
- When used with a terminal that supports multiple fonts, Rmail
+ When the terminal supports multiple fonts or colors, Rmail
highlights certain header fields that are especially interesting---by
default, the @samp{From} and @samp{Subject} fields. The variable
@code{rmail-highlighted-headers} holds a regular expression that
-specifies the header fields to highlight; if it matches the beginning of
-a header field, that whole field is highlighted.
-
- If you specify unusual colors for your text foreground and background,
-the colors used for highlighting may not go well with them. If so,
-specify different colors for the @code{highlight} face. That is worth
-doing because the @code{highlight} face is used for other kinds of
-highlighting as well. @xref{Faces}, for how to do this.
-
- To turn off highlighting entirely in Rmail, set
+specifies the header fields to highlight; if it matches the beginning
+of a header field, that whole field is highlighted.
+
+ If you specify unusual colors for your text foreground and
+background, the colors used for highlighting may not go well with
+them. If so, specify different colors for the face
+@code{rmail-highlight-face}. @xref{Faces}, for how to do this. To
+turn off highlighting entirely in Rmail, set
@code{rmail-highlighted-headers} to @code{nil}.
-@findex goto-addr
-URLs in messages may be highlighted and activated for following with the
-mouse or keyboard by using the Goto-address package. Customize the hook
-@code{rmail-show-message-hook} to add @code{goto-addr}.
+ You can highlight and activate URLs in incoming messages by adding
+the function @code{goto-address} to the hook
+@code{rmail-show-message-hook}. Then you can browse these URLs by
+clicking on them with @kbd{Mouse-2} (or @kbd{Mouse-1} quickly) or by
+moving to one and typing @kbd{C-c @key{RET}}. @xref{Goto-address,
+Activating URLs, Activating URLs}.
+
+@node Rmail Coding
+@section Rmail and Coding Systems
+
+@cindex decoding mail messages (Rmail)
+ Rmail automatically decodes messages which contain non-@acronym{ASCII}
+characters, just as Emacs does with files you visit and with subprocess
+output. Rmail uses the standard @samp{charset=@var{charset}} header in
+the message, if any, to determine how the message was encoded by the
+sender. It maps @var{charset} into the corresponding Emacs coding
+system (@pxref{Coding Systems}), and uses that coding system to decode
+message text. If the message header doesn't have the @samp{charset}
+specification, or if @var{charset} is not recognized,
+Rmail chooses the coding system with the usual Emacs heuristics and
+defaults (@pxref{Recognize Coding}).
+
+@cindex fixing incorrectly decoded mail messages
+ Occasionally, a message is decoded incorrectly, either because Emacs
+guessed the wrong coding system in the absence of the @samp{charset}
+specification, or because the specification was inaccurate. For
+example, a misconfigured mailer could send a message with a
+@samp{charset=iso-8859-1} header when the message is actually encoded
+in @code{koi8-r}. When you see the message text garbled, or some of
+its characters displayed as empty boxes, this may have happened.
+
+@findex rmail-redecode-body
+ You can correct the problem by decoding the message again using the
+right coding system, if you can figure out or guess which one is
+right. To do this, invoke the @kbd{M-x rmail-redecode-body} command.
+It reads the name of a coding system, encodes the message body using
+whichever coding system was used to decode it before, then redecodes
+it using the coding system you specified. If you specified the right
+coding system, the result should be readable.
+
+ Decoding and encoding using the wrong coding system is lossless for
+most encodings, in particular with 8-bit encodings such as iso-8859 or
+koi8. So, if the initial attempt to redecode the message didn't
+result in a legible text, you can try other coding systems until you
+succeed.
+
+ With some coding systems, notably those from the iso-2022 family,
+information can be lost in decoding, so that encoding the message
+again won't bring back the original incoming text. In such a case,
+@code{rmail-redecode-body} cannot work. However, the problems that
+call for use of @code{rmail-redecode-body} rarely occur with those
+coding systems. So in practice the command works when you need it.
@node Rmail Editing
@section Editing Within a Message
runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). It adds the
attribute @samp{edited} to the message. It also displays the full
headers of the message, so that you can edit the headers as well as the
-body of the message, and your changes in the the headers will be
+body of the message, and your changes in the headers will be
permanent.
@node Rmail Digest
When you receive a digest message, the most convenient way to read it is
to @dfn{undigestify} it: to turn it back into many individual messages.
Then you can read and delete the individual messages as it suits you.
-
- To do this, select the digest message and type the command @kbd{M-x
+To do this, select the digest message and type the command @kbd{M-x
undigestify-rmail-message}. This extracts the submessages as separate
Rmail messages, and inserts them following the digest. The digest
message itself is flagged as deleted.
@node Out of Rmail
@section Converting an Rmail File to Inbox Format
+@cindex Babyl format to Inbox format
+@cindex converting Rmail file to mailbox format
@findex unrmail
The command @kbd{M-x unrmail} converts a file in Rmail format to inbox
-format (also known as the system mailbox format), so that you can use it
-with other mail-editing tools. You must specify two arguments, the name
-of the Rmail file and the name to use for the converted file. @kbd{M-x
-unrmail} does not alter the Rmail file itself.
+format (also known as the system mailbox, or mbox, format), so that
+you can use it with other mail-editing tools. You must specify two
+arguments, the name of the Rmail file and the name to use for the
+converted file. @kbd{M-x unrmail} does not alter the Rmail file itself.
+
+@pindex b2m
+ @kbd{M-x unrmail} is useful if you can run Emacs on the machine
+where the Rmail file resides, or can access the Rmail file remotely
+(@pxref{Remote Files}) from a machine where Emacs is installed. If
+accessing Rmail files from Emacs is impossible, you can use the
+@command{b2m} program instead. @command{b2m} is part of the Emacs
+distribution, it is installed into the same directory where all the
+other auxiliary programs (@command{etags} etc.) are installed, and its
+source is available in the Emacs source distribution, so that you
+could copy the source to the target machine and compile it there.
+
+ To convert a file @file{@var{babyl-file}} into @file{@var{mbox-file}},
+invoke @command{b2m} like this:
+
+@example
+ b2m < @var{babyl-file} > @var{mbox-file}
+@end example
@node Rmail Rot13
@section Reading Rot13 Messages
which applies the code when displaying the text.
@node Movemail
-@section @code{movemail} and POP
+@section @code{movemail} program
@cindex @code{movemail} program
-@vindex rmail-preserve-inbox
- When getting new mail, Rmail first copies the new mail from the inbox
-file to the Rmail file; then it saves the Rmail file; then it truncates
-the inbox file. This way, a system crash may cause duplication of mail
-between the inbox and the Rmail file, but cannot lose mail. If
-@code{rmail-preserve-inbox} is non-@code{nil}, then Rmail will copy new
-mail from the inbox file to the Rmail file without truncating the inbox
-file. You may wish to set this, for example, on a portable computer you
-use to check your mail via POP while traveling, so that your mail will
-remain on the server and you can save it later on your workstation.
+ When invoked for the first time, Rmail attempts to locate the
+@code{movemail} program and determine its version. There are two
+versions of @code{movemail} program: the native one, shipped with GNU
+Emacs (the ``emacs version'') and the one included in GNU mailutils
+(the ``mailutils version,'' @pxref{movemail,,,mailutils,GNU
+mailutils}). They support the same command line syntax and the same
+basic subset of options. However, the @samp{mailutils} version offers
+additional features.
+
+ The Emacs version of @code{movemail} is able to retrieve mail from
+usual UNIX mailbox formats and from remote mailboxes using the POP3
+protocol.
+
+ The Mailutils version is able to handle a wide set of mailbox
+formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH}
+mailboxes, etc. It is able to retrieve remote mail using POP3 or
+IMAP4 protocol, and can retrieve mail from them using a TLS encrypted
+channel. It also accepts mailbox argument in the @acronym{URL} form.
+The detailed description of mailbox @acronym{URL}s can be found in
+@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL}
+is:
+
+@smallexample
+@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
+@end smallexample
- In some cases, Rmail copies the new mail from the inbox file
-indirectly. First it runs the @code{movemail} program to move the mail
-from the inbox to an intermediate file called
-@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from
-that file, saves the Rmail file, and only then deletes the intermediate
-file. If there is a crash at the wrong time, this file continues to
-exist, and Rmail will use it again the next time it gets new mail from
-that inbox.
+@noindent
+where square brackets denote optional elements.
+@table @var
+@item proto
+Specifies the @dfn{mailbox protocol}, or @dfn{format} to
+use. The exact semantics of the rest of @acronym{URL} elements depends
+on the actual value of @var{proto}.
+
+@item user
+User name to access the remote mailbox.
+
+@item password
+User password to access the remote mailbox.
+
+@item host-or-file-name
+Hostname of the remote server for remote mailboxes or file name of a
+local mailbox.
+@end table
+
+@var{Proto} can be one of:
+
+@table @asis
+@item mbox
+Usual UNIX mailbox format. In this case, neither @var{user} nor
+@var{pass} are used, and @var{host-or-file-name} denotes the file name of
+the mailbox file, e.g., @code{mbox://var/spool/mail/smith}.
+
+@item mh
+A local mailbox in the @acronym{MH} format. @var{User} and
+@var{pass} are not used. @var{Host-or-file-name} denotes the name of
+@acronym{MH} folder, e.g., @code{mh://Mail/inbox}.
+
+@item maildir
+A local mailbox in the @acronym{maildir} format. @var{User} and
+@var{pass} are not used, and @var{host-or-file-name} denotes the name of
+@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}.
+
+@item file
+Any local mailbox format. Its actual format is detected automatically
+by @code{movemail}.
+
+@item pop
+A remote mailbox to be accessed via POP3 protocol. @var{User}
+specifies the remote user name to use, @var{pass} may be used to
+specify the user password, @var{host-or-file-name} is the name or IP
+address of the remote mail server to connect to; e.g.,
+@code{pop://smith:guessme@@remote.server.net}.
+
+@item imap
+A remote mailbox to be accessed via IMAP4 protocol. @var{User}
+specifies the remote user name to use, @var{pass} may be used to
+specify the user password, @var{host-or-file-name} is the name or IP
+address of the remote mail server to connect to;
+e.g., @code{imap://smith:guessme@@remote.server.net}.
+@end table
+
+ Alternatively, you can specify the file name of the mailbox to use.
+This is equivalent to specifying the @samp{file} protocol:
+
+@smallexample
+/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user}
+@end smallexample
+
+@vindex rmail-movemail-program
+@vindex rmail-movemail-search-path
+ The variable @code{rmail-movemail-program} controls which version of
+@code{movemail} to use. If that is a string, it specifies the
+absolute file name of the @code{movemail} executable. If it is
+@code{nil}, Rmail searches for @code{movemail} in the directories
+listed in @code{rmail-movemail-search-path} and @code{exec-path}, then
+in @code{exec-directory}.
+
+@node Remote Mailboxes
+@section Retrieving Mail from Remote Mailboxes
@pindex movemail
- If Rmail is unable to convert the data in
-@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file
-to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the
-name unique) so that Rmail will not have trouble with the data again.
-You should look at the file, find whatever message confuses Rmail
-(probably one that includes the control-underscore character, octal code
-037), and delete it. Then you can use @kbd{1 g} to get new mail from
-the corrected file.
Some sites use a method called POP for accessing users' inbox data
-instead of storing the data in inbox files. @code{movemail} can work
-with POP if you compile it with the macro @code{MAIL_USE_POP} defined.
-(You can achieve that by specifying @samp{--with-pop} when you run
-@code{configure} during the installation of Emacs.)
-@code{movemail} only works with POP3, not with older
+instead of storing the data in inbox files. The @code{Emacs
+movemail} can work with POP if you compile it with the macro
+@code{MAIL_USE_POP} defined. (You can achieve that by specifying
+@samp{--with-pop} when you run @code{configure} during the
+installation of Emacs.)
+
+The @code{Mailutils movemail} by default supports POP, unless configured
+with @samp{--disable-pop} option.
+
+Both versions of @code{movemail} only work with POP3, not with older
versions of POP.
@cindex @env{MAILHOST} environment variable
-@cindex POP inboxes
- Assuming you have compiled and installed @code{movemail}
-appropriately, you can specify a POP inbox by using a ``file name'' of
-the form @samp{po:@var{username}}, in the inbox list of an Rmail file.
-@code{movemail} handles such a name by opening a connection to the POP
-server. The @env{MAILHOST} environment variable specifies the machine
-to look for the server on; alternatively, you can specify the POP server
-host name as part of the mailbox name using the syntax
-@samp{po:@var{username}:@var{hostname}}.
-
+@cindex POP mailboxes
+ No matter which flavor of @code{movemail} you use, you can specify
+POP inbox by using POP @dfn{URL} (@pxref{Movemail}). A POP
+@acronym{URL} is a ``file name'' of the form
+@samp{pop://@var{username}@@@var{hostname}}, where
+@var{hostname} is the host name or IP address of the remote mail
+server and @var{username} is the user name on that server.
+Additionally, you may specify the password in the mailbox @acronym{URL}:
+@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this
+case, @var{password} takes preference over the one set by
+@code{rmail-remote-password}. This is especially useful if you have
+several remote mailboxes with different passwords.
+
+ For backward compatibility Rmail also supports two alternative ways
+of specifying remote POP mailboxes. Specifying inbox name in the form
+@samp{po:@var{username}:@var{hostname}} is equivalent to
+@samp{pop://@var{username}@@@var{hostname}}. Alternatively, you may set
+a ``file name'' of @samp{po:@var{username}} in the inbox list of an
+Rmail file. @code{Movemail} will handle such a name by opening a
+connection to the POP server. The @env{MAILHOST} environment variable
+will in this case specify the machine to look for the server on.
+
+@cindex IMAP mailboxes
+ Another method for accessing remote mailboxes is IMAP. This method is
+supported only by the @code{mailutils movemail}. To specify an IMAP
+mailbox in the inbox list, use the following mailbox @acronym{URL}:
+@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The
+@var{password} part is optional, as described above.
+
+@vindex rmail-remote-password
+@vindex rmail-remote-password-required
@vindex rmail-pop-password
@vindex rmail-pop-password-required
- Accessing mail via POP may require a password. If the variable
-@code{rmail-pop-password} is non-@code{nil}, it specifies the password
-to use for POP. Alternatively, if @code{rmail-pop-password-required} is
-non-@code{nil}, then Rmail asks you for the password to use.
+ Accessing a remote mailbox may require a password. Rmail uses the
+following algorithm to retrieve it:
+
+@enumerate
+@item
+If the @var{password} is present in mailbox URL (see above), it is
+used.
+@item
+If the variable @code{rmail-remote-password} is non-@code{nil}, its
+value is used.
+@item
+Otherwise, if @code{rmail-remote-password-required} is non-@code{nil},
+then Rmail will ask you for the password to use.
+@item
+Otherwise, Rmail assumes no password is required.
+@end enumerate
+
+ For compatibility with previous versions, @code{rmail-pop-password}
+and @code{rmail-pop-password-required} may be used instead of
+@code{rmail-remote-password} and @code{rmail-remote-password-required}.
@vindex rmail-movemail-flags
If you need to pass additional command-line flags to @code{movemail},
POP mail when @code{rmail-pop-password} and
@code{rmail-pop-password-required} are unset.
-@cindex POP inboxes in reverse order
+@cindex reverse order in POP inboxes
Some POP servers store messages in reverse order. If your server does
this, and you would rather read your mail in the order in which it was
received, you can tell @code{movemail} to reverse the order of
downloaded messages by adding the @samp{-r} flag to
@code{rmail-movemail-flags}.
+
+@cindex TLS encryption (Rmail)
+ @code{Mailutils movemail} supports TLS encryption. If you wish to
+use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}.
+
+@node Other Mailbox Formats
+@section Retrieving Mail from Local Mailboxes in Various Formats
+
+ If your incoming mail is stored on a local machine in a format other
+than UNIX mailbox, you will need the @code{mailutils movemail} to retrieve
+it. @xref{Movemail}, for the detailed description of @code{movemail}
+versions.
+
+ For example, to retrieve mail from a @code{maildir} inbox located in
+@file{/var/spool/mail/in}, you would set the following in Rmail inbox list:
+
+@smallexample
+maildir://var/spool/mail/in
+@end smallexample
+
+@ignore
+ arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23
+@end ignore
HCoop / bpt / emacs.git / blobdiff