(Mail Format): Fix typo. Add index entry for mail-header-separator.

(Mail Headers): Put info about initialization and changing in one place
at the start.  Update FCC section for mbox Rmail.  Clarify From
section, mention mail-setup-with-from.  Clarify Reply-to section.
Add Mail-followup-to and mail-mailing-lists.  Clarify References section.
(Mail Aliases): Update example, make less contentious.
Update for name change of mail-interactive-insert-alias.
(Mail Mode): Remove mention of `%' as a word separator.
(Mail Sending): Mention mail-send-hook.  Mention Mailclient.
(Header Editing): Add reply-to, mail-reply-to, and mail-followup-to commands.
Clarify FCC handling.  In mail-complete, add reference to
Mail Aliases section, and mention mail-complete-function.
(Citing Mail): Mention mail-yank-ignored-headers and mail-citation-hook.
(Mail Mode Misc): Clarify the mail-signature function.  Add basic
signature netiquette.  Explain how the mail hooks work when continuing
a composition.
(Mail Amusements): Internationalize the spook section a bit.
Remove the spook mail-setup-hook example, since it doesn't work well.
Mention fortune-file.
(Mail Methods): Mention read-mail-command.

2 files changed, 194 insertions, 87 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 80a76adbd40..6a1df7168e2 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,7 +1,32 @@
+2009-03-14  Glenn Morris  <rgm@gnu.org>
+
+        * sending.texi (Mail Format): Fix typo.  Add index entry for
+        mail-header-separator.
+        (Mail Headers): Put info about initialization and changing in one place
+        at the start.  Update FCC section for mbox Rmail.  Clarify From
+        section, mention mail-setup-with-from.  Clarify Reply-to section.
+        Add Mail-followup-to and mail-mailing-lists.  Clarify References
+        section.
+        (Mail Aliases): Update example, make less contentious.
+        Update for name change of mail-interactive-insert-alias.
+        (Mail Mode): Remove mention of `%' as a word separator.
+        (Mail Sending): Mention mail-send-hook.  Mention Mailclient.
+        (Header Editing): Add reply-to, mail-reply-to, and mail-followup-to
+        commands.  Clarify FCC handling.  In mail-complete, add reference to
+        Mail Aliases section, and mention mail-complete-function.
+        (Citing Mail): Mention mail-yank-ignored-headers and mail-citation-hook.
+        (Mail Mode Misc): Clarify the mail-signature function.  Add basic
+        signature netiquette.  Explain how the mail hooks work when continuing
+        a composition.
+        (Mail Amusements): Internationalize the spook section a bit.
+        Remove the spook mail-setup-hook example, since it doesn't work well.
+        Mention fortune-file.
+        (Mail Methods): Mention read-mail-command.
+
 2009-03-14  David Reitter <david.reitter@gmail.com>
 
-        * macos.texi (Mac / GNUstep Basics): remove references to Prefs panel
-        and NS resources following recent changes. 
+        * macos.texi (Mac / GNUstep Basics): Remove references to Prefs panel
+        and NS resources following recent changes.
 
 2009-03-10  Jason Rumney  <jasonr@gnu.org>
 
diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index 56d158eb398..47ecc021f3c 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -62,6 +62,8 @@ with each mail buffer independently.
 directory for mail buffers, and also says where to put their auto-save
 files.
 
+@c Not mentioned: mail-bury-selects-summary.  Really an Rmail feature.
+
 @ignore
 @c Commented out because it is not user-oriented;
 @c it doesn't say how to do some job.  -- rms.
@@ -77,7 +79,7 @@ separate manual.  It may be useful for looking up names and addresses.
 
 @menu
 * Format: Mail Format.       Format of the mail being composed.
-* Headers: Mail Headers.     Details of permitted mail header fields.
+* Headers: Mail Headers.     Details of some standard mail header fields.
 * Aliases: Mail Aliases.     Abbreviating and grouping mail addresses.
 * Mode: Mail Mode.           Special commands for editing mail being composed.
 * Amuse: Mail Amusements.    Distracting the NSA; adding fortune messages.
@@ -94,10 +96,11 @@ automatically when you send the message.  Others, such as the recipient
 names, must be specified by you in order to send the message properly.
 
   In the mail buffer, you can insert and edit header fields using
-ordinary editing commands.  Mail mode provides a commands to help you
+ordinary editing commands.  Mail mode provides commands to help you
 edit some header fields, and some are preinitialized in the buffer
 automatically when appropriate.
 
