Mercurial > emacs

--- a/doc/emacs/ChangeLog	Tue Mar 03 22:26:24 2009 +0000
+++ b/doc/emacs/ChangeLog	Wed Mar 04 04:15:38 2009 +0000
@@ -1,3 +1,19 @@
+2009-03-04  Glenn Morris  <rgm@gnu.org>
+
+	* rmail.texi (Rmail Sorting): Add the keybindings associated with each
+	sort command.  Fix `rmail-sort-by-labels' name.  Mention sorting from
+	summary.  Mention sorts cannot be undone.
+	(Rmail Display): Give an example of how to use goto-address-mode.
+	(Rmail Editing): It's keybindings that are redefined, not commands.
+	Fix some typos.
+	(Movemail): Some minor rewording.
+	(Remote Mailboxes): Emacs movemail supports pop by default.
+	Fix some minor grammatical issues.  The "two alternative ways" to
+	specify a POP mailbox are really just one.  Remove all reference to the
+	variables rmail-pop-password and rmail-pop-password-required, obsolete
+	since Emacs 22.1.  Clarify the four password steps.  Emacs movemail
+	can support Kerberos.
+
 2009-03-03  Glenn Morris  <rgm@gnu.org>

 	* rmail.texi (Rmail Deletion): Revert previous change, which was
--- a/doc/emacs/rmail.texi	Tue Mar 03 22:26:24 2009 +0000
+++ b/doc/emacs/rmail.texi	Wed Mar 04 04:15:38 2009 +0000
@@ -1010,37 +1010,44 @@

 @table @kbd
 @findex rmail-sort-by-date
-@item M-x rmail-sort-by-date
-Sort messages of current Rmail file by date.
+@item C-c C-s C-d
+@itemx M-x rmail-sort-by-date
+Sort messages of current Rmail buffer by date.

 @findex rmail-sort-by-subject
-@item M-x rmail-sort-by-subject
-Sort messages of current Rmail file by subject.
+@item C-c C-s C-s
+@itemx M-x rmail-sort-by-subject
+Sort messages of current Rmail buffer by subject.

 @findex rmail-sort-by-author
-@item M-x rmail-sort-by-author
-Sort messages of current Rmail file by author's name.
+@item C-c C-s C-a
+@itemx M-x rmail-sort-by-author
+Sort messages of current Rmail buffer by author's name.

 @findex rmail-sort-by-recipient
-@item M-x rmail-sort-by-recipient
-Sort messages of current Rmail file by recipient's names.
+@item C-c C-s C-r
+@itemx M-x rmail-sort-by-recipient
+Sort messages of current Rmail buffer by recipient's names.

 @findex rmail-sort-by-correspondent
-@item M-x rmail-sort-by-correspondent
-Sort messages of current Rmail file by the name of the other
+@item C-c C-s C-c
+@itemx M-x rmail-sort-by-correspondent
+Sort messages of current Rmail buffer by the name of the other
 correspondent.

 @findex rmail-sort-by-lines
-@item M-x rmail-sort-by-lines
-Sort messages of current Rmail file by size (number of lines).
+@item C-c C-s C-l
+@itemx M-x rmail-sort-by-lines
+Sort messages of current Rmail buffer by number of lines.

-@findex rmail-sort-by-keywords
-@item M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET}
-Sort messages of current Rmail file by labels.  The argument
+@findex rmail-sort-by-labels
+@item C-c C-s C-k @key{RET} @var{labels} @key{RET}
+@itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET}
+Sort messages of current Rmail buffer by labels.  The argument
 @var{labels} should be a comma-separated list of labels.  The order of
 these labels specifies the order of messages; messages with the first
 label come first, messages with the second label come second, and so on.
-Messages which have none of these labels come last.
+Messages that have none of these labels come last.
 @end table

   The Rmail sort commands perform a @emph{stable sort}: if there is no
@@ -1050,10 +1057,18 @@
 @code{rmail-sort-by-author}, messages from the same author appear in
 order by date.

-  With a numeric argument, all these commands reverse the order of
+  With a prefix argument, all these commands reverse the order of
 comparison.  This means they sort messages from newest to oldest, from
 biggest to smallest, or in reverse alphabetical order.

+  The same keys in the summary buffer run similar functions; for
+example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}.
+Note that these commands always sort the whole Rmail buffer, even if the
+summary is only showing a subset of messages.
+
+  Note that you cannot undo a sort, so you may wish to save the Rmail
+buffer before sorting it.
+
 @node Rmail Display
 @section Display of Messages

@@ -1107,12 +1122,18 @@
 Customize the face @code{rmail-highlight} to adjust the style of the
 highlighting.

-  You can highlight and activate URLs in incoming messages by adding
-the function @code{goto-address-mode} 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
-mode, Activating URLs, Activating URLs}.
+  You can highlight and activate URLs in incoming messages using
+Goto Address mode:
+
+@c FIXME goto-addr.el commentary says to use goto-address instead.
+@smallexample
+(add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1)))
+@end smallexample
+
+@noindent
+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 mode, Activating URLs, Activating URLs}.

 @node Rmail Coding
 @section Rmail and Coding Systems
@@ -1149,7 +1170,7 @@
 @node Rmail Editing
 @section Editing Within a Message

-  Most of the usual Emacs commands are available in Rmail mode, though a
+  Most of the usual Emacs keybindings are available in Rmail mode, though a
 few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for
 other purposes.  However, the Rmail buffer is normally read only, and
 most of the letters are redefined as Rmail commands.  If you want to
@@ -1167,11 +1188,10 @@
 same as Text mode.  The mode line indicates this change.

   In Rmail Edit mode, letters insert themselves as usual and the Rmail
-commands are not available.  You can edit message body and header
+commands are not available.  You can edit the message body and header
 fields.  When you are finished editing the message, type @kbd{C-c C-c}
 to switch back to Rmail mode.  Alternatively, you can return to Rmail
-mode but cancel all the editing that you have done, by typing @kbd{C-c
-C-]}.
+mode but cancel any editing that you have done, by typing @kbd{C-c C-]}.

 @vindex rmail-edit-mode-hook
   Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then
@@ -1221,27 +1241,27 @@
 @section @code{movemail} program
 @cindex @code{movemail} program

-  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 Mailutils version offers
-additional features.
+  Rmail uses the @code{movemail} program to move mail from your inbox to
+your Rmail file (@pxref{Rmail Inbox}).  When loaded for the first time,
+Rmail attempts to locate the @code{movemail} program and determine its
+version.  There are two versions of the @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
+Mailutils version offers additional features.

-  The Emacs version of @code{movemail} is able to retrieve mail from
+  The Emacs version of @code{movemail} is able to retrieve mail from the
 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
+mailboxes, etc.  It is able to access remote mailboxes using the 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.
+channel.  It also accepts mailbox arguments in @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:
+@ref{URL,,,mailutils,Mailbox URL Formats}.  In short, a @acronym{URL} is:

 @smallexample
 @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name}
@@ -1326,14 +1346,12 @@
 @pindex movemail

   Some sites use a method called POP for accessing users' inbox data
-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.)
+instead of storing the data in inbox files.  By default, the @code{Emacs
+movemail} can work with POP (unless the Emacs @code{configure} script
+was run with the option @samp{--without-pop}).

-The Mailutils @code{movemail} by default supports POP, unless it was
-configured with @samp{--disable-pop} option.
+Similarly, the Mailutils @code{movemail} by default supports POP, unless
+it was configured with the @samp{--disable-pop} option.

 Both versions of @code{movemail} only work with POP3, not with older
 versions of POP.
@@ -1341,7 +1359,7 @@
 @cindex @env{MAILHOST} environment variable
 @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
+a POP inbox by using a 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
@@ -1349,18 +1367,17 @@
 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.
+@code{rmail-remote-password} (see below).  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.  First, specifying an 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.  In this case, the @env{MAILHOST}
-environment variable specifies the machine on which to look for the
-POP server.
+  For backward compatibility, Rmail also supports an alternative way of
+specifying remote POP mailboxes.  Specifying an inbox name in the form
+@samp{po:@var{username}:@var{hostname}} is equivalent to
+@samp{pop://@var{username}@@@var{hostname}}.  If you omit the
+@var{:hostname} part, the @env{MAILHOST} environment variable specifies
+the machine on which to look for the POP server.
+
+@c FIXME mention --with-hesiod "support Hesiod to get the POP server host"?

 @cindex IMAP mailboxes
   Another method for accessing remote mailboxes is IMAP.  This method is
@@ -1371,30 +1388,23 @@

 @vindex rmail-remote-password
 @vindex rmail-remote-password-required
-@vindex rmail-pop-password
-@vindex rmail-pop-password-required
   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
+If a @var{password} is present in the mailbox URL (see above), it is
 used.
 @item
+If the variable @code{rmail-remote-password-required} is @code{nil},
+Rmail assumes no password is required.
+@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.
+Otherwise, Rmail will ask you for the password to use.
 @end enumerate

-  For compatibility with previous versions, the variables
-@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},
 set the variable @code{rmail-movemail-flags} a list of the flags you
@@ -1403,10 +1413,12 @@

 @cindex Kerberos POP authentication
   The @code{movemail} program installed at your site may support
-Kerberos authentication.  If it is
-supported, it is used by default whenever you attempt to retrieve
-POP mail when @code{rmail-pop-password} and
-@code{rmail-pop-password-required} are unset.
+Kerberos authentication (the Emacs @code{movemail} does so if Emacs was
+configured with the option @code{--with-kerberos} or
+@code{--with-kerberos5}).  If it is supported, it is used by default
+whenever you attempt to retrieve POP mail when
+@code{rmail-remote-password} and @code{rmail-remote-password-required}
+are unset.

 @cindex reverse order in POP inboxes
   Some POP servers store messages in reverse order.  If your server does