[Emacs-diffs] emacs/doc/emacs ChangeLog rmail.texi

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       09/03/04 04:15:39

Modified files:
        doc/emacs      : ChangeLog rmail.texi 

Log message:
        (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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/emacs/ChangeLog?cvsroot=emacs&r1=1.296&r2=1.297
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/emacs/rmail.texi?cvsroot=emacs&r1=1.15&r2=1.16

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/ChangeLog,v
retrieving revision 1.296
retrieving revision 1.297
diff -u -b -r1.296 -r1.297
--- ChangeLog   3 Mar 2009 08:18:53 -0000       1.296
+++ ChangeLog   4 Mar 2009 04:15:38 -0000       1.297
@@ -1,3 +1,19 @@
+2009-03-04  Glenn Morris  <address@hidden>
+
+       * 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  <address@hidden>
 
        * rmail.texi (Rmail Deletion): Revert previous change, which was

Index: rmail.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/rmail.texi,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -b -r1.15 -r1.16
--- rmail.texi  3 Mar 2009 08:18:54 -0000       1.15
+++ rmail.texi  4 Mar 2009 04:15:39 -0000       1.16
@@ -1010,37 +1010,44 @@
 
 @table @kbd
 @findex rmail-sort-by-date
address@hidden M-x rmail-sort-by-date
-Sort messages of current Rmail file by date.
address@hidden C-c C-s C-d
address@hidden M-x rmail-sort-by-date
+Sort messages of current Rmail buffer by date.
 
 @findex rmail-sort-by-subject
address@hidden M-x rmail-sort-by-subject
-Sort messages of current Rmail file by subject.
address@hidden C-c C-s C-s
address@hidden M-x rmail-sort-by-subject
+Sort messages of current Rmail buffer by subject.
 
 @findex rmail-sort-by-author
address@hidden M-x rmail-sort-by-author
-Sort messages of current Rmail file by author's name.
address@hidden C-c C-s C-a
address@hidden M-x rmail-sort-by-author
+Sort messages of current Rmail buffer by author's name.
 
 @findex rmail-sort-by-recipient
address@hidden M-x rmail-sort-by-recipient
-Sort messages of current Rmail file by recipient's names.
address@hidden C-c C-s C-r
address@hidden M-x rmail-sort-by-recipient
+Sort messages of current Rmail buffer by recipient's names.
 
 @findex rmail-sort-by-correspondent
address@hidden M-x rmail-sort-by-correspondent
-Sort messages of current Rmail file by the name of the other
address@hidden C-c C-s C-c
address@hidden M-x rmail-sort-by-correspondent
+Sort messages of current Rmail buffer by the name of the other
 correspondent.
 
 @findex rmail-sort-by-lines
address@hidden M-x rmail-sort-by-lines
-Sort messages of current Rmail file by size (number of lines).
-
address@hidden rmail-sort-by-keywords
address@hidden M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET}
-Sort messages of current Rmail file by labels.  The argument
address@hidden C-c C-s C-l
address@hidden M-x rmail-sort-by-lines
+Sort messages of current Rmail buffer by number of lines.
+
address@hidden rmail-sort-by-labels
address@hidden C-c C-s C-k @key{RET} @var{labels} @key{RET}
address@hidden 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
address@hidden  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:
+
address@hidden FIXME goto-addr.el commentary says to use goto-address instead.
address@hidden
+(add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1)))
address@hidden smallexample
+
address@hidden
+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
address@hidden  @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
address@hidden 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,''
address@hidden,,,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
address@hidden,,,mailutils,Mailbox URL Formats}.  In short, a @acronym{URL}
-is:
address@hidden,,,mailutils,Mailbox URL Formats}.  In short, a @acronym{URL} is:
 
 @smallexample
 @var{proto}://address@hidden:@var{password}]@@address@hidden
@@ -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
address@hidden defined.  (You can achieve that by specifying
address@hidden 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
address@hidden  This is especially useful if you have
-several remote mailboxes with different passwords.
address@hidden (see below).  This is especially useful
+if you have several remote mailboxes with different passwords.
+
+  For backward compatibility, Rmail also supports an alternative way of
+specifying remote POP mailboxes.  Specifying an inbox name in the form
address@hidden:@var{username}:@var{hostname}} is equivalent to
address@hidden://@var{username}@@@var{hostname}}.  If you omit the
address@hidden:hostname} part, the @env{MAILHOST} environment variable specifies
+the machine on which to look for the POP server.
 
-  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
address@hidden://@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.
address@hidden 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
address@hidden rmail-pop-password
address@hidden 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.
address@hidden
 If the variable @code{rmail-remote-password} is address@hidden, its
 value is used.
 @item
-Otherwise, if @code{rmail-remote-password-required} is address@hidden,
-then Rmail will ask you for the password to use.
address@hidden
-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
address@hidden and @code{rmail-pop-password-required} may
-be used instead of @code{rmail-remote-password} and
address@hidden
-
 @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
address@hidden are unset.
+Kerberos authentication (the Emacs @code{movemail} does so if Emacs was
+configured with the option @code{--with-kerberos} or
address@hidden).  If it is supported, it is used by default
+whenever you attempt to retrieve POP mail when
address@hidden 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