+@vindex mail-header-separator
   The line in the buffer that says
 
 @example
@@ -118,7 +121,7 @@ might look like.
 To: gnu@@gnu.org
 CC: lungfish@@spam.org, byob@@spam.org
 Subject: The Emacs Manual
---Text follows this line--
+--text follows this line--
 Please ignore this message.
 @end example
 
@@ -133,7 +136,10 @@ colon and optional whitespace comes the contents of the field.
 
   You can use any name you like for a header field, but normally people
 use only standard field names with accepted meanings.  Here is a table
-of fields commonly used in outgoing messages.
+of fields commonly used in outgoing messages.  Emacs preinitializes some
+of these when you start to compose a mail, depending on various options
+you can set.  You can delete or alter any header field before you send
+the message, if you wish.
 
 @table @samp
 @item To
@@ -166,11 +172,12 @@ copy of every message to some other @var{address}, set the variable
 
 @item FCC
 This field contains the name of one file and directs Emacs to append a
-copy of the message to that file when you send the message.  If the file
-is in Rmail format, Emacs writes the message in Rmail format; otherwise,
-Emacs writes the message in system mail file format.  To specify
-more than one file, use several @samp{FCC} fields, with one file
-name in each field.
+copy of the message to that file when you send the message.  Emacs
+writes the message in mbox format, unless the file is in Babyl format
+(used by Rmail before Emacs 23), in which case Emacs writes Babyl.  If
+an Rmail buffer is visiting the file, Emacs updates it accordingly.
+To specify more than one file, use several @samp{FCC} fields, with one
+file name in each field.
 
 @vindex mail-archive-file-name
 To put a fixed file name in the @samp{FCC} field each time you start
@@ -180,11 +187,16 @@ editing an outgoing message, set the variable
 file when it is sent.
 
 @item From
-Use the @samp{From} field to say who you are, when the account you are
-using to send the mail is not your own.  The contents of the @samp{From}
-field should be a valid mailing address, since replies will normally go
-there.  If you don't specify the @samp{From} field yourself, Emacs uses
-the value of @code{user-mail-address} as the default.
+Use the @samp{From} field to say who you are.  You might need to change
+this if the account you are using to send the mail is not your own.  The
+contents of the @samp{From} field should be a valid mailing address,
+since replies will normally go there.  
+
+@vindex mail-setup-with-from
+Emacs initializes this field (unless the variable
+@code{mail-setup-with-from} is @code{nil}) using
+@code{user-mail-address} as the default.  If there is no @samp{From}
+field when you send a mail, Emacs adds one.
 
 @item Reply-to
 Use this field to direct replies to a different address.  Most
@@ -197,11 +209,25 @@ any problems your @samp{From} address may cause for replies.
 @vindex mail-default-reply-to
 To put a fixed @samp{Reply-to} address into every outgoing message, set
 the variable @code{mail-default-reply-to} to that address (as a string).
-Then @code{mail} initializes the message with a @samp{Reply-to} field as
-specified.  You can delete or alter that header field before you send
-the message, if you wish.  When Emacs starts up, if the environment
-variable @env{REPLYTO} is set, @code{mail-default-reply-to} is
-initialized from that environment variable.
+Then Emacs initializes the message with a @samp{Reply-to} field as
+specified.  When you first compose a mail, if
+@code{mail-default-reply-to} is @code{nil}, it is initialized from the
+environment variable @env{REPLYTO}.
+
+@item Mail-followup-to
+  This field contains one or more addresses.  It is typically used when
+you reply to a message from a mailing list that you are subscribed to.
+It usually indicates that you want replies to go to the list, and that
+you do not need an extra copy sent directly to you.
+
+@vindex mail-mailing-lists
+  The variable @code{mail-mailing-lists} holds a list of mailing list
+addresses that you are subscribed to.  If it is non-@code{nil}, Emacs
+inserts an appropriate @samp{Mail-followup-to} header when sending mail
+to a mailing list.
+
+@c There is also "Sent-via", added by C-c C-v, but it does not seem
+@c particularly useful (?).
 
 @item In-reply-to
 This field contains a piece of text describing the message you are
@@ -211,8 +237,9 @@ when you reply to a message in Rmail, and you never need to
 think about it (@pxref{Rmail}).
 
 @item References
-This field lists the message IDs of related previous messages.  Rmail
-sets up this field automatically when you reply to a message.
+This field lists the message IDs of related previous messages (a message
+ID is a unique identifier generated when a message is sent).  Rmail sets
+up this field automatically when you reply to a message.
 @end table
 
   The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear
@@ -233,8 +260,8 @@ To: foo@@here.net, this@@there.net,
 
 @vindex mail-from-style
   When you send the message, if you didn't write a @samp{From} field
-yourself, Emacs puts in one for you.  The variable
-@code{mail-from-style} controls the format:
+yourself, Emacs puts in one for you, using @code{user-mail-address}.
+The variable @code{mail-from-style} controls the format:
 
 @table @code
 @item nil
@@ -249,6 +276,9 @@ Use both email address and full name, as in:@*
 Allow the system to insert the @samp{From} field.
 @end table
 
+@c There is also mail-specify-envelope-from and mail-envelope-from, but
+@c these are probably not topics for the Emacs manual.
+
 @vindex mail-default-headers
   You can direct Emacs to insert certain default headers into the
 outgoing message by setting the variable @code{mail-default-headers}
@@ -268,6 +298,7 @@ These are short mnemonic names which stand for mail addresses or groups of
 mail addresses.  Like many other mail programs, Emacs expands aliases
 when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and
 @samp{Reply-to} fields, plus their @samp{Resent-} variants.
+@c The list is defined by mail-address-field-regexp.
 
   To define an alias in @file{~/.mailrc}, write a line in the following
 format:
@@ -280,7 +311,7 @@ alias @var{shortaddress} @var{fulladdresses}
 Here @var{fulladdresses} stands for one or more mail addresses for
 @var{shortaddress} to expand into.  Separate multiple addresses with
 spaces; if an address contains a space, quote the whole address with a
-pair of double-quotes.
+pair of double quotes.
 
 For instance, to make @code{maingnu} stand for
 @code{gnu@@gnu.org} plus a local address of your own, put in
@@ -291,18 +322,18 @@ alias maingnu gnu@@gnu.org local-gnu
 @end example
 
 @noindent
-Addresses specified in this way should use doublequotes around an
+Addresses specified in this way should use double quotes around an
 entire address when the address contains spaces.  But you need not
-include doublequotes around parts of the address, such as the person's
+include double quotes around parts of the address, such as the person's
 full name.  Emacs puts them in if they are needed.  For example,
 
 @example
-alias chief-torturer "George W. Bush <bush@@whitehouse.gov>"
+alias pres "President of the United States <president@@whitehouse.gov>"
 @end example
 
 @noindent
 is correct in @samp{.mailrc}.  Emacs will insert the address as
-@samp{"George W. Bush" <bush@@whitehouse.gov>}.
+@samp{"President of the United States" <president@@whitehouse.gov>}.
 
   Emacs also recognizes ``include'' commands in @samp{.mailrc} files.
 They look like this:
@@ -338,6 +369,8 @@ Emacs should read @file{.mailrc} to get the proper value.
 @file{~/.mailrc} by setting the variable
 @code{mail-personal-alias-file}.
 
+@c There is also mail-alias-file for the system aliases.
+
 @findex expand-mail-aliases
   Normally, Emacs expands aliases when you send the message.  You do not
 need to expand mail aliases before sending the message, but you can
@@ -364,9 +397,9 @@ Note that the mail abbreviation package uses the variable
 names are converted to lower case.
 
 @kindex C-c C-a @r{(Mail mode)}
-@findex mail-interactive-insert-alias
+@findex mail-abbrev-insert-alias
   The mail abbreviation package also provides the @kbd{C-c C-a}
-(@code{mail-interactive-insert-alias}) command, which reads an alias
+(@code{mail-abbrev-insert-alias}) command, which reads an alias
 name (with completion) and inserts its definition at point.  This is
 useful when editing the message text itself or a header field such as
 @samp{Subject} in which Emacs does not normally expand aliases.
@@ -392,9 +425,7 @@ expansion as well.  Here's how to do that:
   The major mode used in the mail buffer is Mail mode, which is much
 like Text mode except that various special commands are provided on the
 @kbd{C-c} prefix.  These commands all have to do specifically with
-editing or sending the message.  In addition, Mail mode defines the
-character @samp{%} as a word separator; this is helpful for using the
-word commands to edit mail addresses.
+editing or sending the message. 
 
   Mail mode is normally used in buffers set up automatically by the
 @code{mail} command and related commands.  However, you can also switch
@@ -425,13 +456,17 @@ Send the message, and select some other buffer (@code{mail-send-and-exit}).
 @kindex C-c C-c @r{(Mail mode)}
 @findex mail-send
 @findex mail-send-and-exit
+@vindex mail-send-hook
   @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail
 buffer unmodified, but leaves that buffer selected so that you can
 modify the message (perhaps with new recipients) and send it again.
 @kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the
 window or switches to another buffer.  It puts the mail buffer at the
 lowest priority for reselection by default, since you are finished with
-using it.  This is the usual way to send the message.
+using it.  This is the usual way to send the message.  Sending a message
+runs the hook @code{mail-send-hook}.
+
+@c Options not mentioned: mail-interactive, mail-use-dsn.
 
   In a file-visiting buffer, sending the message does not clear the
 modified flag, because only saving the file should do that.  Also, you
@@ -450,18 +485,22 @@ the coding system for outgoing mail by setting the variable
 a particular message, Emacs asks you to select the coding system to use,
 showing a list of possible coding systems.
 
+@c Not mentioned: mail-send-nonascii.
+
 @cindex SMTP
 @cindex Feedmail
 @cindex Sendmail
+@cindex Mailclient
 @vindex send-mail-function
   The variable @code{send-mail-function} controls how the default mail
 user agent sends mail.  It should be set to a function.  The default
 is @code{sendmail-send-it}, which delivers mail using the Sendmail
 installation on the local host.  To send mail through a SMTP server,
 set it to @code{smtpmail-send-it} and set up the Emacs SMTP library
-(@pxref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}).  A
-third option is @code{feedmail-send-it}, see the commentary section of
-the @file{feedmail.el} package for more information.
+(@pxref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}).
+Other options are @code{feedmail-send-it} (see the commentary section of
+the @file{feedmail.el} package), and @code{mailclient-send-it} (see
+@file{mailclient.el}).
 
 @node Header Editing
 @subsection Mail Header Editing
@@ -482,9 +521,20 @@ Move to the @samp{CC} header field, creating one if there is none
 @item C-c C-f C-b
 Move to the @samp{BCC} header field, creating one if there is none
 (@code{mail-bcc}).
+@item C-c C-f C-r
+Move to the @samp{Reply-To} header field, creating one if there is none
+(@code{mail-reply-to}).
+@item C-c C-f C-a
+Move to the @samp{Mail-Reply-To} header field, creating one if there is none
+(@code{mail-mail-reply-to}).
+@item C-c C-f C-l
+Move to the @samp{Mail-Followup-To} header field, creating one if there is none
+(@code{mail-mail-followup-to}).
 @item C-c C-f C-f
-Move to the @samp{FCC} header field, creating one if there is none
+Add a new @samp{FCC} header field, with file-name completion
 (@code{mail-fcc}).
+@c There is also C-c C-v, mail-sent-via, which adds one or more
+@c "Sent-via" headers, but I don't know what the point of that header is.
 @item M-@key{TAB}
 Complete a mailing address (@code{mail-complete}).
 @end table
@@ -497,17 +547,25 @@ Complete a mailing address (@code{mail-complete}).
 @findex mail-cc
 @kindex C-c C-f C-b @r{(Mail mode)}
 @findex mail-bcc
+@kindex C-c C-f C-r @r{(Mail mode)}
+@findex mail-reply-to
+@kindex C-c C-f C-a @r{(Mail mode)}
+@findex mail-mail-reply-to
+@kindex C-c C-f C-l @r{(Mail mode)}
+@findex mail-mail-followup-to
 @kindex C-c C-f C-f @r{(Mail mode)}
 @findex mail-fcc
-  There are five commands to move point to particular header fields, all
-based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field'').  They
-are listed in the table above.  If the field in question does not exist,
-these commands create one.  We provide special motion commands for these
-particular fields because they are the fields users most often want to
-edit.
+  There are several commands to move point to particular header fields,
+all based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field'').
+They are listed in the table above.  If the field in question does not
+exist, these commands create one (the exception is @code{mail-fcc},
+which creates a new field each time).  We provide special motion
+commands for these particular fields because they are the fields users
+most often want to edit.
 
 @findex mail-complete
 @kindex M-TAB @r{(Mail mode)}
+@c `mail-complete-alist' specifies the headers.
   While editing a header field that contains mailing addresses, such
 as @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing
 address by typing @kbd{M-@key{TAB}} (@code{mail-complete}).  It
@@ -519,14 +577,15 @@ manager defines @kbd{M-@key{TAB}} to switch windows, you can type
 @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.)
 
   For completion purposes, the valid mailing addresses are taken to be
-the local users' names plus your personal mail aliases.  You can
-specify additional sources of valid addresses; see the customization
-group @samp{mailalias} to see the variables for customizing this
-feature (@pxref{Customization Groups}).
+the local users' names plus your personal mail aliases (@pxref{Mail
+Aliases}).  You can specify additional sources of valid addresses;
+browse the customization group @samp{mailalias} to see the variables for
+customizing this feature (@pxref{Customization Groups}).
 
-  If you type @kbd{M-@key{TAB}} in the body of the message,
-@code{mail-complete} invokes @code{ispell-complete-word}, as in Text
-mode.
+  If you type @kbd{M-@key{TAB}} in the body of the message, or on a
+unrecognized header, @code{mail-complete} invokes the function specified
+by @code{mail-complete-function}.  By default, this is
+@code{ispell-complete-word}, as in Text mode.
 
 @node Citing Mail
 @subsection Citing Mail
@@ -544,6 +603,7 @@ Yank the region from the Rmail buffer (@code{mail-yank-region}).
 @item C-c C-q
 Fill each paragraph cited from another message
 (@code{mail-fill-yanked-message}).
+@c There is also mail-split-line, but it does not seem very useful.
 @end table
 
 @kindex C-c C-y @r{(Mail mode)}
@@ -551,7 +611,8 @@ Fill each paragraph cited from another message
   When mail sending is invoked from the Rmail mail reader using an Rmail
 command, @kbd{C-c C-y} can be used inside the mail buffer to insert
 the text of the message you are replying to.  Normally it indents each line
-of that message three spaces and eliminates most header fields.  A numeric
+of that message three spaces and eliminates most header fields (as
+specified by the variable @code{mail-yank-ignored-headers}).  A numeric
 argument specifies the number of spaces to indent.  An argument of just
 @kbd{C-u} says not to indent at all and not to eliminate anything.
 @kbd{C-c C-y} always uses the current message from the Rmail buffer,
@@ -565,6 +626,7 @@ of each line: set @code{mail-yank-prefix} to the desired string.  (A
 value of @code{nil} means to use indentation; this is the default.)
 However, @kbd{C-u C-c C-y} never adds anything at the beginning of the
 inserted lines, regardless of the value of @code{mail-yank-prefix}.
+@c Indentation controlled by mail-indentation-spaces.
 
 @kindex C-c C-r @r{(Mail mode)}
 @findex mail-yank-region
@@ -583,6 +645,14 @@ quoted message, use @kbd{M-q}.  If filling does not automatically
 handle the type of citation prefix you use, try setting the fill prefix
 explicitly.  @xref{Filling}.
 
+@vindex mail-citation-hook
+  You can customize mail citation through the hook
+@code{mail-citation-hook}.  For example, you can use the Supercite
+package, which provides more flexible citation
+(@pxref{Introduction,,,sc, Supercite}).
+
+@c No need to mention: mail-citation-prefix-regexp.
+
 @node Mail Mode Misc
 @subsection Mail Mode Miscellany
 
@@ -590,14 +660,13 @@ explicitly.  @xref{Filling}.
 @item C-c C-t
 Move to the beginning of the message body text (@code{mail-text}).
 @item C-c C-w
-Insert the file @file{~/.signature} at the end of the message text
-(@code{mail-signature}).
+Insert a signature at the end of the message text (@code{mail-signature}).
 @item C-c C-i @var{file} @key{RET}
-Insert the contents of @var{file} at the end of the outgoing message
+Insert the contents of @var{file} at the end of the message text
 (@code{mail-attach-file}).
 @item M-x ispell-message
 Perform spelling correction on the message text, but not on citations from
-other messages.
+other messages, or the message headers.
 @end table
 
 @kindex C-c C-t @r{(Mail mode)}
@@ -609,19 +678,25 @@ separator line---that is, to the beginning of the message body text.
 @findex mail-signature
 @vindex mail-signature
   @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at
-the end of the message to say more about who you are.  The text comes
-from the file @file{~/.signature} in your home directory.  To insert
-your signature automatically, set the variable @code{mail-signature} to
-@code{t}; after that, starting a mail message automatically inserts the
-contents of your @file{~/.signature} file.  If you want to omit your
-signature from a particular message, delete it from the buffer before
-you send the message.
-
-  You can also set @code{mail-signature} to a string; then that string
-is inserted automatically as your signature when you start editing a
-message to send.  If you set it to some other Lisp expression, the
-expression is evaluated each time, and its value (which should be a
-string) specifies the signature.
+the end of the message to say more about who you are.  For example, it
+may contain telephone numbers, or your physical location.  The text
+comes from the variable @code{mail-signature}.  It can be a fixed
+string, or a Lisp expression that returns a string.  If it is @code{t}
+or @code{nil}, the function inserts the contents of the file
+@code{mail-signature-file}.  By default, this is the file
+@file{~/.signature} in your home directory.
+
+  If the variable @code{mail-signature} has a non-@code{nil} value,
+starting a mail automatically inserts your signature.  Otherwise, you
+must explicitly use the command @code{mail-signature}.  If you want to
+omit your signature from a particular message, just delete it from the
+buffer before you send the message.
+
+  Convention says that the start of your signature should be marked by a
+line whose contents are @samp{-- }.  If your signature comes from a
+file, this prefix is added for you, but in all other cases you must add
+it yourself.  The remainder of your signature should be no more than
+four lines.
 
 @findex ispell-message
   You can do spelling correction on the message text you have written
@@ -637,7 +712,7 @@ lines from your input.)  @xref{Spelling}.
 the usual command to insert a file in the current buffer.  But it is
 often more convenient to use a special command, @kbd{C-c C-i}
 (@code{mail-attach-file}).  This command inserts the file contents at
-the end of the buffer, after your signature if any, with a delimiter
+the end of the buffer, after your signature (if any), with a delimiter
 line that includes the file name.  Note that this is not a MIME
 attachment.
 
@@ -656,6 +731,12 @@ as soon as the @samp{*mail*} buffer is created.  Then the
 @code{mail-setup} function inserts the default contents of the buffer.
 After these default contents are inserted, @code{mail-setup-hook} runs.
 
+  If you use @kbd{M-x mail} to continue an existing composition,
+@code{mail-mode-hook} runs immediately after switching to the
+@samp{*mail*} buffer.  If the buffer is unmodified, or if you decide to
+erase it and start again, @code{mail-setup-hook} runs after the default
+contents are inserted.
+
 @node Mail Amusements
 @section Mail Amusements
 
@@ -666,21 +747,13 @@ mail message.  The keywords are chosen from a list of words that suggest
 you are discussing something subversive.
 
   The idea behind this feature is the suspicion that the
-NSA@footnote{The US National Security Agency.} snoops on
-all electronic mail messages that contain keywords suggesting they might
-find them interesting.  (The NSA says they don't, but that's what they
-@emph{would} say.)  The idea is that if lots of people add suspicious
-words to their messages, the NSA will get so busy with spurious input
-that they will have to give up reading it all.
-
-  Here's how to insert spook keywords automatically whenever you start
-entering an outgoing message:
-
-@example
-(add-hook 'mail-setup-hook 'spook)
-@end example
-
-  Whether or not this confuses the NSA, it at least amuses people.
+NSA@footnote{The US National Security Agency.} and other intelligence
+agencies snoop on all electronic mail messages that contain keywords
+suggesting they might find them interesting.  (The agencies say that
+they don't, but that's what they @emph{would} say.)  The idea is that if
+lots of people add suspicious words to their messages, the agencies will
+get so busy with spurious input that they will have to give up reading
+it all.  Whether or not this is true, it at least amuses some people.
 
 @findex fortune-to-signature
 @cindex fortune cookies
@@ -692,6 +765,10 @@ message into outgoing mail.  To do this, add
 (add-hook 'mail-setup-hook 'fortune-to-signature)
 @end example
 
+@noindent
+You will probably need to set the variable @code{fortune-file} before
+using this.
+
 @node Mail Methods
 @section Mail-Composition Methods
 @cindex mail-composition methods
@@ -719,6 +796,11 @@ in this chapter about the @samp{*mail*} buffer and Mail mode does not
 apply; the other methods use a different format of text in a different
 buffer, and their commands are different as well.
 
+@vindex read-mail-command
+  Similarly, to specify your preferred method for reading mail,
+customize the variable @code{read-mail-command}.  The default is
+@code{rmail} (@pxref{Rmail}).
+
 @ignore
    arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6
 @end ignore