File: mh-e.texi

package info (click to toggle)
mh-e 7.82-4
links: PTS
area: main
in suites: sarge
size: 2,596 kB
ctags: 1,180
sloc: lisp: 16,919; makefile: 336; sh: 157; perl: 34
file content (6270 lines) | stat: -rw-r--r-- 226,132 bytes
\\\input texinfo   @c -*-texinfo-*-
@c $Id: mh-e.texi,v 1.65 2003/11/03 23:43:37 wohler Exp $
@c
@c Note: This document requires makeinfo version 4.6 or greater to build.
@c
@c %**start of header
@setfilename info/mh-e
@settitle MH-E
@c %**end of header

@c Version variables.
@set EDITION of the MH-E manual which you must ignore until it is released as it is a work in progress and does not reflect any known release of MH-E
@set VERSION None
@set UPDATED in progress
@set UPDATE-MONTH Work in Progress

@c Other variables.
@set MH-BOOK-HOME http://www.ics.uci.edu/~mh/book/mh
@set MH-E-HOME http://mh-e.sourceforge.net/

@copying
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
@cite{MH-E, The Emacs Interface to MH}, for MH-E, Version
@value{VERSION}.

Copyright @copyright{} 1995, 2001, 02, 2003 Free Software Foundation, Inc.

@quotation
The MH-E manual is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

The MH-E manual is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

The GNU GENERAL PUBLIC LICENSE appears as an appendix to this
document. You may also request a copy by writing to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.
@end quotation
@end copying

@setchapternewpage odd

@dircategory Emacs
@direntry
* MH-E: (mh-e).		Emacs interface to the MH mail system.
@end direntry

@titlepage
@title MH-E - The GNU Emacs Interface to the MH Mail System
@subtitle Edition @value{EDITION} for MH-E Version @value{VERSION}
@subtitle @value{UPDATE-MONTH}
@author Bill Wohler

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Preface, (dir), (dir)
@top MH and Emacs
@insertcopying
@end ifnottex

@menu
* Preface::                     Preface
* Tour Through MH-E::           Tour Through MH-E
* Using This Manual::           Using This Manual
* Ranges::                      Ranges
* Folder Selection::            Folder Selection
* Incorporating Mail::          Incorporating Mail
* Reading Mail::                Reading Mail
* Folders::                     Organizing Your Mail with Folders
* Sending Mail::                Sending Mail
* Editing Drafts::              Editing a Draft
* Aliases::                     Aliases
* Identities::                  Identities
* Speedbar::                    The Speedbar
* Menubar::                     The Menubar
* Toolbar::                     The Toolbar
* Searching::                   Searching Through Messages
* Limits::                      Limiting Display
* Sequences::                   Using Sequences
* Miscellaneous::               Miscellaneous Commands, Variables, and Buffers
* Junk::                        Dealing With Junk Mail
* Scan Line Formats::           Scan Line Formats
* Procmail::                    Reading Mailing Lists Effectively
* Odds and Ends::               Odds and Ends
* History::                     History of MH-E
* Copying::                     GNU General Public License
* Key Index::                   Key (Character) Index
* Command Index::               Command Index
* Option Index::                Option (Variable) Index
* Concept Index::               Concept Index
* XXX::                         Placeholder For Sections Unwritten

@detailmenu
 --- The Detailed Node Listing ---

Tour Through MH-E

* Conventions::                 GNU Emacs Terms and Conventions
* Getting Started::             
* Sending Mail Tour::           
* Reading Mail Tour::           
* Processing Mail Tour::        
* Leaving MH-E::                
* More About MH-E::             

Reading Your Mail

* MH-Folder Options::             
* Viewing::                     
* Viewing Attachments::         
* HTML::                        
* Digests::                     
* Reading PGP::                 
* Printing::                    
* Files and Pipes::             
* Navigating::                  

Sending Mail

* Composing::                   
* Replying::                    
* Forwarding::                  
* Redistributing::              
* Editing Again::               

Editing a Draft

* Inserting Letter::            
* Inserting Messages::          
* Editing Header::              
* Checking Recipients::         
* Signature::                   
* Picture::                     
* Adding Attachments::          
* Sending PGP::                 
* Sending Message::             
* Killing Draft::               

Odds and Ends

* Bug Reports::                 
* Mailing Lists::               
* MH FAQ and Support::          
* Getting MH-E::                
* Contrib::                     

History of MH-E

* From Brian Reid::             
* From Jim Larus::              
* From Stephen Gildea::         

@end detailmenu
@end menu

@node Preface, Tour Through MH-E, Top, Top
@unnumbered Preface

@cindex Emacs
@cindex Unix commands, Emacs

These chapters introduce another interface to MH that is accessible
through the GNU Emacs editor, namely, @emph{MH-E}. MH-E is easy to
use. I don't assume that you know GNU Emacs or even MH at this point,
since I didn't know either of them when I discovered MH-E. However,
MH-E was the tip of the iceberg, and I discovered more and more
niceties about GNU Emacs and MH@. Now I'm fully hooked on both of
them.

@cindex MH-E, versions
@cindex history
@cindex versions of MH-E

The MH-E package is distributed with GNU Emacs@footnote{Version
@value{VERSION} of MH-E is distributed with Emacs 21.4. It is
supported in GNU Emacs 21, as well as @w{XEmacs 21} and @w{GNU Emacs
20.7}. It is compatible with MH versions 6.8.4 and higher and all
versions of nmh.}, so you shouldn't have to do anything special to use
it. But it's important to note a brief history of MH-E. @w{Version 3}
was prevalent through the @w{Emacs 18} and early @w{Emacs 19} years.
Then @w{Version 4} came out (@w{Emacs 19.23}), which introduced
several new and changed commands. Finally, @w{Version 5.0} was
released, which fixed some bugs and incompatibilities, and was
incorporated into @w{Emacs 19.29}. Finally, development was rekindled
on SourceForge which resulted in menus and buttons in version 6 and
Emacs 21.2. Then, indexed searches, improved MIME handling, a
speedbar, multiple identities, and alias completion were introduced
through version 7 in Emacs 21.4. This is the version covered by this
manual. @ref{Getting Started} will help you decide which version you
have.

If you don't already use GNU Emacs but want to learn more, you can
read an online tutorial by starting GNU Emacs and typing @kbd{C-h t}
(@code{help-with-tutorial}). (To learn about this notation, see
@ref{Conventions}.) If you want to take the plunge, consult the
@iftex
@cite{GNU Emacs Manual},
@end iftex
@ifinfo
@ref{top, , GNU Emacs Manual, emacs, GNU Emacs Manual},
@end ifinfo
@ifhtml
@uref{http://www.gnu.org/software/emacs/manual/html_node/emacs.html,
@cite{GNU Emacs Manual}},
@end ifhtml
from the Free Software Foundation.

If more information is needed, you can go to the Unix manual pages of
the individual MH commands. When the name is not obvious, I'll guide
you to a relevant MH manual page that describes the action more fully.

If you are reading this within Emacs or @command{info}, you may be
interested in the online versions of
@uref{http://www.ics.uci.edu/~mh/book/mh-e/, this document} as well as
@uref{http://www.ics.uci.edu/~mh/book/, @cite{MH & nmh: Email for
Users & Programmers}} (also known as @dfn{the MH book}). Likewise, if
you are reading this online, you might be interested to know that the
MH-E manual is also distributed with Emacs.

I hope you enjoy these chapters! If you have any comments, or
suggestions for this document, please let me know.

@cindex Bill Wohler
@cindex Wohler, Bill

@noindent
Bill Wohler <@i{wohler at newt.com}>@*
8 February 1995@*
21 January 2003

@node Tour Through MH-E, Using This Manual, Preface, Top
@chapter Tour Through MH-E

This chapter introduces some of the terms you'll need to know and then
takes you on a tour of MH-E@footnote{The keys mentioned in these
chapters refer to the default key bindings. If you've changed the
bindings, refer to the command summaries at the beginning of each
chapter for a mapping between default key bindings and function
names.}. When you're done, you'll be able to send, read, and file
mail, which is all that a lot of people ever do. But if you're the
curious or adventurous type, read the rest of the manual to be able to
use all the features of MH-E. I suggest you read this chapter first to
get the big picture, and then you can read the manual as you wish.

@menu
* Conventions::                 GNU Emacs Terms and Conventions
* Getting Started::             
* Sending Mail Tour::           
* Reading Mail Tour::           
* Processing Mail Tour::        
* Leaving MH-E::                
* More About MH-E::             
@end menu

@node Conventions, Getting Started, Tour Through MH-E, Tour Through MH-E
@section GNU Emacs Terms and Conventions

@cindex Emacs
@cindex Emacs, terms and conventions
@cindex Unix commands, Emacs

If you're an experienced Emacs user, you can skip the following
conventions and definition of terms and go directly to the next
section (@pxref{Getting Started}).

@cindex Emacs commands
@cindex MH commands
@cindex Unix commands
@cindex commands
@cindex commands, MH
@cindex commands, Unix
@cindex commands, shell
@cindex functions
@cindex shell commands

In general, @dfn{functions} in this text refer to Emacs Lisp functions
that one would call from within Emacs Lisp programs (for example,
@code{(mh-inc-folder)}). On the other hand, @dfn{commands} are those
things that are run by the user, such as @kbd{i} or @kbd{M-x
mh-inc-folder}. Programs outside of Emacs are specifically called MH
commands, shell commands, or Unix commands.

@cindex conventions, key names
@cindex key names

The conventions for key names are as follows:

@table @kbd
@item C-x
Hold down the @key{CTRL} (Control) key and press the @kbd{x} key.
@item M-x
Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key.

Since some keyboards don't have a @key{META} key, you can generate
@kbd{M-x}, for example, by pressing @key{ESC} (Escape),
@emph{releasing it}@footnote{This is emphasized because pressing ESC
twice or holding it down a second too long so that it repeats gives
you an error message.}, and then pressing the @kbd{x} key.
@item RET
Press the @key{RETURN} or @key{ENTER} key. This is normally used to
complete a command.
@item SPC
Press the space bar.
@item TAB
Press the @key{TAB} key.
@item DEL
Press the @key{DELETE} key.
@item BS
Press the @key{BACKSPACE} key@footnote{If you are using Version 20 or
earlier of Emacs, you will need to use the @key{DEL} key.}.
@end table

@cindex Emacs, prefix argument
@cindex prefix argument

A @dfn{prefix argument} allows you to pass an argument to any Emacs
function. To pass an argument, type @kbd{C-u} before the Emacs command
or keystroke. Numeric arguments can be passed as well. For example, to
insert five f's, use @kbd{C-u 5 f}. There is a default of four when
using @kbd{C-u}, and you can use multiple prefix arguments to provide
arguments of powers of four. To continue our example, you could insert
four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with
@kbd{C-u C-u C-u f}, and so on. Numeric and valueless negative
arguments can also be inserted with the @key{META} key. Examples
include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which
specifies a negative argument with no particular value.

@sp 1
@center @strong{NOTE}

@quotation
The prefix @kbd{C-u} or @kbd{M-} is not necessary in MH-E's MH-Folder
mode (@pxref{Reading Mail Tour}). In this mode, simply enter the
numerical argument before entering the command.
@end quotation

@sp 1

@cindex Emacs, options
@cindex options
@findex customize-group
@findex customize-option

Variables in MH-E that can normally be modified by the user are called
@dfn{options} and are modified through the customize functions (such
as @kbd{M-x customize-option} or @kbd{M-x customize-group}).

@cindex Emacs, variables
@cindex variables

There are, however, a few @dfn{variables} that you may wish to change
which are modified via the @code{setq} function rather than through
the customize interface.

@cindex Emacs, mark
@cindex Emacs, point
@cindex Emacs, region
@cindex mark
@cindex point
@cindex region

There are several other terms that are used in Emacs that you should
know. The @dfn{point} is where the cursor currently is. You can save
your current place in the file by setting a @dfn{mark}. This operation
is useful in several ways. The mark can be later used when defining a
@dfn{region}, which is the text between the point and mark. Many
commands operate on regions, such as those for deleting text or
filling paragraphs. A mark can be set with @kbd{C-@@} (or
@kbd{C-SPC}).

@cindex Emacs, file completion
@cindex Emacs, minibuffer
@cindex file completion
@cindex minibuffer

The @dfn{minibuffer} is the bottom line of the Emacs window, where all
prompting and multiple-character input is directed. If you are
prompted for information in the minibuffer, such as a filename, Emacs
can help you complete your answer if you type @key{SPC} or @key{TAB}.
A second @key{SPC} or @key{TAB} will list all possibilities at that
point. The minibuffer is also where you enter Emacs function names
after typing @kbd{M-x}. For example, in the preface, I mentioned that
you could obtain help with @kbd{C-h t} (@code{help-with-tutorial}).
What this means is that you can get a tutorial by typing either
@kbd{C-h t} or @kbd{M-x help-with-tutorial}. In the latter case, you
are prompted for @samp{help-with-tutorial} in the minibuffer after
typing @kbd{M-x}.

@cindex Emacs, interrupting
@cindex Emacs, quitting
@cindex interrupting
@cindex quitting

@i{In case of trouble:} Emacs can be interrupted at any time with
@kbd{C-g}. For example, if you've started a command that requests that
you enter something in the minibuffer, but then you change your mind,
type @kbd{C-g} and you'll be back where you started. If you want to
exit Emacs entirely, use @kbd{C-x C-c}.

@node Getting Started, Sending Mail Tour, Conventions, Tour Through MH-E
@section Getting Started

@cindex MH-E, versions
@cindex history
@cindex versions of MH-E

Because there are many old versions of MH-E out there, it is important
to know which version you have. I'll be talking about @w{Version 8}
which is pretty close to @w{Version 6} and @w{Version 7} but differs
from @w{Version 4} and @w{Version 5} and is vastly different from
@w{Version 3}.

To determine which version of MH-E that you have, enter @kbd{M-x
mh-version @key{RET}}. The version of MH-E should be displayed.
Hopefully it says that you're running @w{Version @value{VERSION}}
which is the latest version as of this printing. If instead Emacs
beeps and says @samp{[No match]}, then you're running a old version of
MH-E.

You may also be running an older version of Emacs which does not load
the MH-E library automatically. To see if this is the case, enter
@kbd{M-x load-library @key{RET} mh-e @key{RET}}. The message,
@samp{Loading mh-e...done}, should be displayed in the minibuffer. If
you get @samp{Cannot open load file: mh-e}, then your Emacs is very
badly configured, or MH-E is missing. You may wish to have your system
administrator install a new Emacs or at least the latest MH-E files.

If these tests reveal a non-existent or old version of MH-E, please
consider obtaining a new version. You can have your system
administrator upgrade the system-wide version, or you can install your
own personal version. It's really quite easy. @xref{Getting MH-E}, for
instructions for getting and installing MH-E.

@cindex @command{install-mh}
@cindex MH commands, @command{install-mh}

Also, older versions of MH-E assumed that you had already set up your
MH environment@footnote{See the section
@uref{@value{MH-BOOK-HOME}/setup.htm, Setting Up MH} in the MH book.}.
Newer versions set up a new MH environment for you by running
@command{install-mh} and notifying you of this fact with the message
in a temporary buffer:

@example
I'm going to create the standard MH path for you.
@end example

Therefore, if you've never run MH before and you're using an old
version of MH-E, you need to run @command{install-mh} from the shell
before you continue the tour. If you don't, you'll be greeted with the
error message: @samp{Can't find MH profile}.

@cindex @file{.emacs}
@cindex files, @file{.emacs}
@vindex mh-lib-progs
@vindex mh-lib
@vindex mh-progs

The variables @code{mh-progs}, @code{mh-lib}, and @code{mh-lib-progs}
are used to tell MH-E where the MH programs, supporting files, and
supporting programs are kept, respectively. MH-E does try to figure
out where they are kept by looking in common places and in the user's
@samp{PATH} environment variable, but if it cannot find the
directories, or finds the wrong ones, you should set these variables.
A symptom that the variables are wrong is a message like:
@samp{Searching for program: no such file or directory,
/usr/local/bin/mhpath}. In this case, add the following@footnote{If
your version of MH-E is less than 6.0, then you will have to set
@code{mh-lib} and @code{mh-lib-progs} manually too.} to
@file{~/.emacs} and restart @command{emacs}:

@vindex mh-progs, example

@lisp
(setq mh-progs "/usr/bin/mh/")
@end lisp

Note that the name of the directory should be placed in double quotes,
and there should be a trailing slash (@samp{/}). If you have to do
this, please file a bug report (@pxref{Bug Reports}) and indicate the
directories that contains your MH files and programs and the type of
system that you're running.

@cindex ~

The @samp{~} notation used by @file{~/.emacs} above represents your
home directory. This is used by the @command{bash} and @command{csh}
shells. If your shell does not support this feature, you could use the
environment variable @samp{$HOME} (such as @file{$HOME/.emacs}) or the
absolute path (as in @file{/home/wohler/.emacs}) instead.

At this point, you should see something like the screen in the figure
in @ref{Reading Mail Tour}. We're now ready to move on.

@node Sending Mail Tour, Reading Mail Tour, Getting Started, Tour Through MH-E
@section Sending Mail

@cindex sending mail
@findex mh-smail

Let's start our tour by sending ourselves a message which we can later
read and process. Enter @kbd{M-x mh-smail} to invoke the MH-E program
to send messages. You will be prompted in the minibuffer by
@samp{To:}. Enter your login name. The next prompt is @samp{Cc:}. Hit
@key{RET} to indicate that no carbon copies are to be sent. At the
@samp{Subject:} prompt, enter @kbd{Test} or anything else that comes
to mind.

@cindex MH-Letter mode
@cindex modes, MH-Letter
@cindex mode

Once you've specified the recipients and subject, your message appears
in an Emacs buffer whose mode@footnote{A @dfn{mode} changes Emacs to
make it easier to edit a particular type of text.} is MH-Letter. Enter
some text in the body of the message, using normal Emacs commands. You
should now have something like this@footnote{If you're running Emacs
under the X Window System, then you would also see a menubar. Under
Emacs 21, you would also see a toolbar. I've left out the menubar and
toolbar in all of the example screens.}:

@smallexample
@group
@cartouche






--:--  *scratch*   (Lisp Interaction)--L1--All-------------------------
To: wohler
cc:
Subject: Test
--------
  This is a test message to get the wheels churning...#


--:** @{draft@}   (MH-Letter)--L5--All-----------------------------------

@end cartouche
@i{MH-E message composition window}
@end group
@end smallexample

Note the line of dashes that separates the header and the body of the
message. It is essential that these dashes (or a blank line) are
present or the body of your message will be considered to be part of
the header.

@cindex help
@kindex C-c C-c

There are several commands specific to MH-Letter mode@footnote{You can
get quick help for the commands used most often with @kbd{C-c ?} or
more complete help with the @kbd{C-h m} (@code{describe-mode})
command.}, but at this time we'll only use @kbd{C-c C-c} to send your
message. Type @kbd{C-c C-c} now. That's all there is to it!

@node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through MH-E
@section Receiving Mail

@cindex @command{inc}
@cindex @command{scan}
@cindex MH commands, @command{inc}
@cindex MH commands, @command{scan}
@cindex MH-Folder mode
@cindex modes, MH-Folder
@cindex reading mail
@findex mh-rmail

To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}.
This incorporates the new mail and put the output from
@command{inc}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/reapre.htm, Reading Mail: inc show next
prev} in the MH book.} (called @dfn{scan lines} after the MH program
@command{scan}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/faswsprs.htm, Find and Specify with scan
pick Ranges Sequences} in the MH book.} which prints a one-line
summary of each message) into a buffer called @samp{+inbox} whose
major mode is MH-Folder.

@sp 1
@center @strong{NOTE}

@quotation
The @kbd{M-x mh-rmail} command will show you only new mail, not mail
you have already read. If you were to run this tour again, you would
use @kbd{F r} to pull all your messages into MH-E.
@end quotation

@sp 1

@kindex RET
@kindex n
@kindex p

You should see the scan line for your message, and perhaps others. Use
@kbd{n} or @kbd{p} to move the cursor to your test message and type
@key{RET} to read your message. You should see something like:

@smallexample
@group
@cartouche
  3 t08/24 root       received fax files on Wed Aug 24 11:00:13 PDT 1
# 4+t08/24 To:wohler  Test<<This is a test message to get the wheels

-:%%  @{+inbox@} 4 msgs (1-4)   (MH-Folder Show)--L4--Bot--------------
To: wohler
Subject: Test
Date: Wed, 24 Aug 1994 13:01:13 -0700
From: Bill Wohler <wohler@@stop.mail-abuse.org>

  This is a test message to get the wheels churning...





--:--  @{show-+inbox@} 4   (MH-Show)--L1--All---------------------------

@end cartouche
@i{After incorporating new messages}
@end group
@end smallexample

@kindex DEL
@kindex SPC

If you typed a long message, you can view subsequent pages with
@key{SPC} and previous pages with @key{DEL}.

@node Processing Mail Tour, Leaving MH-E, Reading Mail Tour, Tour Through MH-E
@section Processing Mail

@cindex processing mail
@kindex r

The first thing we want to do is reply to the message that we sent
ourselves. Ensure that the cursor is still on the same line as your
test message and type @kbd{r}. You are prompted in the minibuffer with
@samp{Reply to whom:}. Here MH-E is asking whether you'd like to reply
to the original sender only, to the sender and primary recipients, or
to the sender and all recipients. If you simply hit @key{RET}, you'll
reply only to the sender. Hit @key{RET} now.

You'll find yourself in an Emacs buffer similar to that when you were
sending the original message, like this:

@smallexample
@group
@cartouche
To: wohler
Subject: Re: Test
In-reply-to: Bill Wohler's message of Wed, 24 Aug 1994 13:01:13 -0700
             <199408242001.NAA00505@@stop.mail-abuse.org>
--------
#

--:--  @{draft@}   (MH-Letter)--L11--Bot---------------------------------
To: wohler
Subject: Test
Date: Wed, 24 Aug 1994 13:01:13 -0700
From: Bill Wohler <wohler@@stop.mail-abuse.org>

  This is a test message to get the wheels churning...

--:--  @{show-+inbox@} 4   (MH-Show)--L1--All----------------------------
Composing a reply...done
@end cartouche
@i{Composition window during reply}
@end group
@end smallexample

@kindex C-c C-c
@kindex C-c C-f C-t

By default, MH will not add you to the address list of your replies,
so if you find that the @samp{To:} header field is missing, don't
worry. In this case, type @kbd{C-c C-f C-t} to create and go to the
@samp{To:} field, where you can type your login name again. You can
move around with the arrow keys or with @kbd{C-p}
(@code{previous-line}), @kbd{C-n} (@code{next-line}), @kbd{C-b}
(@code{backward-char}), and @kbd{C-f} (@code{forward-char}) and can
delete the previous character with @key{BS}. When you're finished
editing your message, send it with @kbd{C-c C-c} as before.

@cindex folders
@kindex o

You'll often want to save messages that were sent to you in an
organized fashion. This is done with @dfn{folders}. You can use
folders to keep messages from your friends, or messages related to a
particular topic. With your cursor in the MH-Folder buffer and
positioned on the message you sent to yourself, type @kbd{o} to output
(@command{refile} in MH parlance) that message to a folder. Enter
@kbd{test} at the @samp{Destination:} prompt and type @kbd{y} (or
@key{SPC}) when MH-E asks to create the folder @samp{+test}. Note that
a @samp{^} (caret) appears next to the message number, which means
that the message has been marked for refiling but has not yet been
refiled. We'll talk about how the refile is actually carried out in a
moment.

@cindex MH-Folder mode
@cindex modes, MH-Folder
@kindex RET
@kindex d
@kindex i
@kindex x

Your previous reply is now waiting in the system mailbox. You
incorporate this mail into your MH-Folder buffer named @samp{+inbox}
with the @kbd{i} command. Do this now. After the mail is incorporated,
use @kbd{n} or @kbd{p} to move the cursor to the new message, and read
it with @key{RET}. Let's delete this message by typing @kbd{d}. Note
that a @samp{D} appears next to the message number. This means that
the message is marked for deletion but is not yet deleted. To perform
the deletion (and the refile we did previously), use the @kbd{x}
command.

@findex mh-smail
@kindex m

If you want to send another message you can use @kbd{m} instead of
@kbd{M-x mh-smail}. So go ahead, send some mail to your friends!

@cindex help
@cindex prefix characters
@findex describe-mode
@kindex ?
@kindex C-h m

You can get a quick reminder about these commands by typing @kbd{?}.
This lists several @dfn{prefix characters}. To list the commands
available via the prefix characters, type the prefix character
followed by a @kbd{?}, for example, @kbd{F ?}. More complete help is
available with the @kbd{C-h m} (@code{describe-mode}) command.

@node Leaving MH-E, More About MH-E, Processing Mail Tour, Tour Through MH-E
@section Leaving MH-E

@cindex Emacs, quitting
@cindex quitting

You may now wish to exit @command{emacs} entirely. Use @kbd{C-x C-c}
to exit @command{emacs}. If you exited without running @kbd{x} in the
@samp{+inbox} buffer, Emacs will offer to save it for you. Type
@kbd{y} or @key{SPC} to save @samp{+inbox} changes, which means to
perform any refiles and deletes that you did there.

@findex mh-rmail
@kindex q

If you don't want to leave Emacs, you can type @kbd{q} to bury (hide)
the MH-E folder or delete it entirely with @kbd{C-x k}. You can then
later recall it with @kbd{C-x b} or @kbd{M-x mh-rmail}.

@c From Mark: XXX
@c It may seem silly, but I think a reference of how they
@c would escape from using MH-E and save their MH folders
@c into an mbox-style folder is also appropriate. An exit
@c strategy that is well spelled out, like using the
@c packmbox command always relieves folks who have been
@c used to the systems where the e-mail checks-in but
@c never leaves that is true of some propietary e-mail
@c systems out there.

@node More About MH-E,  , Leaving MH-E, Tour Through MH-E
@section More About MH-E

These are the basic commands to get you going, but there are plenty
more. If you think that MH-E is for you, read the rest of the manual
to find out how you can:

@c ensure all new features are listed here XXX

@itemize @bullet
@item
Print your messages. (@ref{Printing}.)
@item
Edit messages and include your signature. (@ref{Editing Drafts}.)
@item
Forward messages. (@ref{Forwarding}.)
@item
Read digests. (@ref{Digests}.)
@item
Edit bounced messages. (@ref{Editing Again}.)
@item
Send multimedia messages. (@ref{Adding Attachments}.)
@item
Process mail that was sent with @command{shar} or @command{uuencode}.
(@ref{Files and Pipes}.)
@item
Use sequences conveniently. (@ref{Sequences}.)
@item
Show header fields in different fonts. (@ref{XXX}.)
@item
Find previously refiled messages. (@ref{Searching}.)
@item
Place messages in a file. (@ref{Files and Pipes}.)
@end itemize

Remember that you can also use MH commands when you're not running
MH-E (and when you are!).

@node Using This Manual, Ranges, Tour Through MH-E, Top
@chapter Using This Manual

@c From Mark: XXX
@c Hmmm... Is there a chapter on MH vs nmh vs mailutils-MH?

@c I think this should covered in the discussion of mh-variant. Maybe
@c this chapter should be named Getting Started.

This chapter begins the meat of the manual which goes into more detail
about every MH-E command and option.

@cindex Emacs, info
@cindex Emacs, online help
@cindex info
@cindex online help
@findex describe-mode
@findex mh-help
@kindex ?
@kindex C-c ?

There are many commands, but don't get intimidated. There are command
summaries at the beginning of each chapter. In case you have or would
like to rebind the keys, the command summaries also list the
associated Emacs Lisp function. Furthermore, even if you're stranded
on a desert island with a laptop and are without your manuals, you can
get a summary of all these commands with GNU Emacs online help: use
@kbd{C-h m} (@code{describe-mode}) for a brief summary of commands,
@kbd{?} (@code{mh-help}) for an even briefer summary@footnote{This
help appears in a buffer called @samp{*MH-E Help*}
(@pxref{Miscellaneous}).} (@kbd{C-c ?} in MH-Letter mode), or @kbd{C-h
i} to read this manual via Info. The online help is quite good; try
running @kbd{C-h C-h C-h}. This brings up a list of available help
topics, one of which displays the documentation for a given key (like
@kbd{C-h k C-n}). Another useful help feature is to view the manual
section that describes a given key (such as @kbd{C-h C-k i}). In
addition, review @ref{Conventions}, if any of the GNU Emacs
conventions are strange to you.

In addition to all of the commands, it is also possible to reconfigure
MH-E to fit the needs of even the most demanding user. The following
chapters also describe all of the options, show the defaults, and make
recommendations for customization.

However, when customizing your mail environment, first try to change
what you want in MH, and only change MH-E if changing MH is not
possible. That way you will get the same behavior inside and outside
GNU Emacs. Note that MH-E does not provide hooks for customizations
that can be done in MH; this omission is intentional.

@cindex Emacs, customizing
@cindex Emacs, setting options
@cindex customizing MH-E
@cindex setting options
@findex customize-option
@vindex mh-lpr-command-format, example

Many string or integer options are easy to modify using @kbd{M-x
customize-option}. For example, to modify the option that controls
printing, you would run @kbd{M-x customize-option @key{RET}
mh-lpr-command-format @key{RET}}. In the buffer that appears, modify
the string to the right of the variable. For example, you may change
the @command{lpr} command with @samp{nenscript -G -r -2 -i'%s'}. Then
use the @samp{State} combobox and select @samp{Save for Future
Sessions}. @ref{Printing} talks more about this option.

@vindex mh-bury-show-buffer-flag, example

Options can also hold boolean values. In Emacs Lisp, the boolean
values are @code{nil}, which means false, and @code{t}, which means
true. The @code{customize-option} function makes it easy to change
boolean values; simply click on the toggle button in the customize
buffer to switch between @samp{on} (@code{t}) and @samp{off}
(@code{nil}). For example, try setting @code{mh-bury-show-buffer-flag}
to @samp{off} to keep the MH-Show buffer at the top of the buffer
stack. Use the @samp{State} combobox and choose @samp{Set for Current
Session} to see how the option affects the show buffer. Then choose
the @samp{Erase Customization} menu item to reset the option to the
default, which places the MH-Show buffer at the bottom of the buffer
stack.

The text usually says to turn on an option by setting it to a
@emph{non-@code{nil}} value, because sometimes values other than
@samp{on} are meaningful (for example, see @code{mhl-formfile},
described in @ref{Viewing}). Other options, such as hooks, involve a
little more Emacs Lisp programming expertise.

@cindex @samp{mh} customization group
@cindex customization group, @samp{mh}
@findex customize-group

You can browse all of the MH-E options with the @code{customize-group}
function. Try entering @kbd{M-x customize-group @key{RET} mh
@key{RET}} to view the top-level options as well as buttons for all of
the MH-E customization groups.

@need 1000

While options can be set via Emacs customization, variables must be
modified using Emacs Lisp. For example:

@vindex mh-progs, example

@lisp
(setq mh-progs "/usr/local/bin/mh/")
@end lisp

@cindex @file{.emacs}
@cindex files, @file{.emacs}

Any such modifications should be placed in @file{~/.emacs}.

You can ``preview'' the effects of changing variables before
committing the changes to @file{~/.emacs}. Variables can be changed in
the current Emacs session by using @kbd{M-x set-variable}.

@cindex Emacs, Emacs Lisp manual
@cindex Emacs, info
@cindex Emacs, online help
@cindex info
@cindex online help

I hope I've included enough examples here to get you well on your way.
If you want to explore Emacs Lisp further, a programming manual does
exist,
@c Yes, some of the stuff in the following sections is redundant, but
@c TeX barfs if the @ifs are inside the @footnote.
@iftex
@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available
online in the Info system by typing @kbd{C-h i m Emacs Lisp
@key{RET}}. If not, you can order a printed manual, which has the
desirable side-effect of helping to support the Free Software
Foundation which made all this great software available. You can find
an order form by running @kbd{C-h C-d}, or you can request an order
form from @i{gnu at gnu.org}.}
@end iftex
@ifinfo
@footnote{Perhaps you can find the online version of @ref{Top, The GNU
Emacs Lisp Reference Manual, , elisp, GNU Emacs Lisp Reference
Manual}. If not, you can order a printed manual, which has the
desirable side-effect of helping to support the Free Software
Foundation which made all this great software available. You can find
an order form by running @kbd{C-h C-d}, or you can request an order
form from @i{gnu at gnu.org}.}
@end ifinfo
@ifhtml
@footnote{Perhaps you can find the online version of
@uref{http://www.gnu.org/manual/elisp-manual-21-2.8/html_node/elisp.html,
The GNU Emacs Lisp Reference Manual}. If not, you can order a printed
manual, which has the desirable side-effect of helping to support the
Free Software Foundation which made all this great software available.
You can find an order form by running @kbd{C-h C-d}, or you can
request an order form from @i{gnu at gnu.org}.}
@end ifhtml
and you can look at the code itself for examples. Look in the Emacs
Lisp directory on your system (such as
@file{/usr/local/lib/emacs/lisp/mail}) and find all the @file{mh-*.el}
files there. When calling MH-E and other Emacs Lisp functions directly
from Emacs Lisp code, you'll need to know the correct arguments. Use
the online help for this. For example, try @kbd{C-h f
mh-execute-commands @key{RET}}. If you write your own functions,
please do not prefix your symbols (variables and functions) with
@samp{mh-}. This prefix is reserved for the MH-E package. To avoid
conflicts with existing MH-E symbols, use a prefix like @samp{my-} or
your initials.

@node Ranges, Folder Selection, Using This Manual, Top
@chapter Ranges

@c Customization Group: mh-ranges
@c Menu: 

@cindex ranges
@cindex message abbreviations
@cindex message ranges

Many commands that operate on individual messages, such as
@code{mh-forward} or @code{mh-refile-msg} take a @code{RANGE}
argument. This argument can be used in several ways.

If you provide the prefix argument @kbd{C-u} to these commands, then
you will be prompted for the message range. This can be any legal MH
range which can include messages, sequences (@pxref{Sequences}), and
the abbreviations (described in the @command{mh}(1) man page):

@table @samp
@item <num1>-<num2>
Indicates all messages in the range <num1> to <num2>, inclusive. The
range must be nonempty.

@item <num>:N
@item <num>:+N
@itemx <num>:-N
Up to N messages beginning with (or ending with) message num. Num may
be any of the pre-defined symbols: first, prev, cur, next or last.

@item first:N
@itemx prev:N
@itemx next:N
@itemx last:N
The first, previous, next or last messages, if they exist.

@item all
All of the messages.
@end table

For example, a range that shows all of these things is @samp{1 2 3
5-10 last:5 unseen}.

@vindex transient-mark-mode

If the option @code{transient-mark-mode} is set to @code{t} and you
set a region in the MH-Folder buffer, then the MH-E command will
perform the operation on all messages in that region.

@node Folder Selection, Incorporating Mail, Ranges, Top
@chapter Folder Selection

@c Customization Group: mh-folder-selection
@c Menu: 

@cindex folders, selecting

When you choose a folder in MH-E via a command such as @kbd{o}
(@code{mh-refile-msg}), completion is used to enter the folder
@ifnothtml
(@pxref{Completion, , , emacs, The GNU Emacs Manual}).
@end ifnothtml
@ifhtml
(see the section
@uref{http://www.gnu.org/software/emacs/manual/html_node/emacs_34.html#SEC34,
Completion} in @cite{The GNU Emacs Manual}).
@end ifhtml
In addition, MH-E has several ways of choosing a suitable default so
that the folder can often be selected with a single @key{RET} key.

@cindex @samp{mh-folder-selection} customization group
@cindex customization group, @samp{mh-folder-selection}

The @samp{mh-folder-selection} customization group contains some
options which are used to help with this.

@vtable @code
@item mh-default-folder-for-message-function
Function to select a default folder for refiling or @samp{Fcc}
(default: @code{nil}).

@item mh-default-folder-list
List of addresses and folders (default: @code{nil}).

@item mh-default-folder-must-exist-flag
Non-nil means guessed folder name must exist to be used (default:
@code{t}).

@item mh-default-folder-prefix
Prefix used for folder names generated from aliases (default: @code{""}).
@end vtable

You can set the option @code{mh-default-folder-for-message-function}
to a function that provides a default folder for the message to be
refiled. The current buffer is set to the message being refiled with
point at the start of the message. This function should return the
default folder as a string with a leading @samp{+} sign. It can also
return @code{nil} so that the last folder name is used as the default,
or an empty string to suppress the default entirely.

Otherwise, the name of the destination folder is derived from the
sender as follows:

@enumerate
@item
The folder name associated with the first address found in the list
@code{mh-default-folder-list} is used. Each element in this list
contains a @samp{Check Recipient} item. If this item is turned on,
then the address is checked against the recipient instead of the
sender. This is useful for mailing lists.

@item
An alias prefixed by @code{mh-default-folder-prefix} corresponding to
the address is used. The prefix is used to prevent clutter in your
mail directory. @xref{Aliases}.
@end enumerate

If the derived folder does not exist, and
@code{mh-default-folder-must-exist-flag} is @code{t}, then the last
folder name used is suggested. This is useful if you get mail from
various people for whom you have an alias, but file them all in the
same project folder.

@node Incorporating Mail, Reading Mail, Folder Selection, Top
@chapter Incorporating Your Mail

@c Customization Group: mh-inc
@c Menu: Folder (mh-inc-folder)

@cindex incorporating

This chapter talks about getting mail from your system mailbox into
your MH @samp{+inbox} folder. The following command accomplishes that.

@table @kbd
@findex mh-inc-folder
@kindex i
@item i
Incorporate new mail into folder (@code{mh-inc-folder}).
@end table

@cindex @samp{mh-inc} customization group
@cindex customization group, @samp{mh-inc}

The following option in the @samp{mh-inc} customization group is used.

@vtable @code
@item mh-inc-prog
Program to incorporate mail (default: @samp{"inc"}).
@end vtable

The following hook is available.

@vtable @code
@item mh-inc-folder-hook
Functions to run when incorporating mail (default: @code{nil}).
@end vtable

If at any time you receive new mail, incorporate the new mail into
your @samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}). Note
that @kbd{i} will display the @samp{+inbox} buffer, even if there
isn't any new mail. You can incorporate mail from any file into the
current folder by specifying a prefix argument; you'll be prompted for
the name of the file to use (for example, @kbd{C-u i ~/mbox
@key{RET}}).

@cindex @file{.emacs}
@cindex Emacs, notification of new mail
@cindex files, @file{.emacs}
@cindex new mail
@cindex notification of new mail

Emacs can notify you when you have new mail by displaying @samp{Mail}
in the mode line. To enable this behavior, and to have a clock in the
mode line besides, add the following to @file{~/.emacs}:

@findex display-time

@lisp
(display-time)
@end lisp

@cindex @command{inc}
@cindex MH commands, @command{inc}
@cindex incorporating
@vindex mh-progs

The name of the program that incorporates new mail is stored in
@code{mh-inc-prog}; it is @samp{"inc"} by default. This program
generates a one-line summary for each of the new messages. Unless it
is an absolute pathname, the file is assumed to be in the
@code{mh-progs} directory. You may also link a file to @command{inc}
that uses a different format (see @samp{mh-profile}(5), and sections
@uref{@value{MH-BOOK-HOME}/reapre.htm, Reading Mail: inc show next
prev} and @uref{@value{MH-BOOK-HOME}/mhstr.htm, MH Format Strings} in
the MH book). You'll then need to modify several variables
appropriately (@pxref{Scan Line Formats}).

You can set the hook @code{mh-inc-folder-hook}, which is called after
new mail is incorporated by the @kbd{i} (@code{mh-inc-folder})
command. A good use of this hook is to rescan the whole folder either
after running @kbd{M-x mh-rmail} the first time or when you've changed
the message numbers from outside of MH-E.

@findex mh-execute-commands
@findex mh-rescan-folder, example
@findex mh-show, example
@vindex mh-inc-folder-hook, example

@smalllisp
@group
(defun my-mh-inc-folder-hook ()
  "Hook to rescan folder after incorporating mail."
  (if (buffer-modified-p)            ; @r{if outstanding refiles and deletes,}
      (mh-execute-commands))         ;   @r{carry them out}
  (mh-rescan-folder)                 ; @r{synchronize with +inbox}
  (mh-show))                         ; @r{show the current message}

(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook)

@i{Rescan folder after incorporating new mail via mh-inc-folder-hook}

@end group
@end smalllisp

@node Reading Mail, Folders, Incorporating Mail, Top
@chapter Reading Your Mail

@c Customization Group: mh-show
@c Menu: Message

@cindex MH-Folder mode
@cindex MH-Show mode
@cindex modes, MH-Folder
@cindex modes, MH-Show
@cindex reading mail
@cindex scan lines
@findex mh-rmail

The MH-E entry point for reading mail is @kbd{M-x mh-rmail}. This
command incorporates your mail and creates a buffer called
@samp{+inbox} in MH-Folder mode. The @kbd{M-x mh-rmail} command shows
you only new mail, not mail you have already read@footnote{If you want
to see your old mail as well, use @kbd{F r} to pull all your messages
into MH-E. Or, give a prefix argument to @code{mh-rmail} so it will
prompt you for folder to visit like @kbd{F v} (for example, @kbd{C-u
M-x mh-rmail @key{RET} bob @key{RET}}). @xref{Folders}.}. The
@samp{+inbox} buffer contains @dfn{scan lines}, which are one-line
summaries of each incorporated message. You can perform most MH
commands on these messages via one- or two-letter commands in either
the MH-Folder or MH-Show buffers. See @command{scan}(1) for a
description of the contents of the scan lines, and see the Figure in
@ref{Reading Mail Tour}, for an example.

@table @kbd
@kindex RET
@kindex . (period)
@findex mh-show
@item RET
@itemx . (period)
Display a message (@code{mh-show}).

@kindex , (comma)
@findex mh-header-display
@item , (comma)
Display a message with all header fields (@code{mh-header-display}).

@kindex |
@findex mh-pipe-msg
@item |
Pipe message through shell command (@code{mh-pipe-msg}).

@kindex SPC
@findex mh-page-msg
@item SPC
Go to next page in message (@code{mh-page-msg}).

@kindex BS
@findex mh-previous-page
@item BS
Go to previous page in message (@code{mh-previous-page}).

@kindex C-d
@findex mh-delete-msg-no-motion
@item C-d
Delete message, don't move to next message
(@code{mh-delete-msg-no-motion}).

@kindex C-o
@findex mh-write-msg-to-file
@item C-o
Output (write) message to file (@code{mh-write-msg-to-file}).

@kindex d
@findex mh-delete-msg
@item d
Delete message (@code{mh-delete-msg}).

@kindex D SPC
@findex mh-page-digest
@item D SPC
Go to next message in digest (@code{mh-page-digest}).

@kindex D BS
@findex mh-page-digest-backwards
@item D BS
Go to previous message in digest (@code{mh-page-digest-backwards}).

@kindex D b
@findex mh-burst-digest
@item D b
Break up digest into separate messages (@code{mh-burst-digest}).

@kindex g
@findex mh-goto-msg
@item g
Go to a message (@code{mh-goto-msg}).

@kindex l
@findex mh-print-msg
@item l
Print message with @command{lpr} (@code{mh-print-msg}).

@kindex M-<
@findex mh-first-msg
@item M-<
Go to first message (@code{mh-first-msg}).

@kindex M->
@findex mh-last-msg
@item M->
Go to last message (@code{mh-last-msg}).

@kindex n
@findex mh-next-undeleted-msg
@item n
Display next message (@code{mh-next-undeleted-msg}).

@kindex p
@findex mh-previous-undeleted-msg
@item p
Display previous message (@code{mh-previous-undeleted-msg}).

@kindex X s
@findex mh-store-msg
@item X s
Unpack message created with @command{uudecode} or @command{shar}
(@code{mh-store-msg}).
@end table

@cindex @samp{mh-show} customization group
@cindex customization group, @samp{mh-show}

The following table lists options in the @samp{mh-show} customization
group that are used while reading mail.

@vtable @code
@item mh-bury-show-buffer-flag
Leave show buffer at bottom of stack (default: @code{t}).

@item mh-clean-message-header-flag
Non-nil means remove extraneous header fields (default: @samp{on}).

@item mh-do-not-confirm-flag
Don't confirm on non-reversible commands (default: @code{nil}).

@item mh-fetch-x-image-url
Control fetching of @samp{X-Image-URL:} header field image (default:
@code{'ask}).

@item mh-invisible-header-fields
Additional header fields to hide (default: nil).

@item mh-invisible-header-fields-default
List of hidden header fields (default: a checklist too long to list
here).

@item mh-lpr-command-format
Command used to print (default: @samp{"lpr -J '%s'"}).

@item mh-print-background-flag
Print in foreground or background (default: @code{nil}).

@item mh-show-buffer-mode-line-buffer-id
Name of show buffer in mode line (default: @samp{"@{show-%s@} %d"}).

@item mh-show-use-xface-flag
Non-nil means display face images in @code{mh-show-mode} (default:
@code{t} if your version of Emacs is 21 or greater).

@item mh-store-default-directory
Default directory for storing files created by @command{uuencode} or
@command{shar} (default: @code{nil}).

@item mh-summary-height
Number of scan lines to show (includes mode line) (default: 4).

@item mhl-formfile
Format file for @command{mhl} (default: @code{nil}).
@end vtable

The following hooks are available.

@vtable @code
@item mh-delete-msg-hook
Functions to run when deleting messages (default: @code{nil}).

@item mh-folder-mode-hook
Functions to run in MH-Folder mode (default: @code{nil}).

@item mh-show-hook
Functions to run when showing message (default: @code{nil}).

@item mh-show-mode-hook
Functions to run when showing message (default: @code{nil}).
@end vtable

The functions and variables introduced here are explained in more
detail in the following sections.

@menu
* MH-Folder Options::             
* Viewing::                     
* Viewing Attachments::         
* HTML::                        
* Digests::                     
* Reading PGP::                 
* Printing::                    
* Files and Pipes::             
* Navigating::                  
@end menu

@node MH-Folder Options, Viewing, Reading Mail, Reading Mail
@section MH-Folder Mode Options

@vindex mh-do-not-confirm-flag

If you never make mistakes, and you do not like confirmations for your
actions, you can set @code{mh-do-not-confirm-flag} to a non-@code{nil}
value to disable confirmation for unrecoverable commands such as
@kbd{x} (@code{mh-execute-commands})@footnote{In previous versions of
MH-E, this option suppressed the confirmation in
@code{mh-kill-folder}. Since this kept most users from setting this
option, @code{mh-kill-folder} has been modified in version 6.0 to
always ask for confirmation.}. Here's how you set boolean values:

@lisp
(setq mh-do-not-confirm-flag t)
@end lisp

@cindex MH-Folder mode
@cindex modes, MH-Folder

@vindex mh-summary-height

The variable @code{mh-summary-height} controls the number of scan
lines displayed in the MH-Folder window, including the mode line. The
default value of 4 means that 3 scan lines are displayed. Here's how
you set numerical values:

@lisp
(setq mh-summary-height 2)              ; @r{only show the current scan line}
@end lisp

@vindex mh-bury-show-buffer-flag

Normally the buffer for displaying messages is buried at the bottom at
the buffer stack. You may wish to disable this feature by setting
@code{mh-bury-show-buffer-flag} to @code{nil}. One advantage of not
burying the show buffer is that one can delete the show buffer more
easily in an electric buffer list because of its proximity to its
associated MH-Folder buffer. Try running @kbd{M-x
electric-buffer-list} to see what I mean.

@vindex mh-folder-mode-hook

The hook @code{mh-folder-mode-hook} is called when a new folder is
created with MH-Folder mode. This could be used to set your own key
bindings, for example:

@vindex mh-folder-mode-hook, example

@smalllisp
@group
(defvar my-mh-init-done nil "Non-@code{nil} when one-time MH-E settings made.")

(defun my-mh-folder-mode-hook ()
  "Hook to set key bindings in MH-Folder mode."
  (if (not my-mh-init-done)             ; @r{only need to bind the keys once }
      (progn
        (local-set-key "/" 'search-msg)
        (local-set-key "b" 'mh-burst-digest)    ; @r{better use of @kbd{b}}
        (setq my-mh-init-done t))))

;;; @r{Emacs 19}
(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook)
;;; @r{Emacs 18}
;;;   @r{(setq mh-folder-mode-hook (cons 'my-mh-folder-mode-hook}
;;;                               @r{mh-folder-mode-hook))}

(defun search-msg ()
  "Search for a regexp in the current message."
  (interactive)                         ; @r{user function}
  (save-window-excursion
    (other-window 1)                    ; @r{go to next window}
    (isearch-forward-regexp)))          ; @r{string search; hit return (ESC}
                                        ;   @r{in Emacs 18) when done}

@i{Create additional key bindings via mh-folder-mode-hook}

@end group
@end smalllisp

@cindex @file{.emacs}
@cindex files, @file{.emacs}
@cindex reading mail

Before we leave this section, I'll include a function that I use as a
front end to MH-E@footnote{Stephen Gildea's favorite binding is
@kbd{(global-set-key "\C-cr" 'mh-rmail)}.}. It toggles between your
working window configuration, which may be quite involved---windows
filled with source, compilation output, man pages, and other
documentation---and your MH-E window configuration. Like the rest of
the customization described in this section, simply add the following
code to @file{~/.emacs}.

@iftex
@filbreak
@end iftex

@findex mh-rmail, example

@smalllisp
@group
(defvar my-mh-screen-saved nil
  "Set to non-@code{nil} when MH-E window configuration shown.")
(defvar my-normal-screen nil "Normal window configuration.")
(defvar my-mh-screen nil "MH-E window configuration.")

(defun my-mh-rmail (&optional arg)
  "Toggle between MH-E and normal screen configurations.
With non-@code{nil} or prefix argument, @i{inc} mailbox as well
when going into mail."
  (interactive "P")                 ; @r{user callable function, P=prefix arg}
  (setq my-mh-screen-saved          ; @r{save state}
        (cond
         ;; @r{Bring up MH-E screen if arg or normal window configuration.}
         ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.}
         ((or arg (null my-mh-screen-saved))
          (setq my-normal-screen (current-window-configuration))
          (if (or arg (null (get-buffer "+inbox")))
              (mh-rmail)
            (set-window-configuration my-mh-screen))
          t)                        ; @r{set my-mh-screen-saved to @code{t}}
         ;; @r{Otherwise, save MH-E screen and restore normal screen.}
         (t
          (setq my-mh-screen (current-window-configuration))
          (set-window-configuration my-normal-screen)
          nil))))                   ; @r{set my-mh-screen-saved to nil}

(global-set-key "\C-x\r" 'my-mh-rmail)  ;@r{ call with C-x RET}

@i{Starting MH-E}

@end group
@end smalllisp

If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved} is
@code{nil} (meaning a non-MH-E window configuration), the current
window configuration is saved, either the @samp{+inbox} buffer is
displayed or @code{mh-rmail} is run, and the MH-E window configuration
is shown. Otherwise, the MH-E window configuration is saved and the
original configuration is displayed.

@node Viewing, Viewing Attachments, MH-Folder Options, Reading Mail
@section Viewing Your Mail

@findex mh-header-display
@findex mh-page-msg
@findex mh-previous-page
@findex mh-show
@kindex , (comma)
@kindex . (period)
@kindex BS
@kindex RET
@kindex SPC

The @kbd{RET} (@code{mh-show}) command displays the message that the
cursor is on. If the message is already displayed, it scrolls to the
beginning of the message. Use @key{SPC} (@code{mh-page-msg}) and
@key{BS} (@code{mh-previous-page}) to move forwards and backwards one
page at a time through the message. You can give either of these
commands a prefix argument that specifies the number of lines to
scroll (such as @kbd{10 SPC}). MH-E normally hides a lot of the
superfluous header fields that mailers add to a message, but if you
wish to see all of them, use the @kbd{,} (comma;
@code{mh-header-display}) command.

@vindex mh-clean-message-header-flag
@vindex mh-invisible-header-fields-default
@vindex mh-invisible-header-fields

Several variables control what displayed messages look like. Normally
messages are delivered with a handful of uninteresting header fields.
These are hidden by turning the option
@code{mh-clean-message-header-flag} on (which it is by default). The
header fields listed in the @code{mh-invisible-header-fields-default}
option are hidden, although you can check off any field that you would
like to see. Header fields that you would like to hide that aren't
listed can be added to the @code{mh-invisible-header-fields} option
with a couple of caveats. Regular expressions are not allowed. Unique
fields should have a @samp{:} suffix; otherwise, the element can be
used to render invisible an entire class of fields that start with the
same prefix. If you think this header field should be generally
ignored, report a bug (@pxref{Bug Reports}).

@cindex @samp{Face:} header field
@cindex @samp{X-Face:} header field
@cindex @samp{X-Image-URL:} header field
@cindex header field, @samp{Face:}
@cindex header field, @samp{X-Face:}
@cindex header field, @samp{X-Image-URL:}

MH-E can display the content of @samp{Face:}, @samp{X-Face:}, and
@samp{X-Image-URL:} header fields. If any of these fields occur in the
header of your message, the sender's face will appear in the
@samp{From:} header field. If more than one of these fields appear,
then the first field found in the order @samp{Face:}, @samp{X-Face:},
and @samp{X-Image-URL:} will be used. Note that versions of GNU Emacs
prior to 21.1 don't support the display of inline images, so face
images are not displayed in these versions.

@vindex mh-show-use-xface-flag

The option @code{mh-show-use-xface-flag} is used to turn this feature
on and off. This feature will be turned on by default if your system
supports it.

@cindex @command{uncompface}
@cindex Emacs, packages, x-face
@cindex Unix commands, @command{uncompface}

The first header field used, if present, is the Gnus-specific
@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU
Emacs 21 and XEmacs. For more information, see
@uref{http://quimby.gnus.org/circus/face/}}. Next is the traditional
@samp{X-Face:} header field@footnote{The display of this field
requires the @command{uncompface} program which can be obtained from
@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z}.
Recent versions of XEmacs have internal support for @samp{X-Face:}
images. If your version of XEmacs does not, then you'll need both
@command{uncompface} and the @samp{x-face} package which is available
at @uref{ftp://ftp.jpl.org/pub/elisp/}.}.

@cindex @command{convert}
@cindex @command{wget}
@cindex ImageMagick
@cindex Unix commands, @command{convert}
@cindex Unix commands, @command{wget}

Finally, MH-E will display images referenced by the
@samp{X-Image-URL:} header field if neither the @samp{Face:} nor the
@samp{X-Face:} fields are present@footnote{The display of the images
requires the @command{wget} program, available from
@uref{http://www.gnu.org/software/wget/wget.html}, to fetch the image
and the @command{convert} program from the ImageMagick suite,
available from @uref{http://www.imagemagick.org/}.}. Of the three
header fields this is the most efficient in terms of network usage
since the image doesn't need to be transmitted with every single mail.

@vindex mh-fetch-x-image-url

The option @code{mh-fetch-x-image-url} controls the fetching of the
@samp{X-Image-URL:} header field image with the following three
values:

@table @samp
@item Ask Before Fetching
You are prompted before the image is fetched. MH-E will remember your
reply and will either use the already fetched image the next time the
same URL is encountered or silently skip it if you didn't fetch it the
first time. This is a good setting.

@item Never Fetch
Images are never fetched and only displayed if they are already
present in the cache. This is the default.
@end table

There isn't a value of @samp{Always Fetch} for privacy and DOS (denial
of service) reasons. For example, fetching a URL can tip off a spammer
that you've read his email. Someone may also flood your network and
fill your disk drive by sending a torrent of messages, each specifying
a unique URL to a very large file.

@cindex @file{.mhe-x-image-cache}
@cindex files, @file{.mhe-x-image-cache}

The cache of images is found in the directory
@file{.mhe-x-image-cache} within your MH directory. You can add your
own face to the @samp{From:} field too (@pxref{Picture}).

@cindex @command{mhl}
@cindex MH commands, @command{mhl}
@vindex mhl-formfile

Normally MH-E takes care of displaying messages itself (rather than
calling an MH program to do the work). If you'd rather have @command{mhl}
display the message (within MH-E), set the variable
@code{mhl-formfile} to a non-@code{nil} value. You can set this
variable either to @code{t} to use the default format file or to a
filename if you have your own format file (@command{mhl}(1) or section
@uref{@value{MH-BOOK-HOME}/shomes.htm#Usisho, Using mhl}
in the MH book tells you how
to write one). When writing your own format file, use a nonzero value
for @samp{overflowoffset} to ensure the header is RFC 822 compliant
and parsable by MH-E. @command{mhl} is always used for printing and
forwarding; in this case, the value of @code{mhl-formfile} is
consulted if it is a filename.

@cindex signature separator
@cindex vCard

MH-E normally renders signatures and vCards in italics so that the
body of the message stands out more. MH-E depends on the presence of
the @dfn{signature separator} ("@samp{-- }") to do this.

@vindex mh-show-mode-hook

Two hooks can be used to control how messages are displayed. The first
hook, @code{mh-show-mode-hook}, is called early on in the process of
displaying of messages. It is used to perform some actions on the
contents of messages, such as highlighting the header fields. If
you're running Emacs 19 under the X Window System, the following
example will highlight the @samp{From:} and @samp{Subject:} header
fields. This is a very nice feature indeed.

@vindex mh-show-mode-hook, example

@smalllisp
@group
(defvar my-mh-keywords
   '(("^From: \\(.*\\)" 1 'bold t)
     ("^Subject: \\(.*\\)" 1 'highlight t))
  "MH-E additions for font-lock-keywords.")

(defun my-mh-show-mode-hook ()
  "Hook to turn on and customize fonts."
  (font-lock-add-keywords nil my-mh-keywords))

(add-hook 'mh-show-mode-hook 'my-mh-show-mode-hook))

@i{Emphasize header fields in different fonts via mh-show-mode-hook}

@end group
@end smalllisp

@vindex mh-show-hook

The second hook, @code{mh-show-hook}, is the last thing called after
messages are displayed. It's used to affect the behavior of MH-E in
general or when @code{mh-show-mode-hook} is too early.

@vindex mh-show-buffer-mode-line-buffer-id
@cindex MH-Show mode
@cindex modes, MH-Show

For those who like to modify their mode lines, use
@code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in
the MH-Show buffers. Place the two escape strings @samp{%s} and
@samp{%d}, which will display the folder name and the message number,
respectively, somewhere in the string in that order. The default value
of @samp{"@{show-%s@} %d"} yields a mode line of

@smallexample
-----@{show-+inbox@} 4      (MH-Show)--Bot--------------------------------
@end smallexample

@node Viewing Attachments, HTML, Viewing, Reading Mail
@section Viewing Attachments

@cindex @command{mhshow}
@cindex @command{show}
@cindex MH commands, @command{mhshow}
@cindex MH commands, @command{show}
@cindex MIME
@cindex multimedia mail

MH has the ability to display @dfn{@sc{mime}} (Multipurpose Internet
Mail Extensions) messages. Unfortunately, MH-E does not yet have this
ability, so you have to use the MH commands
@command{show}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/reapre.htm, Reading Mail: inc show next
prev} in the MH book.} or @command{mhshow}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/usimim.htm#ReMIMa, Reading MIME Mail} in
the MH book.} from the shell to read @sc{mime} messages@footnote{You
can call them directly from Emacs if you're running the X Window
System: type @kbd{M-! xterm -e mhshow @var{message-number}}. You can
leave out the @samp{xterm -e} if you use @command{mhlist} or
@command{mhstore}.}.

@c For additional information on buttons, see (gnus) Article Buttons. XXX

@node HTML, Digests, Viewing Attachments, Reading Mail
@section HTML

@cindex HTML
@cindex Gnus
@vindex mm-text-html-renderer

MH-E can display messages that have been sent in HTML@footnote{This
feature depends on post-5.10 versions of Gnus.}. The browser used
depends on the setting of @code{mm-text-html-renderer}. @xref{Display
Customization, , , emacs-mime, Emacs MIME}, and the documentation for
@kbd{W h} (@pxref{Article Washing, , , gnus, The Gnus Newsreader}),
for additional information. The default setting is set automatically
based upon the presence of a known browser on your system. If you wish
to use a different browser, then set this option accordingly. See the
documentation for the browser you use for additional information on
how to use it.

@cindex Emacs, packages, w3m
@cindex w3m

For example, if you're using the built-in browser @samp{w3m}, the
content of the message will appear in the MH-Show buffer if the entire
message is HTML, or there is an inline HTML body part. If there is an
HTML body part that is an attachment, then you'll see a button like
this:

@example
[1. text/html; foo.html]...
@end example

You can read the contents of this body part using the methods
described in @ref{Reading Mail}.

@node Digests, Reading PGP, HTML, Reading Mail
@section Digests

@cindex digests
@findex mh-page-digest
@findex mh-page-digest-backwards
@kindex BS
@kindex D BS
@kindex D SPC
@kindex SPC

A digest is a message that contains other messages. Special MH-E
commands let you read digests conveniently. You can use @key{SPC} and
@key{BS} to page through the digest as if it were a normal message,
but if you wish to skip to the next message in the digest, use
@kbd{D SPC} (@code{mh-page-digest}). To return to a previous message,
use @kbd{D BS} (@code{mh-page-digest-backwards}).

@cindex @command{burst}
@cindex MH commands, @command{burst}
@cindex MH-Folder Show mode
@cindex modes, MH-Folder Show
@findex mh-burst-digest
@kindex D b
@kindex d
@kindex t

Another handy command is @kbd{D b} (@code{mh-burst-digest}). This
command uses the MH command @command{burst}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/burdig.htm, Bursting Messages} in the MH
book.} to break out each message in the digest into its own message.
Using this command, you can quickly delete unwanted messages, like
this: Once the digest is split up, toggle out of MH-Folder Show mode
with @kbd{t} (@pxref{Folders}) so that the scan lines fill the screen
and messages aren't displayed. Then use @kbd{d} (@pxref{Reading Mail})
to quickly delete messages that you don't want to read (based on the
@samp{Subject:} header field). You can also burst the digest to reply
directly to the people who posted the messages in the digest. One
problem you may encounter is that the @samp{From:} header fields are
preceded with a @samp{>} so that your reply can't create the
@samp{To:} field correctly. In this case, you must correct the
@samp{To:} field yourself. This is described later (@pxref{Editing
Drafts}).

@node Reading PGP, Printing, Digests, Reading Mail
@section Signed and Encrypted Messages

@cindex GPG
@cindex GnuPG
@cindex Gnus
@cindex OpenPGP
@cindex PGP
@cindex RFC 3156
@cindex encrypted messages
@cindex security
@cindex signed messages

You can read encrypted or signed PGP or GPG messages with
MH-E@footnote{This feature depends on post-5.10 versions of Gnus.
@cite{MIME Security with OpenPGP} is documented in
@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. However,
MH-E can also decrypt old-style PGP messages that are not in MIME
format.}. This section assumes that you already have a good
understanding of GPG and have set up your keys appropriately.

If someone sends you a signed message, here is what you'll see:

@smallexample
@group
[[PGP Signed Part:Bill Wohler <wohler@@stop.mail-abuse.org>]]
This is a signed message.

[[End of PGP Signed Part]]
@end group
@end smallexample

@cindex keychain
@cindex keyserver
@cindex signed messages

If the key for the given signature is not in your keychain, you'll be
given the opportunity to fetch the key from a keyserver and verify the
key. If the message is really large, the verification process can take
a long time. You can press @kbd{C-g} at any time to
cancel@footnote{Unfortunately in the current version, the validation
process doesn't display a message so it appears that MH-E has hung. We
hope that this will be fixed in the future.}.

If the signature doesn't check out, you might see something like this:

@example
@group
[[PGP Signed Part:Failed]]
This is a signed message.
This is garbage added after the signature was made.

[[End of PGP Signed Part]]
@end group
@end example

@cindex decrypting messages

If someone sends you an encrypted message, MH-E will ask for your
passphrase to decrypt the message. You should see something like this:

@example
@group
[[PGP Encrypted Part:OK]]

[[PGP Signed Part:Bill Wohler <wohler@@stop.mail-abuse.org>]]
This is the secret message.

[[End of PGP Signed Part]]

[[End of PGP Encrypted Part]]
@end group
@end example

If there is a problem decrypting the message, the button will say:

@example
[[PGP Encrypted Part:Failed]]
@end example

To view the contents of the button, either click it with the middle
mouse button or press @key{RET} when the cursor is over the button. If
the message were corrupted, you'd see this:

@example
[[PGP Encrypted Part:Failed]
Invalid base64 data]
@end example

If your passphrase were incorrect, you'd see something like this:

@example
[GNUPG:] ENC_TO CD9C88BB610BD9AD 1 0
[GNUPG:] USERID_HINT CD9C88BB610BD9AD Bill Wohler <wohler@@stop.mail-abuse.org>
[GNUPG:] NEED_PASSPHRASE CD9C88BB610BD9AD CD9C88BB610BD9AD 1 0
[GNUPG:] BAD_PASSPHRASE CD9C88BB610BD9AD
gpg: encrypted with 1024-bit RSA key, ID 610BD9AD, created 1997-09-09
      "Bill Wohler <wohler@@stop.mail-abuse.org>"
gpg: public key decryption failed: bad passphrase
[GNUPG:] BEGIN_DECRYPTION
[GNUPG:] DECRYPTION_FAILED
gpg: decryption failed: secret key not available
[GNUPG:] END_DECRYPTION

gpg exited abnormally: '2'
@end example

@cindex @samp{pgg} customization group
@cindex PGG
@cindex customization group, @samp{pgg}

The @samp{pgg} customization group may have some settings which may
interest you. 
@iftex
See @cite{The PGG Manual}.
@end iftex
@ifinfo
@xref{Top, , The PGG Manual, pgg, The PGG Manual}.
@end ifinfo
@ifhtml
See
@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html,
@cite{The PGG Manual}}.
@end ifhtml

@node Printing, Files and Pipes, Reading PGP, Reading Mail
@section Printing Your Mail

@cindex @command{lpr}
@cindex @command{mhl}
@cindex MH commands, @command{mhl}
@cindex Unix commands, @command{lpr}
@cindex printing
@kindex l

Printing mail is simple. Enter @kbd{l} (@code{mh-print-msg}) (for
@i{l}ine printer or @i{l}pr). The message is formatted with
@command{mhl}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/shomes.htm#Usisho, Using mhl} in the MH
book.} and printed with the @command{lpr} command. You can print all
the messages in a range (as in @kbd{C-u l 1 3 5-7 last:5 frombob
@key{RET}}, @pxref{Ranges}).

@cindex @command{lpr}
@cindex Unix commands, @command{lpr}
@vindex mh-lpr-command-format
@vindex mh-print-background-flag

Normally messages are printed in the foreground. If this is slow on
your system, you may elect to set @code{mh-print-background-flag} to
non-@code{nil} to print in the background. If you do this, do not
delete the message until it is printed or else the output may be
truncated. The variable @code{mh-lpr-command-format} controls how the
printing is actually done. The string can contain one escape,
@samp{%s}, which is filled with the name of the folder and the message
number and is useful for print job names. As an example, the default
is @samp{"lpr -J '%s'"}.

@node Files and Pipes, Navigating, Printing, Reading Mail
@section Files and Pipes

@cindex files
@cindex pipes
@findex mh-write-msg-to-file
@kindex C-o

MH-E does offer a couple of commands that are not a part of MH@. The
first one, @kbd{C-o} (@code{mh-write-msg-to-file}), writes a message
to a file (think of the @kbd{o} as in "output"). You are prompted for
the filename. If the file already exists, the message is appended to
it. You can also write the message to the file without the header by
specifying a prefix argument (such as @kbd{C-u C-o /tmp/foobar
@key{RET}}). Subsequent writes to the same file can be made with the
@kbd{!} command.

@findex mh-pipe-msg
@kindex |

You can also pipe the message through a Unix shell command with the
@kbd{|} (@code{mh-pipe-msg}) command. You are prompted for the Unix
command through which you wish to run your message. If you give an
argument to this command, the message header is included in the text
passed to the command (the contrived example @kbd{C-u | lpr} would be
done with the @kbd{l} command instead).

@cindex @command{shar}
@cindex @command{uuencode}
@cindex Unix commands, @command{shar}
@cindex Unix commands, @command{uuencode}
@findex mh-store-msg
@kindex X s

If the message is a shell archive @command{shar} or has been run through
@command{uuencode} use @kbd{X s} (@code{mh-store-msg}) to extract the
body of the message. The default directory for extraction is the
current directory, and you have a chance to specify a different
extraction directory. The next time you use this command, the default
directory is the last directory you used.

@vindex mh-store-default-directory

The initial directory for the @code{mh-store-msg} command is held in
@code{mh-store-default-directory}. Since I almost always run
@code{mh-store-msg} on sources, I set it to my personal source
directory like this:

@vindex mh-store-default-directory, example

@lisp
(setq mh-store-default-directory (expand-file-name "~/src/"))
@end lisp

@findex mh-store-buffer

Subsequent incarnations of @code{mh-store-msg} offer the last
directory used as the default. By the way, @code{mh-store-msg} calls
the Emacs Lisp function @code{mh-store-buffer}. I mention this because
you can use it directly if you're editing a buffer that contains a
file that has been run through @command{uuencode} or @command{shar}. For
example, you can extract the contents of the current buffer in your
home directory by typing @kbd{M-x mh-store-buffer @key{RET} ~
@key{RET}}.

@node Navigating,  , Files and Pipes, Reading Mail
@section Navigating

@cindex moving between messages
@findex mh-first-msg
@findex mh-goto-msg
@findex mh-last-msg
@findex mh-next-undeleted-msg
@findex mh-previous-undeleted-msg
@kindex M-<
@kindex M->
@kindex g
@kindex n
@kindex p

To move on to the next message, use the @kbd{n}
(@code{mh-next-undeleted-msg}) command; use the @kbd{p}
(@code{mh-previous-undeleted-msg}) command to read the previous
message. Both of these commands can be given a prefix argument to
specify how many messages to skip (for example, @kbd{5 n}). You can
also move to a specific message with @kbd{g} (@code{mh-goto-msg}). You
can enter the message number either before or after typing @kbd{g}. In
the latter case, Emacs prompts you. Finally, you can go to the first
or last message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->}
(@code{mh-last-msg}) respectively.

@cindex MH-Folder mode
@cindex modes, MH-Folder
@findex next-line
@findex previous-line
@kindex C-n
@kindex C-p

You can also use the Emacs commands @kbd{C-p} (@code{previous-line})
and @kbd{C-n} (@code{next-line}) to move up and down the scan lines in
the MH-Folder window. These commands can be used in conjunction with
@key{RET} to look at deleted or refiled messages.

@cindex deleting messages
@findex mh-delete-msg
@kindex d

To mark a message for deletion, use the @kbd{d} (@code{mh-delete-msg})
command. A @samp{D} is placed by the message in the scan window, and
the next undeleted message is displayed. If the previous command had
been @kbd{p}, then the next message displayed is the first undeleted
message previous to the message just deleted. Use @kbd{n} to force
subsequent @kbd{d} commands to move forward to the next undeleted
message after deleting the message under the cursor.

@findex mh-delete-msg-no-motion
@kindex C-d

You may also specify a range (for example, @kbd{C-u d 1 3 5-7 last:5
frombob RET}, @pxref{Ranges}). The @kbd{x} command actually carries
out the deletion (@pxref{Folders}). @kbd{C-d}
(@code{mh-delete-msg-no-motion}) marks the message for deletion but
leaves the cursor at the current message in case you wish to perform
other operations on the message.

@vindex mh-delete-msg-hook

The hook @code{mh-delete-msg-hook} is called after you mark a message
for deletion. For example, the current maintainer of MH-E used this
once when he kept statistics on his mail usage.

@node Folders, Sending Mail, Reading Mail, Top
@chapter Organizing Your Mail with Folders

@c Customization Group:
@c Menu: Folder
@c Menu: Message (mh-refile-msg, mh-undo, mh-execute-commands, mh-copy-msg)

@c Mark says: XXX
@c > >   Renaming folders
@c > 
@c > We can do that?
@c
@c Using the Emacs dired capability, yes.

@cindex folders
@cindex using folders

This chapter discusses the things you can do with folders within MH-E.

@table @kbd
@kindex !
@findex mh-refile-or-write-again
@item !
Repeat last output command (@code{mh-refile-or-write-again}).

@kindex c
@findex mh-copy-msg
@item c
Copy message to folder (@code{mh-copy-msg}).

@kindex F '
@findex mh-index-ticked-messages
@item F '
Display ticked messages (@code{mh-index-ticked-messages}).

@kindex F S
@findex mh-sort-folder
@item F S
Sort folder (@code{mh-sort-folder}).

@kindex F k
@findex mh-kill-folder
@item F k
Remove folder (@code{mh-kill-folder}).

@kindex F l
@findex mh-list-folders
@item F l
List all folders (@code{mh-list-folders}).

@kindex F n
@findex mh-index-new-messages
@item F n
Display unseen messages (@code{mh-index-new-messages}).

@kindex F p
@findex mh-pack-folder
@item F p
Pack folder (@code{mh-pack-folder}).

@kindex F q
@findex mh-index-sequenced-messages
@item F q
Display messages in any sequence (@code{mh-index-sequenced-messages}).

@kindex F r
@findex mh-rescan-folder
@item F r
Regenerate scan lines (@code{mh-rescan-folder}).

@kindex F s
@findex mh-search-folder
@item F s
Search folder for messages matching a pattern (@code{mh-search-folder}).

@kindex F u
@findex mh-undo-folder
@item F u
Undo all pending refiles and deletes (@code{mh-undo-folder}).

@kindex F v
@findex mh-visit-folder
@item F v
Visit folder (@code{mh-visit-folder}).

@kindex o
@findex mh-refile-msg
@item o
Output (refile) message to folder (@code{mh-refile-msg}).

@kindex q
@findex mh-quit
@item q
Quit (@code{mh-quit}).

@kindex t
@findex mh-toggle-showing
@item t
Toggle between MH-Folder and MH-Folder Show modes
(@code{mh-toggle-showing}).

@kindex u
@findex mh-undo
@item u
Undo pending refile or delete (@code{mh-undo}).

@kindex x
@findex mh-execute-commands
@item x
Execute pending refiles and deletes (@code{mh-execute-commands}).
@end table

The following options are used by the commands above.

@vtable @code
@item mh-default-folder-for-message-function XXX
Function to generate a default folder (default: @code{nil}).

@item mh-index-new-messages-folders
Folders searched for @code{mh-unseen-seq} (default: @code{t}).

@item mh-index-ticked-messages-folders
Folders searched for @code{mh-tick-seq} (default: @code{t}).

@item mh-large-folder
The number of messages that indicates a large folder (default: 200).

@item mh-recursive-folders-flag
Collect nested folders (default: @code{nil}).

@item mh-sortm-args
Additional arguments for @command{sortm} (default: @code{nil}).
@end vtable

The following hooks are available.

@vtable @code
@item mh-before-quit-hook
Functions to run before quitting (default: @code{nil}). See also
@code{mh-quit-hook}.

@item mh-refile-msg-hook
Functions to run when refiling message (default: @code{nil}).

@item mh-quit-hook
Functions to run after quitting (default: @code{nil}). See also
@code{mh-before-quit-hook}.
@end vtable

@cindex @command{folder}
@cindex @command{refile}
@cindex MH commands, @command{folder}
@cindex MH commands, @command{refile}

MH-E has analogies for each of the MH @command{folder} and
@command{refile} commands@footnote{See the sections
@uref{@value{MH-BOOK-HOME}/fol.htm#Youfol, Your Current Folder:
folder} and @uref{@value{MH-BOOK-HOME}/fol.htm#Movref, Moving and
Linking Messages: refile} in the MH book.}. To refile a message in
another folder, use the @kbd{o} (@code{mh-refile-msg}) (mnemonic:
``output'') command. You are prompted for the folder name
(@pxref{Folder Selection}). Note that this command can also be used to
create folders. If you specify a folder that does not exist, you will
be prompted to create it.

If you are refiling several messages into the same folder, you can use
the @kbd{!} (@code{mh-refile-or-write-again}) command to repeat the
last refile or write (see the description of @kbd{C-o} in @ref{Reading
Mail}). Or, you can use a range (for example, @kbd{C-u o 1 3 5-7
last:5 frombob @key{RET}}, @pxref{Ranges}).

@cindex expunging refiles and deletes
@cindex undoing refiles and deletes

If you've deleted a message or refiled it, but changed your mind, you
can cancel the action before you've executed it. Use @kbd{u}
(@code{mh-undo}) to undo a refile on or deletion of a single message.
You can also undo refiles and deletes for messages that are found in a
given range (@pxref{Ranges}).

Alternatively, you can use @kbd{F u} (@code{mh-undo-folder}) to undo
all refiles or deletes in the current folder.

If you've marked messages to be deleted or refiled and you want to go
ahead and delete or refile the messages, use @kbd{x}
(@code{mh-execute-commands}). Many MH-E commands that may affect the
numbering of the messages (such as @kbd{F r} or @kbd{F p}) will ask if
you want to process refiles or deletes first and then either run
@kbd{x} for you or undo the pending refiles and deletes, which are
lost.

If you wish to copy a message to another folder, you can use the
@kbd{c} (@code{mh-copy-msg}) command (see the @option{-link} argument
to @command{refile}(1)). Like the @kbd{o} command, this command
prompts you for the name of the target folder and you can specify a
range (@pxref{Ranges}). Note that unlike the @kbd{o} command, the copy
takes place immediately. The original copy remains in the current
folder.

@cindex MH-Folder Show mode
@cindex MH-Folder mode
@cindex junk mail
@cindex modes, MH-Folder
@cindex modes, MH-Folder Show
@cindex spam

The command @kbd{t} (@code{mh-toggle-showing}) switches between
MH-Folder mode and MH-Folder Show mode@footnote{For you Emacs wizards,
this is implemented as an Emacs minor mode.}. MH-Folder mode turns off
the associated show buffer so that you can perform operations on the
messages quickly without reading them. This is an excellent way to
prune out your junk mail or to refile a group of messages to another
folder for later examination.

@cindex MH-Folder mode
@cindex MH-Show mode
@cindex modes, MH-Folder
@cindex modes, MH-Show
@cindex moving between messages
@vindex mh-recenter-summary-flag

When you use @kbd{t} (@code{mh-toggle-showing}) to toggle between show
mode and scan mode, the MH-Show buffer is hidden and the MH-Folder
buffer is left alone. Setting @code{mh-recenter-summary-flag} to a
non-@code{nil} value causes the toggle to display as many scan lines
as possible, with the cursor at the middle. The effect of
@code{mh-recenter-summary-flag} is rather useful, but it can be
annoying on a slow network connection.

When you want to read the messages that you have refiled into folders,
use the @kbd{F v} (@code{mh-visit-folder}) command to visit the
folder. You are prompted for the folder name. The folder buffer will
show just unseen messages if there are any; otherwise, it will show
all the messages in the buffer as long there are fewer than
@code{mh-large-folder} messages. If there are more, then you are
prompted for a range of messages to scan. You can provide a prefix
argument in order to specify a range of messages to show when you
visit the folder (@pxref{Ranges}). In this case, regions are not used
to specify the range. Note that this command can also be used to
create folders. If you specify a folder that does not exist, you will
be prompted to create it.

@cindex @command{procmail}
@cindex @command{rcvstore}
@cindex @samp{unseen} sequence
@cindex MH commands, @command{rcvstore}
@cindex Unix commands, @command{procmail}
@cindex sequence, @samp{unseen}
@cindex unseen messages, viewing

If you use a program such as @command{procmail} to use
@command{rcvstore} to file your incoming mail automatically, you can
display new, unseen, messages using the @kbd{F n}
(@code{mh-index-new-messages}) command. All messages in the
@samp{unseen} sequence from the folders in
@code{mh-index-new-messages-folders} are listed. With a prefix
argument, enter a space-separated list of folders, or nothing to
search all folders.

@cindex @samp{tick} sequence
@cindex sequence, @samp{tick}
@cindex ticked messages, viewing

If you have ticked messages (@pxref{Sequences}), you can display them
using the @kbd{F '} (@code{mh-index-ticked-messages}) command. All
messages in the @samp{tick} sequence from the folders in
@code{mh-index-ticked-messages-folders} are listed. With a prefix
argument, enter a space-separated list of folders, or nothing to
search all folders.

You can display messages in any sequence in all of your folders with
the @kbd{F q} (@code{mh-index-sequenced-messages}) command. All
messages in the sequence you provide from the folders in
@code{mh-index-new-messages-folders} are listed. With a prefix
argument, enter a space-separated list of folders, or nothing to
search all folders.

The variables @code{mh-index-new-messages-folders} and
@code{mh-index-ticked-messages-folders} can be @code{t} which means
that messages in the given sequence from the @file{+inbox} folder are
listed. These variables can be also be @code{nil}, which means that
all of the top-level folders are searched. Otherwise the list of
folders specified as strings are searched. See also
@code{mh-recursive-folders-flag}.

@cindex @samp{*MH-E Folders*}
@cindex buffers, @samp{*MH-E Folders*}

Other commands you can perform on folders include: @kbd{F l}
(@code{mh-list-folders}), to place a listing of all the folders in
your mail directory in a buffer called @samp{*MH-E Folders*}
(@pxref{Miscellaneous}); @kbd{F k} (@code{mh-kill-folder}), to remove
a folder; @kbd{M-x mh-sort-folder}, to sort the messages by date (see
@command{sortm}(1) to see how to sort by other criteria); @kbd{F p}
(@code{mh-pack-folder}), to pack a folder, removing gaps from the
numbering sequence; and @kbd{F r} (@code{mh-rescan-folder}), to rescan
the folder, which is useful to grab all messages in your @samp{+inbox}
after processing your new mail for the first time. If you don't want
to rescan the entire folder, the commands @kbd{F r} or @kbd{F p} will
accept a range argument (@pxref{Ranges}).

By default, operations on folders work only one level at a time. Set
@code{mh-recursive-folders-flag} to non-@code{nil} to operate on all
folders. This mostly means that you'll be able to see all your folders
when you press @key{TAB} when prompted for a folder name.

The function @code{mh-default-folder-for-message-function} is used by
@kbd{o} (@code{mh-refile-msg}) and @kbd{C-c C-f C-f}
(@code{mh-to-fcc}) to generate a default folder name. The generated
folder name should be a string with a @samp{+} before it.

The hook @code{mh-refile-msg-hook} is called after a message is marked
to be refiled.

@cindex @command{sortm}
@cindex @file{.mh_profile}
@cindex @samp{sortm:} MH profile component
@cindex MH commands, @command{sortm}
@cindex MH profile component, @samp{sortm:}
@cindex files, @file{.mh_profile}

The variable @code{mh-sortm-args} holds extra arguments to pass on to
the @command{sortm} command@footnote{See the section
@uref{@value{MH-BOOK-HOME}/sorsor.htm, Sorting Messages: sortm} in the
MH book.}. Note: this variable is only consulted when a prefix
argument is given to @kbd{M-x mh-sort-folder}. It is used to override
any arguments given in a @samp{sortm:} profile component
(@file{~/.mh_profile}).

@findex mh-rmail

When you want to quit using MH-E and go back to editing, you can use
the @kbd{q} (@code{mh-quit}) command. This buries the buffers of the
current MH-E folder and restores the buffers that were present when
you first ran @kbd{M-x mh-rmail}. You can later restore your MH-E
session by selecting the @samp{+inbox} buffer or by running @kbd{M-x
mh-rmail} again.

@cindex quitting

The two variables @code{mh-before-quit-hook} and @code{mh-quit-hook}
are called by @kbd{q} (@code{mh-quit}). The former one is called
before the quit occurs, so you might use it to perform any MH-E
operations; you could perform some query and abort the quit or call
@code{mh-execute-commands}, for example. The latter is not run in an
MH-E context, so you might use it to modify the window setup. For
example, if the window configuration was saved as in the example in
@ref{MH-Folder Options}, you would also want to set
@code{mh-quit-hook} to the following:

@vindex mh-quit-hook, example

@smalllisp
@group
(defun my-mh-quit-hook ()
  "Clear window configuration variables as the MH window is gone."
  (setq my-mh-screen-saved nil)
  (setq my-mh-screen nil)
  (if my-normal-screen
      (set-window-configuration my-normal-screen))
  (setq my-normal-screen nil))

@i{Clean up window setup in mh-quit-hook}

@end group
@end smalllisp

@node Sending Mail, Editing Drafts, Folders, Top
@chapter Sending Mail

@c Customization Group: mh-sending-mail
@c Menu: Message

@cindex sending mail
@findex mh-smail

You can send a mail message in several ways. You can call @kbd{M-x
mh-smail} directly, or from the command line like this:

@cindex starting from command line

@example
$ @kbd{emacs -f mh-smail}
@end example

From within MH-E's MH-Folder mode, other methods of sending mail are
available as well.

@table @kbd
@kindex e
@findex mh-edit-again
@item e
Edit a message to send it again (@code{mh-edit-again}).

@kindex E
@findex mh-extract-rejected-mail
@item E
Edit a message that was bounced by mailer
(@code{mh-extract-rejected-mail}).

@kindex f
@findex mh-forward
@item f
Forward message(s) (@code{mh-forward}).

@kindex m
@findex mh-send
@item m
Compose a message (@code{mh-send}).

@c Also described in Aliases.
@kindex M-TAB
@findex mh-letter-complete
@item M-TAB
Perform completion on header field or word preceding point
(@code{mh-letter-complete}).

@kindex M-d
@findex mh-redistribute
@item M-d
Redistribute a message (@code{mh-redistribute}).

@kindex r
@findex mh-reply
@item r
Reply to a message (@code{mh-reply}).
@end table

@cindex @samp{mh-sending-mail} customization group
@cindex customization group, @samp{mh-sending-mail}

In addition, several options from the @samp{mh-sending-mail}
customization group are useful when sending mail or replying to mail.
They are summarized in the following table.

@vtable @code
@item mh-comp-formfile
Format file for drafts (default: @samp{"components"}).

@item mh-compose-letter-function
Functions to run when starting a new draft (default: @code{nil}).

@item mh-compose-prompt-flag
Non-nil means prompt for header fields when composing a new draft
(default: @code{nil}).

@item mh-forward-subject-format
Format string for forwarded message subject (default: @samp{"%s:
%s"}).

@item mh-new-draft-cleaned-headers
Remove these header fields from re-edited draft (default:
@samp{"^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\| ^Sender:\\|@*
^Delivery-Date:\\| ^Return-Path:"}).

@item mh-redist-full-contents
@code{send} requires entire message (default: @code{nil}).

@item mh-repl-formfile
Format file for replies (default: @samp{"replcomps"}).

@item mh-reply-default-reply-to
Whom reply goes to (default: @code{nil}).
@end vtable

The following hook is available.

@vtable @code
@item mh-letter-mode-hook
Functions to run in MH-Letter mode (default: @code{nil}).
@end vtable

The functions and variables introduced here are explained in more
detail in the following sections.

@menu
* Composing::                   
* Replying::                    
* Forwarding::                  
* Redistributing::              
* Editing Again::               
@end menu

@node Composing, Replying, Sending Mail, Sending Mail
@section Composing

@cindex MH-Folder mode
@cindex MH-Letter mode
@cindex composing mail
@cindex modes, MH-Folder
@cindex modes, MH-Letter
@findex mh-send
@kindex m

From within a MH-Folder buffer, you can simply use the command @kbd{m}
(@code{mh-send}). However you invoke @code{mh-send}, your letter
appears in an Emacs buffer whose mode is MH-Letter (see the Figure in
@ref{Sending Mail Tour} to see what the buffer looks like). MH-Letter
mode allows you to edit your message, to check the validity of the
recipients, to insert attachments and other messages into your
message, and to send the message. We'll go more into depth about
editing a @dfn{draft}@footnote{I highly recommend that you use a
@dfn{draft folder} so that you can edit several drafts in parallel. To
do so, create a folder named @samp{+drafts} for example, and add the
profile component @samp{Draft-Folder: drafts} (see
@code{mh-profile}(5)).} (a message you're composing) in just a moment.

@vindex mh-compose-prompt-flag

If you prefer to be prompted for the recipient and subject fields
before the MH-Letter buffer appears, set @code{mh-compose-prompt-flag}
to @code{t}.

@findex mh-smail
@findex mh-smail-other-window

@code{mh-smail} always creates a two-window layout with the current
buffer on top and the draft on the bottom. If you would rather
preserve the window layout, use @kbd{M-x mh-smail-other-window}.

@cindex @file{.emacs}
@cindex files, @file{.emacs}
@cindex sending mail

You may wish to start off by adding the following useful key bindings
to @file{~/.emacs}:

@lisp
(global-set-key "\C-xm" 'mh-smail)
(global-set-key "\C-x4m" 'mh-smail-other-window)
@end lisp

@cindex @command{comp}
@cindex @command{repl}
@cindex @file{components}
@cindex @file{replcomps}
@cindex MH commands, @command{comp}
@cindex MH commands, @command{repl}
@cindex files, @file{components}
@cindex files, @file{replcomps}
@vindex mh-comp-formfile
@vindex mh-repl-formfile

Since MH-E does not use @command{comp}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/sensen.htm, Sending Some Mail: comp send}
in the MH book.} to create the initial draft, you need to set
@code{mh-comp-formfile} to the name of your components file if it
isn't @file{components}. This is the name of the file that contains
the form for composing messages. If it does not contain an absolute
pathname, MH-E searches for the file first in your MH directory and
then in the system MH library directory (such as
@file{/usr/local/lib/mh}). Replies, on the other hand, are built using
@command{repl}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/reprep.htm, Replying to Messages: repl} in
the MH book.}. You can change the location of the field file from the
default of @file{replcomps} by modifying @code{mh-repl-formfile}.

@cindex @command{repl}
@cindex @file{components}
@cindex MH commands, @command{repl}
@cindex files, @file{components}
@vindex mh-letter-mode-hook

Two hooks are provided to run commands on your freshly created draft.
The first hook, @code{mh-letter-mode-hook}, allows you to do some
processing before editing a letter. For example, you may wish to
modify the header after @command{repl} has done its work, or you may have
a complicated @file{components} file and need to tell MH-E where the
cursor should go. Here's an example of how you would use this
hook---all of the other hooks are set in this fashion as well.

@findex mh-insert-signature, example

@smalllisp
@group
(defvar letter-mode-init-done nil
  "Non-@code{nil} when one-time MH-E settings have made.")

(defun my-mh-letter-mode-hook ()
  "Hook to prepare letter for editing."
  (if (not letter-mode-init-done)    ; @r{only need to bind the keys once}
      (progn
        (local-set-key "\C-ctb" 'add-enriched-text)
        (local-set-key "\C-cti" 'add-enriched-text)
        (local-set-key "\C-ctf" 'add-enriched-text)
        (local-set-key "\C-cts" 'add-enriched-text)
        (local-set-key "\C-ctB" 'add-enriched-text)
        (local-set-key "\C-ctu" 'add-enriched-text)
        (local-set-key "\C-ctc" 'add-enriched-text)
        (setq letter-mode-init-done t)))
  (setq fill-prefix "  ")            ; @r{I find indented text easier to read}
  (save-excursion
    (goto-char (point-max))          ; @r{go to end of message to}
    (mh-insert-signature)))          ;   @r{insert signature}

(add-hook 'mh-letter-mode-hook 'my-mh-letter-mode-hook)

@i{Prepare draft for editing via mh-letter-mode-hook}

@end group
@end smalllisp

The function, @code{add-enriched-text} is defined in the example in
@ref{Adding Attachments}.

@vindex mh-compose-letter-function

The second hook, a function really, is
@code{mh-compose-letter-function}. Like @code{mh-letter-mode-hook}, it
is called just before editing a new message; however, it is the last
function called before you edit your message. The consequence of this
is that you can write a function to write and send the message for
you. This function is passed three arguments: the contents of the
@samp{To:}, @samp{Subject:}, and @samp{Cc:} header fields.

@node Replying, Forwarding, Composing, Sending Mail
@section Replying to Mail

@cindex @command{mhl}
@cindex @file{mhl.reply}
@cindex MH commands, @command{mhl}
@cindex files, @file{mhl.reply}
@cindex replying
@findex mh-reply
@kindex r

To compose a reply to a message, use the @kbd{r} (@code{mh-reply})
command. If you supply a prefix argument (as in @kbd{C-u r}), the
message you are replying to is inserted in your reply after having
first been run through @command{mhl} with the format file
@file{mhl.reply}. See @command{mhl}(1) or the section
@uref{@value{MH-BOOK-HOME}/shomes.htm#Usisho, Using mhl}
in the MH book to see how you can modify the
default @file{mhl.reply} file.

When you reply to a message, you are first prompted with @samp{Reply
to whom?}. You have several choices here.

@smallexample
@group
@b{Response}     @b{Reply Goes To}

@kbd{from}         @r{The person who sent the message.  This is the default,}
             @r{so @key{RET} is sufficient.}

@kbd{to}           @r{Replies to the sender, plus all recipients in the}
             @r{@samp{To:} header field.}

@kbd{all}
@kbd{cc}           @r{Forms a reply to the sender, plus all recipients.}
@end group
@end smallexample

@cindex @command{repl}
@cindex MH commands, @command{repl}

Depending on your answer, @command{repl}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/reprep.htm, Replying to Messages: repl} in
the MH book.} is given a different argument to form your reply.
Specifically, a choice of @kbd{from} or none at all runs @samp{repl
-nocc all}, and a choice of @kbd{to} runs @samp{repl -cc to}. Finally,
either @kbd{cc} or @kbd{all} runs @samp{repl -cc all -nocc me}.

@cindex MH-Letter mode
@cindex modes, MH-Letter

Two windows are then created. One window contains the message to which
you are replying. Your draft, in MH-Letter mode (@pxref{Editing
Drafts}), is in the other window.

If you wish to customize the header or other parts of the reply draft,
please see @command{repl}(1) and @code{mh-format}(5).

@vindex mh-reply-default-reply-to

If you find that most of the time that you specify @kbd{cc} when you
reply to a message, set @code{mh-reply-default-reply-to} to @samp{cc}.
This variable is normally set to @code{nil} so that you are prompted
for the recipient of a reply. It can be set to one of @samp{from},
@samp{to}, or @samp{cc}; you are then no longer prompted for the
recipient(s) of your reply.

@node Forwarding, Redistributing, Replying, Sending Mail
@section Forwarding Mail

@cindex @command{forw}
@cindex MH commands, @command{forw}
@cindex forwarding
@findex mh-forward
@kindex f

To forward a message, use the @kbd{f} (@code{mh-forward}) command. You
are given a draft to edit that looks like it would if you had run the
MH command @command{forw}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/forfor.htm, Forwarding Messages: forw} in
the MH book.}. You are given a chance to add some text (@pxref{Editing
Drafts}).

You can forward several messages by using a range (@pxref{Ranges}).
All of the messages in the range are inserted into your draft.

@vindex mh-forward-subject-format

When forwarding a message, the format of the @samp{Subject:} header
field can be modified by the variable
@code{mh-forward-subject-format}. This variable is a string which
includes two escapes (@samp{%s}). The first @samp{%s} is replaced with
the sender of the original message, and the second one is replaced
with the original @samp{Subject:}. The default value of @samp{"%s:
%s"} takes a message with the header:

@example
@group
To: Bill Wohler <wohler@@stop.mail-abuse.org>
Subject: Re: 49er football
From: Greg DesBrisay <gd@@stop.mail-abuse.org>
@end group
@end example

and creates a subject header field of:

@example
Subject: Greg DesBrisay: Re: 49er football
@end example

@c From Mark: XXX
@c One hopes it includes forwarding multiple messages
@c with and without using MIME attachments....

@node Redistributing, Editing Again, Forwarding, Sending Mail
@section Redistributing Your Mail

@cindex @command{dist}
@cindex MH commands, @command{dist}
@cindex redistributing
@findex mh-redistribute
@kindex M-d

The command @kbd{M-d} (@code{mh-redistribute}) is similar in function
to forwarding mail, but it does not allow you to edit the message, nor
does it add your name to the @samp{From:} header field. It appears to
the recipient as if the message had come from the original sender. For
more information on redistributing messages, see @command{dist}(1).
Also investigate the @kbd{e} (@code{mh-edit-again}) command for
another way to redistribute messages (@pxref{Editing Again}).

@cindex @command{send}
@cindex MH commands, @command{send}
@vindex mh-redist-full-contents

The variable @code{mh-redist-full-contents} must be set to
non-@code{nil} if @command{dist}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/disdis.htm, Distributing Messages with
dist} in the MH book.} requires the whole letter for redistribution,
which is the case if @command{send}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/sensen.htm, Sending Some Mail: comp send}
in the MH book.} is compiled with the @sc{berk}@footnote{To see which
options your copy of MH was compiled with, use @kbd{M-x mh-version}
(@pxref{Miscellaneous}).} option (which many people abhor). If you
find that MH will not allow you to redistribute a message that has
been redistributed before, this variable should be set to @code{nil}.

@node Editing Again,  , Redistributing, Sending Mail
@section Editing Old Drafts and Bounced Messages

@cindex @file{draft}
@cindex files, @file{draft}
@cindex re-editing drafts
@findex mh-edit-again
@kindex e

If you don't complete a draft for one reason or another, and if the
draft buffer is no longer available, you can pick your draft up again
with @kbd{e} (@code{mh-edit-again}). If you don't use a draft
folder, your last @file{draft} file will be used. If you use draft
folders, you'll need to visit the draft folder with @kbd{F v drafts
@key{RET}}, use @kbd{n} to move to the appropriate message, and then
use @kbd{e} to prepare the message for editing.

The @kbd{e} command can also be used to take messages that were sent
to you and to send them to more people.

@cindex Mailer-Daemon
@findex mh-extract-rejected-mail
@kindex E

Don't use @kbd{e} to re-edit a message from a @i{Mailer-Daemon} who
complained that your mail wasn't posted for some reason or another. In
this case, use @kbd{E} (@code{mh-extract-rejected-mail}) to prepare
the message for editing by removing the @i{Mailer-Daemon} envelope and
unneeded header fields. Fix whatever addressing problem you had, and
send the message again with @kbd{C-c C-c}.

@vindex mh-new-draft-cleaned-headers

The header fields specified by @code{mh-new-draft-cleaned-headers} are
removed from an old draft that has been recreated with @kbd{E}
(@code{mh-extract-rejected-mail}) or @kbd{e} (@code{mh-edit-again}).
If when you edit an old draft with these commands you find that there
are header fields that you don't want included, you can append them to
this variable. For example,

@vindex mh-new-draft-cleaned-headers, example

@lisp
(setq mh-new-draft-cleaned-headers
      (concat mh-new-draft-cleaned-headers "\\|^Some-Field:"))
@end lisp

@cindex regular expressions

This appends the regular expression @samp{\\|^Some-Field:} to the
variable 
@ifnothtml
(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The
GNU Emacs Manual}). 
@end ifnothtml
@ifhtml
(see the section
@uref{http://www.gnu.org/software/emacs/manual/html_node/emacs_97.html#SEC97,
Syntax of Regular Expressions} in
@cite{The GNU Emacs Manual}).
@end ifhtml
The @samp{\\|} means @emph{or}, and the @samp{^}
(caret) matches the beginning of the line. This is done to be very
specific about which fields match. The literal @samp{:} is appended
for the same reason.

@node Editing Drafts, Aliases, Sending Mail, Top
@chapter Editing a Draft

@c Customization Group: mh-letter
@c Menu: Letter

@cindex MH-Letter mode
@cindex editing draft
@cindex modes, MH-Letter

When you edit a message that you want to send (called a @dfn{draft} in
this case), the mode used is MH-Letter. This mode provides several
commands in addition to the normal Emacs editing commands to help you
edit your draft.

@table @kbd
@kindex C-c C-c
@findex mh-send-letter
@item C-c C-c
Save draft and send message (@code{mh-send-letter}).

@kindex C-c C-e
@findex mh-edit-mhn
@item C-c C-e
Run through @command{mhn} before sending (@code{mh-edit-mhn}).

@kindex C-c C-f C-b
@findex mh-to-field
@item C-c C-f C-b
Move to @samp{Bcc:} header field (@code{mh-to-field}).

@kindex C-c C-f C-c
@item C-c C-f C-c
Move to @samp{Cc:} header field (@code{mh-to-field}).

@kindex C-c C-f C-d
@item C-c C-f C-d
Move to @samp{Dcc:} header field (@code{mh-to-field}).

@kindex C-c C-f C-f
@findex mh-to-fcc
@item C-c C-f C-f
Move to @samp{Fcc:} header field (@code{mh-to-fcc}).

@kindex C-c C-f C-s
@item C-c C-f C-s
Move to @samp{Subject:} header field (@code{mh-to-field}).

@kindex C-c C-f C-t
@item C-c C-f C-t
Move to @samp{To:} header field (@code{mh-to-field}).

@kindex C-c C-i
@findex mh-insert-letter
@item C-c C-i
Insert a message from a folder (@code{mh-insert-letter}).

@kindex C-c C-m e
@findex mh-mml-secure-message-encrypt-pgpmime
@item C-c C-m e
Encrypt a message (@code{mh-mml-secure-message-encrypt-pgpmime}).

@kindex C-c C-m s
@findex mh-mml-secure-message-sign-pgpmime
@item C-c C-m s
Sign a message (@code{mh-mml-secure-message-sign-pgpmime}).

@kindex C-c C-m C-e
@findex mh-mhn-compose-anon-ftp
@item C-c C-m C-e
Include anonymous ftp reference (@sc{mime})
(@code{mh-mhn-compose-anon-ftp}).

@kindex C-c C-m C-f
@findex mh-mhn-compose-forw
@item C-c C-m C-f
Include forwarded message (@sc{mime}) (@code{mh-mhn-compose-forw}).

@kindex C-c C-m C-i
@findex mh-mhn-compose-insertion
@item C-c C-m C-i
Include binary, image, sound, etc. (@sc{mime})
(@code{mh-mhn-compose-insertion}).

@kindex C-c C-m C-t
@findex mh-mhn-compose-external-compressed-tar
@item C-c C-m C-t
Include anonymous ftp reference to compressed tar file (@sc{mime})
(@code{mh-mhn-compose-external-compressed-tar}).

@kindex C-c C-m C-u
@findex mh-revert-mhn-edit
@item C-c C-m C-u
Undo effects of @command{mhn} (@code{mh-revert-mhn-edit}).

@kindex C-c C-q
@findex mh-fully-kill-draft
@item C-c C-q
Quit editing and delete draft message (@code{mh-fully-kill-draft}).

@kindex C-c C-s
@findex mh-insert-signature
@item C-c C-s
Insert signature in message (@code{mh-insert-signature}).

@kindex C-c C-w
@findex mh-check-whom
@item C-c C-w
Display expanded recipient list (@code{mh-check-whom}).

@kindex C-c C-y
@findex mh-yank-cur-msg
@item C-c C-y
Insert contents of message to which you're replying
(@code{mh-yank-cur-msg}).
@end table

@cindex @samp{mh-letter} customization group
@cindex customization group, @samp{mh-letter}

Several options from the @samp{mh-letter} customization group are used
while editing a draft.

@vtable @code
@item mh-compose-skipped-header-fields
List of header fields to skip over when navigating in draft (default: 
@code{'("From" "Organization" "References" "In-Reply-To"
"X-Face" "Face" "X-Image-URL" "X-Mailer")}.

@item mh-letter-complete-function
Function to call when completing outside of address or folder fields

@item mh-signature-file-name
Source of user's signature (default: @samp{"~/.signature"}).

@item mh-signature-separator-flag
Non-nil means a signature separator should be inserted (default:
@samp{on}).

@item mh-x-face-file
File containing X-Face or Face header field to insert in outgoing mail.
(default: @samp{"~/.face"}).
@end vtable

The following hook is available.

@vtable @code
@item mh-letter-insert-signature-hook
Invoked after signature has been inserted (default: @code{nil}).
@end vtable

The functions and variables introduced here are explained in more
detail in the following sections.

@menu
* Inserting Letter::            
* Inserting Messages::          
* Editing Header::              
* Checking Recipients::         
* Signature::                   
* Picture::                     
* Adding Attachments::          
* Sending PGP::                 
* Sending Message::             
* Killing Draft::               
@end menu

@node Inserting Letter, Inserting Messages, Editing Drafts, Editing Drafts
@section Inserting Letter to Which You're Replying

@cindex inserting messages
@findex mh-yank-cur-msg
@kindex C-c C-y

It is often useful to insert a snippet of text from a letter that
someone mailed to provide some context for your reply. The command
@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by yanking a portion
of text from the message to which you're replying and inserting
@samp{> } before each line.

@cindex Emacs, mark
@cindex Emacs, point
@cindex Emacs, region
@cindex mark
@cindex point
@cindex region

You can control how much text is included when you run this command.
If you run this command right away, without entering the buffer
containing the message to you, this command will yank the entire
message, as is, into your reply@footnote{If you'd rather have the
header cleaned up, use @kbd{C-u r} instead of @kbd{r} when replying
(@pxref{Replying}).}. If you enter the buffer containing the message
sent to you and move the cursor to a certain point and return to your
reply and run @kbd{C-c C-y}, then the text yanked will range from that
point to the end of the message. Finally, the most common action
you'll perform is to enter the message sent to you, move the cursor to
the beginning of a paragraph or phrase, set the @dfn{mark} with
@kbd{C-SPC} or @kbd{C-@@}, and move the cursor to the end of the
paragraph or phrase. The cursor position is called the @dfn{point},
and the space between the mark and point is called the @dfn{region}.
Having done that, @kbd{C-c C-y} will insert the region you selected.

@vindex mh-yank-from-start-of-msg

To control how much of the message to which you are replying is yanked
by @kbd{C-c C-y} (@code{mh-yank-cur-msg}) into your reply, modify
@code{mh-yank-from-start-of-msg}. The default value of @code{t} means
that the entire message is copied. If it is set to @code{'body} (don't
forget the apostrophe), then only the message body is copied. If it is
set to @code{nil}, only the part of the message following point (the
current cursor position in the message's buffer) is copied. In any
case, this variable is ignored if a region is set in the message you
are replying to.

@cindex Emacs, packages, supercite
@vindex mail-citation-hook
@vindex mh-ins-buf-prefix

The string contained in @code{mh-ins-buf-prefix} is inserted before
each line of a message that is inserted into a draft with @kbd{C-c
C-y} (@code{mh-yank-cur-msg}). I suggest that you not modify this
variable. The default value of @samp{"> "} is the default string for
many mailers and news readers: messages are far easier to read if
several included messages have all been indented by the same string.
The variable @code{mail-citation-hook} is @code{nil} by default, which
means that when a message is inserted into the letter, each line is
prefixed by @code{mh-ins-buf-prefix}. Otherwise, it can be set to a
function that modifies an included citation@footnote{@emph{Supercite}
is an example of a full-bodied, full-featured, citation package that
comes standard with Emacs.}.

@findex fill-paragraph
@kindex M-q

You'll often include messages made up of long lines that wrap in an
ugly fashion. You'll find that @kbd{M-q} (@code{fill-paragraph}) works
well even on lines prefixed with @code{mh-ins-buf-prefix}.

@vindex mh-delete-yanked-msg-window-flag

If you like to yank all the text from the message you're replying to
in one go, set @code{mh-delete-yanked-msg-window-flag} to
non-@code{nil} to delete the window containing the original message
after yanking it to make more room on your screen for your reply.

@node Inserting Messages, Editing Header, Inserting Letter, Editing Drafts
@section Inserting Messages

@cindex inserting messages
@findex mh-insert-letter
@kindex C-c C-i

Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}).
This command prompts you for the folder and message number and inserts
the message, indented by @samp{> }. Certain undesirable header fields
are removed before insertion. If given a prefix argument (like
@kbd{C-u C-c C-i}), the header is left intact, the message is not
indented, and @samp{> } is not inserted before each line.

@node Editing Header, Checking Recipients, Inserting Messages, Editing Drafts
@section Editing the Header

@cindex editing header
@findex mh-to-field
@kindex C-c C-f C-t

Because the header is part of the message, you can edit the header
fields as you wish. However, several convenience functions exist to
help you create and edit them. For example, the command @kbd{C-c C-f
C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the
cursor to the @samp{To:} header field, creating it if necessary. The
functions to move to the @samp{Cc:}, @samp{Subject:}, @samp{From:},
@samp{Bcc:}, and @samp{Dcc:} header fields are similar.

@findex mh-to-fcc
@kindex C-c C-f C-f

One function behaves differently from the others, namely, @kbd{C-c C-f
C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}). This function
will prompt you for the folder name in which to file a copy of the
draft.

@findex mh-letter-next-header-field-or-indent
@kindex TAB
@vindex mh-compose-skipped-header-fields

Within the header of the message, the @key{TAB}
(@code{mh-letter-next-header-field-or-indent}) command moves between
fields, but skips those fields listed in
@code{mh-compose-skipped-header-fields}.

@cindex spell check
@findex ispell-complete-word
@findex mh-letter-complete
@kindex M-TAB
@vindex mh-letter-complete-function

If the field contains addresses (for example, @samp{To:} or
@samp{Cc:}) or folders (for example, @samp{Fcc:}) then the @kbd{M-TAB}
(@code{mh-letter-complete}) command will provide alias completion
(@pxref{Aliases}). Elsewhere, @kbd{M-TAB} runs
@code{mh-letter-complete-function} instead, which is
@samp{'ispell-complete-word} by default.

Be sure to leave a row of dashes or a blank line between the header
and the body of the message.

@node Checking Recipients, Signature, Editing Header, Editing Drafts
@section Checking Recipients

@cindex @samp{*MH-E Recipients*}
@cindex @command{whom}
@cindex MH commands, @command{whom}
@cindex buffers, @samp{*MH-E Recipients*}
@cindex checking recipients
@cindex recipients, checking
@findex mh-check-whom
@kindex C-c C-w

The @kbd{C-c C-w} (@code{mh-check-whom}) command expands aliases so
you can check the actual address(es) in the alias. A new buffer named
@samp{*MH-E Recipients*} is created with the output of @command{whom}
(@pxref{Miscellaneous})@footnote{See the section
@uref{@value{MH-BOOK-HOME}/senove.htm#WhaPro, What now? -- and the
whatnow Program} in the MH book.}.

@node Signature, Picture, Checking Recipients, Editing Drafts
@section Inserting Your Signature

@cindex signature
@findex mh-insert-signature
@kindex C-c C-s

You can insert your signature at the current cursor location with the
@kbd{C-c C-s} (@code{mh-insert-signature}) command.

@cindex @file{.signature}
@cindex files, @file{.signature}
@cindex vCard
@vindex mh-signature-file-name

By default, the text of your signature is taken from the file
@file{~/.signature}. You can read from other files by changing the
option @code{mh-signature-file-name}. This file may contain a
@dfn{vCard} in which case an attachment is added with the vCard.

@findex mh-signature-separator-p
@vindex mh-signature-separator
@vindex mh-signature-separator-regexp

The @code{mh-signature-file-name} option may also be a symbol, in
which case that function is called. You may not want a signature
separator to be added for you; instead you may want to insert one
yourself. Variables that you may find useful to do this include
@code{mh-signature-separator} (when inserting a signature separator)
and @code{mh-signature-separator-regexp} (for finding said separator).
The function @code{mh-signature-separator-p}, which reports @code{t}
if the buffer contains a separator, may be useful as well.

@cindex signature separator
@vindex mh-signature-separator-flag

A signature separator (@samp{"-- "}) will be added if the signature
block does not contain one and @code{mh-signature-separator-flag} is
on. It is not recommended that you change this option since various
mail user agents, including MH-E, use the separator to present the
signature differently, and to suppress the signature when replying or
yanking a letter into a draft.

@vindex mh-letter-insert-signature-hook

The value of @code{mh-letter-insert-signature-hook} is a list of
functions to be called, with no arguments, after the signature is
inserted. These functions may access the actual name of the file or
the function used to insert the signature with
@code{mh-signature-file-name}.

The signature can also be inserted using Identities. @xref{Identities}.

@node Picture, Adding Attachments, Signature, Editing Drafts
@section Inserting Your Picture

@cindex @file{.face}
@cindex files, @file{.face}
@vindex mh-x-face-file

You can insert your picture in the header of your mail message so that
recipients see your face in the @samp{From:} header field if their
mail user agent is sophisticated enough. In MH-E, this is done by
placing your image in the file named by the @code{mh-x-face-file}
option which is @file{~/.face} by default.

@cindex @samp{Face:} header field
@cindex @samp{X-Face:} header field
@cindex @samp{X-Image-URL:} header field
@cindex header field, @samp{Face:}
@cindex header field, @samp{X-Face:}
@cindex header field, @samp{X-Image-URL:}

If the file starts with either of the strings @samp{X-Face:},
@samp{Face:} or @samp{X-Image-URL:} then the contents are added to the
message header verbatim. Otherwise it is assumed that the file
contains the value of the @samp{X-Face:} header field.

@cindex @command{compface}
@cindex Unix commands, @command{compface}

The @samp{X-Face:} header field, which is a low-resolution, black and
white image, can be generated using the @command{compface} command,
which can be obtained from
@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z}. The
@cite{Online X-Face Convertor} at @uref{http://www.dairiki.org/xface/}
is a useful resource for quick conversion of images into
@samp{X-Face:} header fields.

Use the @command{make-face} script
(@uref{http://quimby.gnus.org/circus/face/make-face}) to convert a
JPEG image to the higher resolution, color, @samp{Face:} header field.

The URL of any image can be used for the @samp{X-Image-URL:} field and
no processing of the image is required.

To prevent the setting of any of these header fields, either set
@code{mh-x-face-file} to @code{nil}, or simply ensure that the file
defined by this option doesn't exist.

@xref{Viewing}, to see how these header fields are displayed in MH-E.

@node Adding Attachments, Sending PGP, Picture, Editing Drafts
@section Adding Attachments

@cindex MIME
@cindex multimedia mail
@cindex @command{mhn}
@cindex MH commands, @command{mhn}

MH-E has the capability to create multimedia messages. It uses the
@sc{mime} (Multipurpose Internet Mail Extensions)
protocol@footnote{MIME is defined in
@uref{http://www.rfc-editor.org/rfc/rfc2045.txt, RFC 2045}.} The
@sc{mime} protocol allows you to incorporate images, sound, video,
binary files, and even commands that fetch a file with @samp{ftp} when
your recipient reads the message!

If you were to create a multimedia message with plain MH commands, you
would use @command{mhn}. Indeed, the MH-E @sc{mime} commands, prefixed
with @kbd{C-c C-m} and described in detail later in this section,
merely insert @command{mhn} directives which are later expanded by
@command{mhn}. One or more of these directives may be inserted into
your message. Remember: you can always add @command{mhn} directives by
hand@footnote{See the section
@uref{@value{MH-BOOK-HOME}/usimim.htm#SeMIMa, Sending MIME Mail} in
the MH book.}.

@cindex media types
@cindex MIME, media types

The MH-E @sc{mime} commands require a @dfn{media type} for each body
part or attachment. Some fill in the media type for you, whereas
others require you to enter one.

@cindex @command{file}
@cindex @file{/etc/mime.types}
@cindex Unix commands, @command{file}
@cindex files, @file{/etc/mime.types}
@findex mailcap-mime-types

In the cases where MH-E can do so, it will determine the media type
automatically. It uses the @command{file} command to do this. Failing
that, the Emacs function @code{mailcap-mime-types} is used to provide
a list from which to choose. This function usually reads the file
@file{/etc/mime.types}. If all else fails, the list is taken from
@code{mh-mime-content-types}.

@cindex MIME
@cindex multimedia mail
@vindex mh-mime-content-types

The variable @code{mh-mime-content-types}@footnote{The variable
@code{mh-mime-content-types} really should be called
@code{mh-mime-media-types} since it holds a list of media types. It
was originally named that way as the media types appear in the
Content-Type header field.} contains a list of the most frequently
used media types. If your system does fall back to using this variable
and you encounter a new media type that you want to add to the list of
types available for media type completion, you can add it like this:

@vindex mh-mime-content-types, example

@lisp
(setq mh-mime-content-types (append mh-mime-content-types
                                    '(("@var{new/type}"))))
@end lisp

No matter how you add the media type, use the type that seems to match
best the file that you are including. In the case of binaries, the
media type @samp{application/x-executable} can be useful. If you can't
find an appropriate media type, use @samp{text/plain} for text
messages and @samp{application/octet-stream} for everything else.

@cindex content description
@cindex MIME, content description

You are also sometimes asked for a @dfn{content description}. This is
simply an optional brief phrase, in your own words, that describes the
object. If you don't care to enter a content description, just press
return and none will be included; however, a reader may skip over
multimedia fields unless the content description is compelling.

To close this section, I'll describe an Emacs function which can be
used to insert enriched text directives to liven up your plain text
messages with boldface, underlining, and italics.

@smalllisp
@group
(defvar enriched-text-types '(("b" . "bold") ("i" . "italic")
                              ("u" . "underline")
                              ("s" . "smaller") ("B" . "bigger")
                              ("f" . "fixed")
                              ("c" . "center"))
  "Alist of (final-character . directive) choices for add-enriched-text.
Additional types can be found in RFC 1563.")

(defun add-enriched-text (begin end)
  "Add enriched text directives around region.
The directive used comes from the list enriched-text-types and is
specified by the last keystroke of the command.  When called from Lisp,
arguments are BEGIN and END@."
  (interactive "r")
  ;; @r{Set type to the directive indicated by the last keystroke.}
  (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`}))
                          enriched-text-types))))
    (save-restriction              ; @r{restores state from narrow-to-region}
      (narrow-to-region begin end) ; @r{narrow view to region}
      (goto-char (point-min))      ; @r{move to beginning of text}
      (insert "<" type ">")        ; @r{insert beginning directive}
      (goto-char (point-max))      ; @r{move to end of text}
      (insert "</" type ">"))))    ; @r{insert terminating directive}

@i{Emacs function for entering enriched text}

@end group
@end smalllisp

To use the function @code{add-enriched-text}, first add it to
@file{~/.emacs} and create key bindings for it (@pxref{Composing}).

Then, in your plain text message, set the mark with @kbd{C-@@} or
@kbd{C-SPC}, type in the text to be highlighted, and type @kbd{C-c t
b}. This adds @samp{<bold>} where you set the mark and adds
@samp{</bold>} at the location of your cursor, giving you something
like: @samp{You should be <bold>very</bold>}.

Before sending this message, use @kbd{C-c C-e} (@code{mh-edit-mhn}) to
add MIME header fields. Then replace @samp{text/plain} with
@samp{text/enriched} in the @samp{Content-Type:} header field.

You may also be interested in investigating @code{sgml-mode}.

@c From Mark: XXX
@c One hopes you discourage sending text/html by at least
@c refrencing @url{http://www.usethesource.com/articles/03/04/07/122224.shtml}

@subheading Forwarding Multimedia Messages

@findex mh-mhn-compose-forw
@kindex C-c C-m C-f

Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m
C-f} (@code{mh-mhn-compose-forw}). You are prompted for a content
description, the name of the folder in which the messages to forward
are located, and the messages' numbers.

@subheading Including an FTP Reference

@cindex @command{ftp}
@cindex MIME, @command{ftp}
@cindex Unix commands, @command{ftp}
@findex mh-mhn-compose-anon-ftp
@kindex C-c C-m C-e

You can even have your message initiate an @command{ftp} transfer when
the recipient reads the message. To do this, use the @kbd{C-c C-m C-e}
(@code{mh-mhn-compose-anon-ftp}) command. You are prompted for the
remote host and pathname, the media type, and the content
description.

@subheading Including tar Files

@cindex @command{ftp}
@cindex @command{tar}
@cindex MIME, @command{ftp}
@cindex MIME, @command{tar}
@cindex Unix commands, @command{ftp}
@cindex Unix commands, @command{tar}
@findex mh-mhn-compose-external-compressed-tar
@kindex C-c C-m C-t

If the remote file is a compressed tar file, you can use @kbd{C-c C-m
C-t} (@code{mh-mhn-compose-external-compressed-tar}). Then, in
addition to retrieving the file via anonymous @emph{ftp}, the file
will also be uncompressed and untarred. You are prompted for the
remote host and pathname and the content description. The pathname
should contain at least one @samp{/} (slash), because the pathname is
broken up into directory and name components.

@subheading Including Other Multimedia Objects

@cindex MIME, images
@cindex MIME, sound
@cindex MIME, video
@cindex attachments, inserting
@cindex images
@cindex sound
@cindex video
@findex mh-mhn-compose-insertion
@kindex C-c C-m C-i

Binaries, images, sound, and video can be inserted in your message
with the @kbd{C-c C-m C-i} (@code{mh-mhn-compose-insertion}) command.
You are prompted for the filename containing the object, the media
type if it cannot be determined automatically, and a content
description of the object. This command may have been mentioned last,
but it will be the command you use most.

@subheading Readying Multimedia Messages for Sending

When you are finished editing a @sc{mime} message, it might look like this:

@smallexample
@group
@cartouche
   3 t08/24  root               received fax files on Wed Aug 24 11:00:
   4+t08/24  To:wohler          Test<<This is a test message to get the





--:%%  @{+inbox@} 4 msgs (1-4)   (MH-Folder Show)--L4--Bot---------------
To: wohler
cc:
Subject: Test of MIME
--------
#@@application/octet-stream [Nonexistent ftp test file] \
access-type=anon-ftp; site=berzerk.com; name=panacea.tar.gz; \
directory="/pub/"
#audio/basic [Test sound bite] /tmp/noise.au
--:**  @{draft@}   (MH-Letter)--L8--All----------------------------------

@end cartouche
@i{MH-E @sc{mime} draft}
@end group
@end smallexample

In versions 6.0 and later of MH-E, this message can be sent as
described in @ref{Sending Message}. However, if none of the @kbd{C-c
C-m} commands have been used (that is, @emph{all} of the @command{mhn}
directives have been added by hand), or you are using an older version
of MH-E, you must first convert the @command{mhn} directives to
@sc{mime} directives before sending.

@cindex @command{mhn}
@cindex MH commands, @command{mhn}
@findex mh-edit-mhn
@kindex C-c C-e

This is accomplished by the command @kbd{C-c C-e}
(@code{mh-edit-mhn}), which runs @command{mhn} on the
message@footnote{See the section
@uref{@value{MH-BOOK-HOME}/usimim.htm#SeMIMa, Sending MIME Mail} in
the MH book.}. The following screen shows what those commands look
like in full @sc{mime} format. You can see why mail user agents are
usually built to hide these details from the user.

@smallexample
@group
@cartouche
To: wohler
cc:
Subject: Test of MIME
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <1623.777796162.0@@stop.mail-abuse.org>

This is a MIME-encapsulated message

------- =_aaaaaaaaaa0
Content-Type: message/external-body; access-type="anon-ftp";
        site="berzerk.com"; name="panacea.tar.gz"; directory="/pub/"

Content-Type: application/octet-stream
Content-ID: <1623.777796162.1@@stop.mail-abuse.org>
Content-Description: Nonexistent ftp test file

------- =_aaaaaaaaaa0
Content-Type: audio/basic
Content-ID: <1623.777796162.2@@stop.mail-abuse.org>
Content-Description: Test sound bite
Content-Transfer-Encoding: base64

Q3JlYXRpdmUgVm9pY2UgRmlsZRoaAAoBKREBQh8AgwCAgH9/f35+fn59fX5+fn5+f39/f39
f4B/f39/f39/f39/f39/f39+f39+f39/f39/f4B/f39/fn5/f39/f3+Af39/f39/gH9/f39
--:--  @{draft@}   (MH-Letter)--L2--Top----------------------------------

@end cartouche
@i{MH-E @sc{mime} draft ready to send}
@end group
@end smallexample

@findex mh-revert-mhn-edit
@kindex C-c C-m C-u

This action can be undone by running @kbd{C-c C-m C-u}
(@code{mh-revert-mhn-edit}). It does this by reverting to a backup
file. You are prompted to confirm this action, but you can avoid the
confirmation by adding an argument (for example, @kbd{C-u C-c C-m
C-u}).

@vindex mh-mhn-args

If you wish to pass additional arguments to @command{mhn} to affect how
it builds your message, use the variable @code{mh-mhn-args}. For
example, you can build a consistency check into the message by setting
@code{mh-mhn-args} to @samp{-check}. The recipient of your message can
then run @samp{mhn -check} on the message---@command{mhn} will complain
if the message has been corrupted on the way. The @kbd{C-c C-e}
(@code{mh-mhn-edit}) command only consults this variable when given a
prefix argument.

Some mailers add a message such as ``This is a MIME-encapsulated
message'' to the top of the message. Note that @command{mhn} does not add
any messages of this sort. You can always add one yourself after
incorporating the MIME body parts with @kbd{C-c C-e}
(@code{mh-edit-mhn}). Insert your text @emph{after} the blank line
that separates the header from the boundary of the first MIME body
part (usually @samp{------- =_aaaaaaaaaa0}). The previous screen shows
how this might look.

@node Sending PGP, Sending Message, Adding Attachments, Editing Drafts
@section Signing and Encrypting Messages

@cindex signing messages
@cindex encrypting messages
@cindex RFC 3156

MH-E can sign and encrypt messages as defined in
@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. If you
should choose to sign or encrypt your message, use one of the
following commands to do so any time before sending your message.

@findex mh-mml-secure-message-encrypt-pgpmime
@findex mh-mml-secure-message-sign-pgpmime
@kindex C-c C-m e
@kindex C-c C-m s

The command @kbd{C-c C-m s}
(@code{mh-mml-secure-message-sign-pgpmime}) inserts the following
text:

@example
<#secure method=pgpmime mode=sign>
@end example

while the command @kbd{C-c C-m e}
(@code{mh-mml-secure-message-encrypt-pgpmime}) inserts the following
text:

@example
<#secure method=pgpmime mode=signencrypt>
@end example

In either case, a proper multipart message is created for you when you
send the message.

@cindex @samp{pgg} customization group
@cindex PGG
@cindex customization group, @samp{pgg}

The @samp{pgg} customization group may have some settings which may
interest you. 
@iftex
See @cite{The PGG Manual}.
@end iftex
@ifinfo
@xref{Top, , The PGG Manual, pgg, The PGG Manual}.
@end ifinfo
@ifhtml
See
@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html,
@cite{The PGG Manual}}.
@end ifhtml

@cindex @samp{Fcc:} header field
@cindex header field, @samp{Fcc:}
@vindex pgg-encrypt-for-me

In particular, I set the variable @code{pgg-encrypt-for-me} to
@code{t} so that all messages I encrypt are encrypted with my public
key as well. If you keep a copy of all of your outgoing mail with a
@samp{Fcc:} header field, this setting is vital so that you can read
the mail you write!

@node Sending Message, Killing Draft, Sending PGP, Editing Drafts
@section Sending a Message

@cindex @samp{*MH-E Mail Delivery*}
@cindex buffers, @samp{*MH-E Mail Delivery*}
@cindex sending mail
@findex mh-send-letter
@kindex C-c C-c

When you are all through editing a message, you send it with the
@kbd{C-c C-c} (@code{mh-send-letter}) command. You can give an
argument (as in @kbd{C-u C-c C-c}) to monitor the first stage of the
delivery; this output can be found in a buffer called @samp{*MH-E Mail
Delivery*} (@pxref{Miscellaneous}).

@cindex sending mail
@cindex spell check
@vindex mh-before-send-letter-hook

If you want to check your spelling in your message before sending, use
@code{mh-before-send-letter-hook} like this:

@vindex mh-before-send-letter-hook, example

@lisp
(add-hook 'mh-before-send-letter-hook 'ispell-message)
@end lisp

@cindex @command{send}
@cindex MH commands, @command{send}
@vindex mh-send-prog

In case the MH @command{send} program@footnote{See the section
@uref{@value{MH-BOOK-HOME}/sensen.htm, Sending Some Mail: comp send}
in the MH book.} is installed under a different name, use
@code{mh-send-prog} to tell MH-E the name.

@node Killing Draft,  , Sending Message, Editing Drafts
@section Killing the Draft

@cindex killing draft
@findex mh-fully-kill-draft
@kindex C-c C-q

If for some reason you are not happy with the draft, you can kill it
instead with @kbd{C-c C-q} (@code{mh-fully-kill-draft}). Emacs then
kills the draft buffer and deletes the draft message.

@node Aliases, Identities, Editing Drafts, Top
@chapter Aliases

@c Customization Group: mh-alias
@c Menu: 

@cindex aliases

MH aliases are used in the same way in MH-E as they are in MH. Any
alias listed as a recipient will be expanded when the message is sent.
This chapter discusses other things you can do with aliases in MH-E.

@cindex MH-Letter mode
@cindex modes, MH-Letter

The following commands are available in MH-Letter mode with the
exception of @code{mh-alias-reload} which can be called from anywhere.

@table @kbd
@kindex SPC
@findex mh-letter-complete-or-space
@item SPC
Perform completion or insert space (@code{mh-letter-complete-or-space}).

@c Also described in Sending Mail XXX
@kindex M-TAB
@findex mh-letter-complete
@item M-TAB
Perform completion on header field or word preceding point
(@code{mh-letter-complete}).

@item mh-alias-apropos
Show all aliases or addresses that match a regular expression.

@item mh-alias-grab-from-field
Add alias for the sender of the current message

@item mh-alias-reload
Reload MH aliases.
@end table

@cindex @samp{mh-alias} customization group
@cindex customization group, @samp{mh-alias}

The @samp{mh-alias} customization group contains options associated
with aliases.

@vtable @code
@item mh-alias-completion-ignore-case-flag
Non-nil means don't consider case significant in MH alias completion
(default: @samp{on}).

@item mh-alias-expand-aliases-flag
Non-nil means to expand aliases entered in the minibuffer (default:
@samp{off}).

@item mh-alias-flash-on-comma
Specify whether to flash or warn on translation (default: @samp{Flash
but don't warn if no translation}).

@item mh-alias-insert-file
Filename used to store a new MH-E alias (default: @samp{Use Aliasfile
profile component}).

@item mh-alias-insertion-location
Specifies where new aliases are entered in alias files (default:
@samp{Sorted alphabetically}).

@item mh-alias-local-users
If @samp{on}, local users are added to alias completion (default:
@samp{on}).

@item mh-alias-local-users-prefix
String prepended to the real names of users from the password file
(default: @samp{"local."}.

@item mh-alias-passwd-gecos-comma-separator-flag
Non-nil means the gecos field in the password file uses a comma
separator (default: @samp{on}).
@end vtable

The following hook is available.

@vtable @code
@item mh-alias-reloaded-hook
Invoked by @code{mh-alias-reload} after reloading aliases (default:
@code{nil}).
@end vtable

@heading Adding Addresses to Draft

You can use aliases when you are adding recipients to a message.

@findex minibuffer-complete
@kindex TAB

In order to use minibuffer prompting for recipients and the subject
line in the minibuffer, turn the option @code{mh-compose-prompt-flag}
on (@pxref{Composing}), and use the @key{TAB}
(@code{minibuffer-complete}) command to complete aliases (and
optionally local logins) when prompted for the recipients. Turn the
option @code{mh-alias-expand-aliases-flag} on if you want these
aliases to be expanded to their respective addresses in the draft.

Otherwise, you can complete aliases in the header of the draft with
@kbd{M-TAB} (@code{mh-letter-complete}) or @kbd{SPC}
(@code{mh-letter-complete-or-space}).

As MH ignores case in the aliases, so too does MH-E. However, you may
turn the option @code{mh-alias-completion-ignore-case-flag} off to
make case significant which can be used to segregate completion of
your aliases. You might use lowercase for mailing lists and uppercase
for people. For example, I have:

@example
Mark.Baushke: Mark Baushke <mdb@@stop.mail-abuse.org>
mh-e: MH-E Mailing List <mh-e-devel@@stop.mail-abuse.org>
@end example

@c Peter says: XXX
@c I like uppercase for organization prefixes and lowercase for names.
@c
@c peter.galbraith
@c MH-E.bill.wohler
@c
@c I started using this scheme after someone on the list mentioned it.

When this option is turned off, if I type @kbd{M} in the @samp{To:}
field and then @kbd{M-TAB}, then I'll get Mark's address; if I started
with @kbd{m} and then entered @kbd{M-TAB}, then I'd get the list. Note
that this option affects completion only. If I were to enter
@kbd{mark.baushke}, it would still be identified with my
@samp{Mark.Baushke} alias.

To verify that the alias you've entered is valid, the alias will be
displayed in the minibuffer when you type a comma (the
@code{mh-letter-confirm-address} command or
@code{mh-alias-minibuffer-confirm-address} if the option
@code{mh-compose-prompt-flag} is turned on). @xref{Composing}. This
behavior can be controlled with the @code{mh-alias-flash-on-comma}
option which provides three choices: @samp{Flash but don't warn if no
translation}, @samp{Flash and warn if no translation}, and @samp{Don't
flash nor warn if no translation}.

For another way to verify the alias expansion, see @ref{Checking
Recipients}.

@heading Loading Aliases

@cindex @command{ali}
@cindex @file{/etc/nmh/MailAliases}
@cindex @samp{Aliasfile:} MH profile component
@cindex MH commands, @command{ali}
@cindex MH profile component, @samp{Aliasfile:}
@cindex files, @file{/etc/nmh/MailAliases}

MH-E loads aliases for completion and folder name hints from various
places. It uses the MH command @command{ali}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/mh.htm, MH Aliases} in the MH book.} to
read aliases from the files listed in the profile component
@samp{Aliasfile:} as well as system-wide aliases (for example,
@file{/etc/nmh/MailAliases}).

@cindex @file{/etc/passwd}
@cindex files, @file{/etc/passwd}

In addition, aliases are created from @file{/etc/passwd} entries with
a user ID larger than a magical number, typically 200. This can be a
handy tool on a machine where you and co-workers exchange messages.
These aliases have the form @samp{local.@var{first.last}} if a real
name is present in the password file. Otherwise, the alias will have
the form @samp{local.@var{login}}.

The prefix @samp{local.} can be modified via the
@code{mh-alias-local-users-prefix} option. This option can also be set
to @samp{Use login instead of real name}.

For example, consider the following password file entry:

@example
psg:x:1000:1000:Peter S Galbraith,,,:/home/psg:/bin/tcsh
@end example

The following settings of @code{mh-alias-local-users-prefix} option
will produce the associated aliases:

@table @samp
@item "local."
local.peter.galbraith
@item ""
peter.galbraith
@item Use login instead of real name
psg
@end table

In the example above, commas are used to separate different values
within the so-called gecos field. This is a fairly common usage.
However, in the rare case that the gecos field in your password file
is not separated by commas and whose contents may contain commas, you
can turn the option @code{mh-alias-passwd-gecos-comma-separator-flag}
off.

@cindex @samp{ypcat passwd}
@cindex NIS, obtaining local aliases from

If you're on a system with thousands of users you don't know, and the
loading of local aliases slows MH-E down noticeably, then the local
alias feature can be disabled by turning the option
@code{mh-alias-local-users} off. This option also takes a string which
is executed to generate the password file. For example, use
@samp{ypcat passwd} to obtain the NIS password file.

Since aliases are updated frequently, MH-E will reload aliases
automatically whenever an alias lookup occurs if an alias source has
changed. However, you can reload your aliases manually by calling the
@kbd{M-x mh-alias-reload} command directly. The value of
@code{mh-alias-reloaded-hook} is a list of functions to be called,
with no arguments, after the aliases have been loaded.

@heading Adding Aliases

In the past, you have manually added aliases to your alias file(s)
listed in your @samp{Aliasfile:} profile component. MH-E provides
other methods for maintaining your alias file(s).

You can use the @kbd{M-x mh-alias-add-alias} command which will prompt
you for the alias and address that you would like to add. If the alias
exists already, you will have the choice of inserting the new alias
before or after the old alias. In the former case, this alias will be
used when sending mail to this alias. In the latter case, the alias
serves as an additional folder name hint when filing messages
(@pxref{Folder Selection}).

An alias for the sender of the current message is added automatically
by clicking on the @samp{Grab From alias} toolbar button or by running
the @kbd{M-x mh-alias-grab-from-field} command. Aliases for other
recipients of the current message are added by placing your cursor
over the desired recipient and giving the @kbd{M-x
mh-alias-add-address-under-point} command.

@c Mark says: XXX
@c A section on modifying Aliases (as when two or more 'John.Smith' entries
@c are in your address book) may be desirable here... conventions like
@c a locale or job or activity association like soccer.John.Smith to
@c disambiguate entries would likely be part of the discussion.

The options @code{mh-alias-insert-file} and
@code{mh-alias-insertion-location} controls how and where these aliases
are inserted.

The default setting of this option is @samp{Use Aliasfile profile
component}. This option can also hold the name of a file or a list a
file names. If this option is set to a list of file names, or the
@samp{Aliasfile:} profile component contains more than one file name,
MH-E will prompt for one of them.

The option @code{mh-alias-insertion-location} is set to @samp{Sorted
alphabetically} by default. If you organize your alias file in other
ways, then the settings @samp{At the top of file} and @samp{At the
bottom of file} might be more appropriate.

@heading Querying Aliases

If you can't quite remember an alias, you can use @kbd{M-x
mh-alias-apropos} to show all aliases or addresses that match a
regular expression.

@node Identities, Speedbar, Aliases, Top
@chapter Identities

@c Customization Group: mh-identity
@c Menu: Identity

@cindex identities
@cindex multiple personalities

A couple of commands are used to insert identities in MH-Letter mode.

@table @kbd
@kindex C-c C-d
@findex mh-insert-identity
@item C-c C-d
Insert proper fields for given identity (@code{mh-insert-identity}).

@kindex C-c M-d
@findex mh-insert-auto-fields
@item C-c M-d
Insert custom fields if @samp{To:} or @samp{Cc:} match
@code{mh-auto-fields-list} (@code{mh-insert-auto-fields}).
@end table

@cindex @samp{mh-identity} customization group
@cindex customization group, @samp{mh-identity}

The @samp{mh-identity} customization group contains the following
options.

@vtable @code
@item mh-auto-fields-list
List of recipients for which header lines are automatically inserted
(default: @code{nil}).

@item mh-auto-fields-prompt-flag
Non-nil means to prompt before sending if fields inserted (default:
@code{t})

@item mh-identity-default
Default identity to use when @code{mh-letter-mode} is called (default:
@samp{None}).

@item mh-identity-list
List holding MH-E identity (default: @code{nil}).
@end vtable

MH-E supports the concept of multiple personalities or identities.
This means that you can easily have a different header and signature
at home and at work.

Some of the common header fields that people change depending on the
context are the @samp{From:} and @samp{Organization:} fields, as well
as the signature.

This is done by customizing the @code{mh-identity-list} option. In the
customization buffer for this option, click on the @samp{INS} button
and enter a label such as @samp{Home} or @samp{Work}. Then click on
the @samp{INS} button with the label @samp{Add at least one item
below}. The @samp{Value Menu} has the following menu items:

@table @samp
@cindex signature
@vindex mh-signature-file-name
@item Signature
Set your signature with this item. You can specify the contents of
@code{mh-signature-file-name}, a file, or a function.
@xref{Signature}.

@cindex header field, @samp{From:}
@cindex @samp{From:} header field
@item From Field
Specify an alternate @samp{From:} header field. You must include a
valid email address. A standard format is @samp{First Last
<login@@host.domain>}. If you use an initial with a period, then you
must quote your name as in @samp{"First I. Last"
<login@@host.domain>}.

@cindex header field, @samp{Organization:}
@cindex @samp{Organization:} header field
@item Organization Field
People usually list the name of the company where they work here.

@item Other Field
Set any arbitrary header field and value here. Unless the header field
is a standard one, precede the name of your field's label with
@samp{X-}, as in @samp{X-Fruit-of-the-Day:}.
@end table

You can select the identities you have added via the menu called
@samp{Identity} in the MH-Letter buffer. You can also use @kbd{C-c
C-d} (@code{mh-insert-identity}). To clear the fields and signature
added by the identity, select the @samp{None} identity.

The @samp{Identity} menu contains two other items to save you from
having to set the identity on every message. The menu item @samp{Set
Default for Session} can be used to set the default identity to the
current identity until you exit Emacs. The menu item @samp{Save as
Default} sets the option @code{mh-identity-default} to the current
identity setting. You can also customize the
@code{mh-identity-default} option in the usual fashion.

The option @code{mh-auto-fields-list} can also be used to set the
identity depending on the recipient to provide even more control.

To customize @code{mh-auto-fields-list}, click on the @samp{INS}
button and enter a regular expression for the recipient's address.
Click on the @samp{INS} button with the @samp{Add at least one item
below} label. The @samp{Value Menu} contains the following menu items:

@table @samp
@item Identity
Select an identity from those configured in @code{mh-identity-list}.
All of the information for that identity will be added if the
recipient matches.

@cindex @samp{Fcc:} header field
@cindex header field, @samp{Fcc:}
@item Fcc Field
Insert an @samp{Fcc:} header field with the folder you provide. When
you send the message, MH will put a copy of your message in this
folder.

@cindex @samp{Mail-Followup-To:} header field
@cindex header field, @samp{Mail-Followup-To:}
@item Mail-Followup-To Field
Insert an @samp{Mail-Followup-To:} header field with the recipients
you provide. If the recipient's mail user agent supports this header
field@footnote{@samp{Mail-Followup-To:} is supported by nmh.}, then
their replies will go to the addresses listed. This is useful if their
replies go both to the list and to you and you don't have a mechanism
to suppress duplicates. If you reply to someone not on the list, you
must either remove the @samp{Mail-Followup-To:} field, or ensure the
recipient is also listed there so that he receives replies to your
reply.
@end table

These fields can only be added after the recipient is known. Thus the
fields are added when you run the @kbd{C-c M-d} command or choose the
@samp{Identity -> Insert Auto Fields} menu item but only if the
recipients have been listed. Usually, you'll just send the message and
the fields will be added at that time. You are given a chance to see
these fields and to confirm them before the message is actually sent.
You can dispel with this confirmation by setting the option
@code{mh-auto-fields-prompt-flag} to @code{nil}.

You should avoid using the same header field in
@code{mh-auto-fields-list} and @code{mh-identity-list} definitions
that may apply to the same message as the result is undefined.

@node Speedbar, Menubar, Identities, Top
@chapter The Speedbar

@c Customization Group: mh-speed
@c So, where are the options? XXX
@c Menu: 

@cindex folder navigation
@cindex speedbar

You can also use the speedbar (when running under X) to view your
folders. To bring up the speedbar, run @kbd{M-x speedbar @key{RET}}.
You will see a new frame appear with all of your MH folders. Folders
with unseen messages appear in boldface. Click on a folder name with
the middle mouse button to visit that folder in a similar fashion to
the @kbd{F v} (@code{mh-visit-folder}) command (@pxref{Folders}).
Click on the @samp{+} icon to expand and view the sub-folders of that
folder.

The speedbar can be manipulated with the keyboard as well. Use the
Emacs navigational keys (like the arrow keys, or @kbd{C-n}) to move
the cursor over the desired folder and then use the shortcuts for the
menu items listed in the table below. Clicking on the right mouse
button will bring up a context menu. The menu items used by MH-E and
their key bindings are:

@table @samp
@findex mh-speed-visit-folder
@findex mh-visit-folder
@item Visit Folder (@kbd{RET})
This runs the command @code{mh-speed-visit-folder} which visits the
selected folder just as if you had used @kbd{F v}
(@code{mh-visit-folder}).

@findex mh-speed-expand-folder
@item Expand Nested Folders (@kbd{+})
This runs the command @code{mh-speed-expand-folder} which expands the
selected folder, exposing the children folders inside it.

@findex mh-speed-contract-folder
@item Contract Nested Folders (@kbd{-})
This runs the command @code{mh-speed-contract-folder} which contracts
or collapses the selected folder, hiding the children folders inside
it.

@findex mh-speed-refresh
@item Refresh Speedbar (@kbd{r})
This runs the command @code{mh-speed-refresh} to regenerate the list
of folders. Run this command if you've added or deleted a folder, or
wanted to update the unseen message count before the next automatic
update.
@end table

@node Menubar, Toolbar, Speedbar, Top
@chapter The Menubar

@c Customization Group:
@c Menu: 

@cindex menu bar

This is a chapter about the menubar. XXX

@node Toolbar, Searching, Menubar, Top
@chapter The Toolbar

@c Customization Group: mh-toolbar
@c Menu: 

@cindex tool bar

This is a chapter about the toolbar. XXX

@node Searching, Limits, Toolbar, Top
@chapter Searching Through Messages

@c Customization Group: mh-index
@c Menu: Pick (mh-do-pick-search)

@cindex searching

Several commands are used to compose the search criteria and to start
searching.

@table @kbd
@kindex C-c C-c
@findex mh-do-pick-search
@item C-c C-c
Execute the search (@code{mh-do-pick-search}).

@kindex C-c C-f C-b
@findex mh-to-field
@item C-c C-f C-b
Move to @samp{Bcc:} header field (@code{mh-to-field}).

@kindex C-c C-f C-c
@item C-c C-f C-c
Move to @samp{Cc:} header field (@code{mh-to-field}).

@kindex C-c C-f C-d
@item C-c C-f C-d
Move to @samp{Dcc:} header field (@code{mh-to-field}).

@kindex C-c C-f C-f
@item C-c C-f C-f
Move to @samp{From:} header field (@code{mh-to-field}).

@kindex C-c C-f C-s
@item C-c C-f C-s
Move to @samp{Subject:} header field (@code{mh-to-field}).

@kindex C-c C-f C-t
@item C-c C-f C-t
Move to @samp{To:} header field (@code{mh-to-field}).
@end table

@cindex @samp{mh-index} customization group
@cindex customization group, @samp{mh-index}

There is one option from the @samp{mh-index} customization group used
in searching.

@vtable @code
@item mh-partial-folder-mode-line-annotation
Annotation when displaying part of a folder (default:
@samp{"select"}).
@end vtable

The following hook is available.

@vtable @code
@item mh-pick-mode-hook
Invoked upon entry to @code{mh-pick-mode} (default: @code{nil}).
@end vtable

@findex mh-search-folder
@kindex F s

You can search a folder for messages to or from a particular person or
about a particular subject. In fact, you can also search for messages
containing selected strings in any arbitrary header field or any
string found within the messages. Use the @kbd{F s}
(@code{mh-search-folder}) command. You are first prompted for the name
of the folder to search and then placed in the following buffer in
MH-Pick mode:

@group
@cartouche
@smallexample
From: #
To:
Cc:
Date:
Subject:
--------









--:**  pick-pattern   (MH-Pick)--L1--All-------------------------------

@end smallexample
@end cartouche
@i{Pick window}
@end group

@cindex @command{pick}
@cindex MH commands, @command{pick}

Edit this template by entering your search criteria in an appropriate
header field that is already there, or create a new field yourself. If
the string you're looking for could be anywhere in a message, then
place the string underneath the row of dashes. The @kbd{F s} command
uses the MH command @command{pick} to do the real work, so read
@command{pick}(1) or the section @uref{@value{MH-BOOK-HOME}/finpic.htm,
Finding Messages with pick} in the MH book to find out more about how
to enter the criteria.

There are no semantics associated with the search criteria---they are
simply treated as strings. Case is ignored when all lowercase is used,
and regular expressions (a la @command{ed}) are available. It is all
right to specify several search criteria. What happens then is that a
logical @emph{and} of the various fields is performed. If you prefer a
logical @emph{or} operation, run @kbd{F s} multiple times.

As an example, let's say that we want to find messages from Ginnean
about horseback riding in the Kosciusko National Park (Australia)
during January, 1994. Normally we would start with a broad search and
narrow it down if necessary to produce a manageable amount of data,
but we'll cut to the chase and create a fairly restrictive set of
criteria as follows:

@smallexample
@group
From: ginnean
To:
Cc:
Date: Jan 1994
Subject: horse.*kosciusko
--------
@end group
@end smallexample

As with MH-Letter mode, MH-Pick provides commands like @kbd{C-c C-f
C-t} (@code{mh-to-field}) to help you fill in the blanks.

To perform the search, type @kbd{C-c C-c} (@code{mh-do-pick-search}).
The selected messages are placed in the @samp{search} sequence, which
you can use later in forwarding (@pxref{Forwarding}), printing
(@pxref{Printing}), or narrowing your field of view
(@pxref{Sequences}). Subsequent searches are appended to the
@samp{search} sequence. If, however, you wish to start with a clean
slate, first delete the @samp{search} sequence (@pxref{Sequences}).

@cindex MH-Folder mode
@cindex modes, MH-Folder

If you're searching in a folder that is already displayed in a
MH-Folder buffer, only those messages contained in the buffer are used
for the search. Therefore, if you want to search in all messages,
first kill the folder's buffer with @kbd{C-x k} or scan the entire
folder with @kbd{F r}.

If you find that you do the same thing over and over when editing the
search template, you may wish to bind some shortcuts to keys. This can
be done with the variable @code{mh-pick-mode-hook}, which is called
when @kbd{F s} (@code{mh-search-folder}) is run on a new pattern.

@cindex mode line

The string @code{mh-partial-folder-mode-line-annotation} is used to
annotate the mode line when only a portion of the folder is shown. For
example, after running @kbd{F s} (@code{mh-search-folder}), the
default annotation of @samp{"select"} yields a mode line that looks
like:

@example
--%%-@{+inbox/select@} 2 msgs (2-3)      (MH-Folder)--All-----------------
@end example

An alternative interface to searching is presented in @ref{Limits}.

@node Limits, Sequences, Searching, Top
@chapter Limiting Display

@c Customization Group:
@c Menu: 

@cindex limits
@cindex filters

Another way to organize messages in a folder besides threading
(@pxref{XXX}) or using full-text indexed searches (@pxref{Searching})
is by limiting the folder display to messages that are similar to the
current message.

@table @kbd
@kindex / '
@findex mh-narrow-to-tick
@item / '
Limit to messages in the @samp{tick} sequence
(@code{mh-narrow-to-tick}).

@kindex / ?
@findex mh-prefix-help
@item / ?
Display cheat sheet for the commands of the current prefix in
minibuffer (@code{mh-prefix-help}).

@kindex / c
@findex mh-narrow-to-cc
@item / c
Limit to messages with the same @samp{Cc:} field
(@code{mh-narrow-to-cc}).

@kindex / f		
@findex mh-narrow-to-from
@item / f		
Limit to messages with the same @samp{From:} field
(@code{mh-narrow-to-from}).

@kindex / r		
@findex mh-narrow-to-range
@item / r		
Limit to messages in range (@code{mh-narrow-to-range}).

@kindex / s
@findex mh-narrow-to-subject
@item / s
Limit to messages with the same @samp{Subject:} field
(@code{mh-narrow-to-subject}).

@kindex / t
@findex mh-narrow-to-to
@item / t
Limit to messages with the same @samp{To:} field
(@code{mh-narrow-to-to}).

@kindex / w
@findex mh-widen
@item / w
Restore the previous limit (@code{mh-widen}).
@end table

All of the limiting commands above refine the display in some way.

@cindex @command{pick}
@cindex MH commands, @command{pick}

The commands @kbd{/ c}, @code{/ f}, @code{/ s}, and @code{/ t}
restrict the display to messages matching the content of the
respective field in the current message. However, you can give any of
these a prefix argument to edit the @command{pick} expression used to
narrow the view@footnote{See @command{pick}(1) or the section
@uref{@value{MH-BOOK-HOME}/finpic.htm, Finding Messages with pick} in
the MH book.}.

@cindex @samp{tick} sequence
@cindex sequence, @samp{tick}
@cindex ticked messages, viewing

You can also limit the display to messages in the @samp{tick} sequence
with the @kbd{/ '} (@code{mh-narrow-to-tick}) command.
@xref{Sequences}, for information on putting message into the
@samp{tick} sequence. Use the @kbd{/ r} (@code{mh-narrow-to-range})
command to limit the display to messages in a range (@pxref{Ranges}).

Each limit can be undone in turn with the @kbd{/ w} (@code{mh-widen})
command. Give this command a prefix argument to remove all limits.

@node Sequences, Miscellaneous, Limits, Top
@chapter Using Sequences

@c Customization Group: mh-sequences
@c Menu: Sequence

@cindex sequences

For the whole scoop on MH sequences, refer to
@samp{mh-sequence}(5)@footnote{See the section
@uref{@value{MH-BOOK-HOME}/morseq.htm, More About Sequences} in the MH
book.}. As you've read, several of the MH-E commands can operate on a
sequence, which is a shorthand for a range or group of messages. For
example, you might want to forward several messages to a friend or
colleague. Here's how to manipulate sequences.

@table @kbd
@kindex '
@findex mh-toggle-tick
@item '
Toggle tick mark (@code{mh-toggle-tick}).

@kindex S d
@findex mh-delete-msg-from-seq
@item S d
Remove message from sequence (@code{mh-delete-msg-from-seq}).

@kindex S k
@findex mh-delete-seq
@item S k
Delete sequence (@code{mh-delete-seq}).

@kindex S l
@findex mh-list-sequences
@item S l
List all sequences in folder (@code{mh-list-sequences}).

@kindex S n
@findex mh-narrow-to-seq
@item S n
Restrict display to messages in sequence (@code{mh-narrow-to-seq}).

@kindex S p
@findex mh-put-msg-in-seq
@item S p
Put message in a sequence (@code{mh-put-msg-in-seq}).

@kindex S s
@findex mh-msg-is-in-seq
@item S s
Display sequences that message belongs to (@code{mh-msg-is-in-seq}).

@kindex S w
@findex mh-widen
@item S w
Remove restriction; display all messages (@code{mh-widen}).

@item mh-update-sequences
Push MH-E's state out to MH@.
@end table

@cindex @samp{mh-sequences} customization group
@cindex customization group, @samp{mh-sequences}

The @samp{mh-sequences} customization group contains the options
associated with sequences.

@vtable @code
@item mh-refile-preserves-sequences-flag
Non-nil means that sequences are preserved when messages are refiled
(default @code{t}).

@item mh-tick-seq
The name of the MH sequence for ticked messages (default: @samp{'tick}).

@item mh-update-sequences-after-mh-show-flag
Non-nil means flush MH sequences to disk after message is shown
(default: @code{t}).
@end vtable

@cindex @command{pick}
@cindex MH commands, @command{pick}

To place a message in a sequence, use @kbd{S p}
(@code{mh-put-msg-in-seq}) to do it manually, or use the MH command
@command{pick}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/finpic.htm, Finding Messages with pick} in
the MH book.} or the MH-E version of @command{pick}
(@pxref{Searching}) which create a sequence automatically. Give @kbd{S
p} a range and you can add all the messages in a sequence to another
sequence (for example, @kbd{C-u S p SourceSequence @key{RET}
DestSequence @key{RET}}, @pxref{Ranges}).

@cindex @samp{tick} sequence
@cindex sequence, @samp{tick}
@cindex ticking messages

One specific use of the @kbd{S p} command is @kbd{'}
(@code{mh-toggle-tick}) which adds messages to the @samp{tick}
sequence (which you can customize via the @code{mh-tick-seq} option).
This sequence can be viewed later with the @kbd{F '} command
(@pxref{Folders}).

@cindex MH-Folder mode
@cindex modes, MH-Folder

Once you've placed some messages in a sequence, you may wish to narrow
the field of view to just those messages in the sequence you've
created. To do this, use @kbd{S n} (@code{mh-narrow-to-seq}). You
are prompted for the name of the sequence. What this does is show only
those messages that are in the selected sequence in the MH-Folder
buffer. In addition, it limits further MH-E searches to just those
messages. When you want to widen the view to all your messages again,
use @kbd{S w} (@code{mh-widen}).

@cindex @samp{*MH-E Sequences*}
@cindex buffers, @samp{*MH-E Sequences*}

You can see which sequences in which a message appears with the @kbd{S
s} (@code{mh-msg-is-in-seq}) command. Use a prefix argument to display
the sequences in which another message appears (as in @kbd{C-u 42 S s
@key{RET}}). Or, you can list all sequences in a selected folder
(default is current folder) with @kbd{S l} (@code{mh-list-sequences}).
The list appears in a buffer named @samp{*MH-E Sequences*}
(@pxref{Miscellaneous}).

@cindex @samp{Previous-Sequence:} MH profile component
@cindex @samp{cur} sequence
@cindex MH profile component, @samp{Previous-Sequence:}
@cindex sequence, @samp{Previous-Sequence}
@cindex sequence, @samp{cur}

If a message is in any sequence (except
@samp{Previous-Sequence:}@footnote{See @samp{mh-profile}(5)).} and
@samp{cur}) when it is refiled, then it will still be in those
sequences in the destination folder. If this behavior is not desired,
then turn off the @code{mh-refile-preserves-sequences-flag} option.

If you want to remove a message (or range, @pxref{Ranges}) from a
sequence, use @kbd{S d} (@code{mh-delete-msg-from-seq}). If you want
to delete an entire sequence, use @kbd{S k} (@code{mh-delete-seq}). In
the latter case you are prompted for the sequence to delete. Note that
this deletes only the sequence, not the messages in the sequence. If
you want to delete the messages, use @kbd{C-u d} (@pxref{Reading
Mail}).

@cindex @samp{Unseen-Sequence:} MH profile component
@cindex MH profile component, @samp{Unseen-Sequence:}
@cindex sequence, @samp{Unseen-Sequence}

Three sequences are maintained internally by MH-E and pushed out to MH
when a message is shown. They include the sequence specified by your
@samp{Unseen-Sequence:} profile component, @samp{cur}, and the
sequence listed by the @code{mh-tick-seq} option which is @samp{tick}
by default. If you do not like this behavior, set the option
@code{mh-update-sequences-after-mh-show-flag} to @code{nil}. You can
then update the state manually with the @kbd{x}, @kbd{q}, or @kbd{M-x
mh-update-sequences} commands.

@cindex @command{mark}
@cindex MH commands, @command{mark}

With the exceptions of @kbd{S n} and @kbd{S w}, the underlying MH
command dealing with sequences is @command{mark}@footnote{See the
section @uref{@value{MH-BOOK-HOME}/mmbwm.htm, Make Message Bookmarks
with mark} in the MH book.}.

@node Miscellaneous, Junk, Sequences, Top
@chapter Miscellaneous Commands, Variables, and Buffers

This chapter covers the following command.

@ftable @code
@item mh-version
Display version information about MH-E and the MH mail handling
system.
@end ftable

@cindex @samp{*MH-E Info*}
@cindex MH-E version
@cindex buffers, @samp{*MH-E Info*}
@cindex version

One command worth noting is @kbd{M-x mh-version}. You can compare the
version this command prints to the latest release (@pxref{Getting
MH-E}). The output of @kbd{M-x mh-version}, found in a buffer named
@samp{*MH-E Info*}, should always be included with any bug report you
submit (@pxref{Bug Reports}).

@heading MH-E Buffers

Besides the @code{MH-E Folder}, @code{MH-E Show}, and @code{MH-E
Letter} buffers, MH-E creates several other buffers. They are:

@table @samp
@cindex @samp{*MH-E Folders*}
@cindex buffers, @samp{*MH-E Folders*}
@item *MH-E Folders*
This buffer contains the output of @kbd{F l} (@code{mh-list-folders}).
@xref{Folders}.

@cindex @samp{*MH-E Help*}
@cindex buffers, @samp{*MH-E Help*}
@item *MH-E Help*
This buffer contains the output of @kbd{?} (@code{mh-help}) and
@kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}.

@cindex @samp{*MH-E Info*}
@cindex buffers, @samp{*MH-E Info*}
@item *MH-E Info*
This buffer contains the output of @kbd{M-x mh-version @key{RET}}.

@cindex @samp{*MH-E Log*}
@cindex buffers, @samp{*MH-E Log*}
@item *MH-E Log*
This buffer contains the last 100 lines of the output of the various
MH commands.

@cindex @samp{*MH-E Mail Delivery*}
@cindex buffers, @samp{*MH-E Mail Delivery*}
@item *MH-E Mail Delivery*
This buffer contains the transcript of a mail delivery. @xref{Sending
Message}.

@cindex @samp{*MH-E Recipients*}
@cindex buffers, @samp{*MH-E Recipients*}
@item *MH-E Recipients*
This buffer contains the output of @kbd{C-c C-w}
(@code{mh-check-whom}) and is killed when draft is sent.
@xref{Checking Recipients}.

@cindex @samp{*MH-E Sequences*}
@cindex buffers, @samp{*MH-E Sequences*}
@item *MH-E Sequences*
This buffer contains the output of @kbd{S l}
(@code{mh-list-sequences}). @xref{Sequences}.

@cindex @samp{*mh-temp*}
@cindex buffers, @samp{*mh-temp*}
@item  *mh-temp
This is a scratch, ephemeral, buffer used by MH-E functions. Note that
it is hidden because the first character in the name is a space.
You'll generally not have any need for this buffer.
@end table

@node Junk, Scan Line Formats, Miscellaneous, Top
@chapter Dealing With Junk Mail

@c Customization Group: mh-junk
@c Menu: 

@cindex Marshall Rose
@cindex junk mail
@cindex spam

Marshall Rose once wrote a paper on MH entitled, @cite{How to process
200 messages a day and still get some real work done}. This chapter
could be entitled, @cite{How to process 1000 spams a day and still get
some real work done}.

@cindex blacklisting
@cindex ham
@cindex virii
@cindex whitelisting
@cindex worms

We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for
any unwanted message which includes spam, @dfn{virii}, and
@dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying
a sender as one who sends junk mail is called @dfn{blacklisting}; the
opposite is called @dfn{whitelisting}.

@table @kbd
@kindex J b
@findex mh-junk-blacklist
@item J b
Blacklist range as spam (@code{mh-junk-blacklist}).

@kindex J w
@findex mh-junk-whitelist
@item J w
Whitelist range as ham (@code{mh-junk-whitelist}).

@item @code{mh-spamassassin-identify-spammers}
Identify spammers who are repeat offenders.
@end table

@cindex @samp{mh-junk} customization group
@cindex customization group, @samp{mh-junk}

The following table lists the options from the @samp{mh-junk}
customization group.

@vtable @code
@item @code{mh-junk-disposition}
Disposition of junk mail (default: @code{Delete Spam}).

@item @code{mh-junk-program}
Spam program that MH-E should use (default: @samp{Auto-detect}).
@end vtable

@cindex SpamProbe
@cindex Spamassassin
@cindex bogofilter
@cindex spam filters, SpamProbe
@cindex spam filters, Spamassassin
@cindex spam filters, bogofilter

MH-E depends on @uref{http://www.spamassassin.org/, SpamAssassin},
@uref{http://bogofilter.sourceforge.net/, bogofilter}, or
@uref{http://spamprobe.sourceforge.net/, SpamProbe} to throw the dreck
away. This chapter describes briefly how to configure these programs
to work well with MH-E and how to use MH-E's interface that provides
continuing education for these programs.

The default setting of the @code{mh-junk-program} option is
@samp{Auto-detect} which means that MH-E will automatically choose one
of SpamAssassin, Bogofilter, or SpamProbe in that order. If, for
example, you have both SpamAssassin and Bogofilter installed and you
want to use BogoFilter, then you can set this option to
@samp{Bogofilter}.

The @kbd{J b} (@code{mh-junk-blacklist}) command trains the spam
program in use with the content of the range (@pxref{Ranges}) and then
handles the message(s) as specified by the @code{mh-junk-disposition}
option. By default, this option is set to @samp{Delete Spam} but you
can also specify the name of the folder which is useful for building a
corpus of spam for training purposes.

In contrast, the @kbd{J w} (@code{mh-junk-whitelist}) command
reclassifies a range of messages (@pxref{Ranges}) as ham if it were
incorrectly classified as spam. It then refiles the message into the
@file{+inbox} folder.

The following sections discuss the various counter-spam measures that
MH-E can work with.

@cindex @file{.procmailrc}
@cindex files, @file{.procmailrc}

@heading SpamAssassin

SpamAssassin is one of the more popular spam filtering programs. Get
it from your local distribution or from the
@uref{http://spamassassin.org/, SpamAssassin web site}.

To use SpamAssassin, add the following recipes to @file{~/.procmailrc}:

@cindex @command{spamc}
@cindex @samp{X-Spam-Level:} header field
@cindex @samp{X-Spam-Status:} header field
@cindex header field, @samp{X-Spam-Level:}
@cindex header field, @samp{X-Spam-Status:}

@example
MAILDIR=$HOME/`mhparam Path`

# Fight spam with SpamAssassin.
:0fw
| spamc

# Anything with a spam level of 10 or more is junked immediately.
:0:
* ^X-Spam-Level: ..........
/dev/null

:0:
* ^X-Spam-Status: Yes
spam/.
@end example

If you don't use @command{spamc}, use @samp{spamassassin -P -a}.

Note that one of the recipes above throws away messages with a score
greater than or equal to 10. Here's how you can determine a value that
works best for you. 

First, run @samp{spamassassin -t} on every mail message in your
archive and use Gnumeric to verify that the average plus the standard
deviation of good mail is under 5, the SpamAssassin default for
"spam".

Using Gnumeric, sort the messages by score and view the messages with
the highest score. Determine the score which encompasses all of your
interesting messages and add a couple of points to be conservative.
Add that many dots to the @samp{X-Spam-Level:} header field above to
send messages with that score down the drain.

In the example above, messages with a score of 5-9 are set aside in
the @samp{+spam} folder for later review. The major weakness of
rules-based filters is a plethora of false positives so it is
worthwhile to check.

If SpamAssassin classifies a message incorrectly, or is unsure, you can
use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and
@kbd{J w} (@code{mh-junk-whitelist}).

@cindex @command{sa-learn}
@cindex @file{.spamassassin/user_prefs}
@cindex files, @file{.spamassassin/user_prefs}

The @kbd{J b} (@code{mh-junk-blacklist}) command adds a
@samp{blacklist_from} entry to @file{~/spamassassin/user_prefs},
deletes the message, and sends the message to the Razor, so that
others might not see this spam. If the @command{sa-learn} command is
available, the message is also recategorized as spam.

The @kbd{J w} (@code{mh-junk-whitelist}) command adds a
@samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If
the @command{sa-learn} command is available, the message is also
recategorized as ham.

Over time, you'll observe that the same host or domain occurs
repeatedly in the @samp{blacklist_from} entries, so you might think
that you could avoid future spam by blacklisting all mail from a
particular domain. The utility function
@code{mh-spamassassin-identify-spammers} helps you do precisely that.
This function displays a frequency count of the hosts and domains in
the @samp{blacklist_from} entries from the last blank line in
@file{~/.spamassassin/user_prefs} to the end of the file. This
information can be used so that you can replace multiple
@samp{blacklist_from} entries with a single wildcard entry such as:

@example
blacklist_from *@@*amazingoffersdirect2u.com
@end example

In versions of SpamAssassin (2.50 and on) that support a Bayesian
classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the
@command{sa-learn} program to recategorize the message as spam.
Neither MH-E, nor SpamAssassin, rebuilds the database after adding
words, so you will need to run @samp{sa-learn --rebuild} periodically.
This can be done by adding the following to your crontab:

@example
0 * * * *	sa-learn --rebuild > /dev/null 2>&1
@end example

@heading Bogofilter

Bogofilter is a Bayesian spam filtering program. Get it from your
local distribution or from the @uref{http://bogofilter.sourceforge.net/,
Bogfilter web site}.

Bogofilter is taught by running:

@example
bogofilter -n < good-message
@end example

on every good message, and

@example
bogofilter -s < spam-message
@end example

@cindex full training

on every spam message. This is called a @dfn{full training}; three
other training methods are described in the FAQ that is distributed
with bogofilter. Note that most Bayesian filters need 1000 to 5000 of
each type of message to start doing a good job.

To use Bogofilter, add the following recipes to @file{~/.procmailrc}:

@cindex @samp{X-Bogosity:} header field
@cindex header field, @samp{X-Bogosity:}

@example
MAILDIR=$HOME/`mhparam Path`

# Fight spam with Bogofilter.
:0fw
| bogofilter -3 -e -p

:0:
* ^X-Bogosity: Yes, tests=bogofilter
spam/.

:0:
* ^X-Bogosity: Unsure, tests=bogofilter
spam/unsure/.
@end example

If Bogofilter classifies a message incorrectly, or is unsure, you can
use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J
w} (@code{mh-junk-whitelist}) to update Bogofilter's training.

The @cite{Bogofilter FAQ} suggests that you run the following
occasionally to shrink the database:

@example
bogoutil -d wordlist.db | bogoutil -l wordlist.db.new
mv wordlist.db wordlist.db.prv
mv wordlist.db.new wordlist.db
@end example

The @cite{Bogofilter tuning HOWTO} describes how you can fine-tune
Bogofilter.

@heading SpamProbe

SpamProbe is a Bayesian spam filtering program. Get it from your local
distribution or from the @uref{http://spamprobe.sourceforge.net,
SpamProbe web site}.

To use SpamProbe, add the following recipes to @file{~/.procmailrc}:

@cindex @command{formail}
@cindex @samp{X-SpamProbe:} header field
@cindex header field, @samp{X-SpamProbe:}

@example
MAILDIR=$HOME/`mhparam Path`

# Fight spam with SpamProbe.
:0
SCORE=| spamprobe receive

:0 wf
| formail -I "X-SpamProbe: $SCORE"

:0:
*^X-SpamProbe: SPAM
spam/.
@end example

If SpamProbe classifies a message incorrectly, you can use the MH-E
commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w}
(@code{mh-junk-whitelist}) to update SpamProbe's training.

@heading Other Things You Can Do

There are a couple of things that you can add to @file{~/.procmailrc}
in order to filter out a lot of spam and virii. The first is to
eliminate any message with a Windows executable (which is most likely
a virus). The second is to eliminate mail in character sets that you
can't read.

@cindex @samp{Content-Transfer-Encoding:} header field
@cindex @samp{Content-Type:} header field
@cindex @samp{Subject:} header field
@cindex header field, @samp{Content-Transfer-Encoding:}
@cindex header field, @samp{Content-Type:}
@cindex header field, @samp{Subject:}

@example
MAILDIR=$HOME/`mhparam Path`

#
# Filter messages with win32 executables/virii.
#
# These attachments are base64 and have a TVqQAAMAAAAEAAAA//8AALg
# pattern. The string "this program cannot be run in MS-DOS mode"
# encoded in base64 is 4fug4AtAnNIbg and helps to avoid false
# positives (Roland Smith via Pete from the bogofilter mailing list).
#
:0 B:
* ^Content-Transfer-Encoding:.*base64
* ^TVqQAAMAAAAEAAAA//8AALg
* 4fug4AtAnNIbg
spam/exe/.

#
# Filter mail in unreadable character sets (from the Bogofilter FAQ).
#
UNREADABLE='[^?"]*big5|iso-2022-jp|ISO-2022-KR|euc-kr|gb2312|ks_c_5601-1987'

:0:
* 1^0 $ ^Subject:.*=\?($UNREADABLE)
* 1^0 $ ^Content-Type:.*charset="?($UNREADABLE)
spam/unreadable/.

:0:
* ^Content-Type:.*multipart
* B ?? $ ^Content-Type:.*^?.*charset="?($UNREADABLE)
spam/unreadable/.
@end example

@node Scan Line Formats, Procmail, Junk, Top
@appendix Scan Line Formats

@c Customization Group: mh-scan-line-formats
@c Menu: 

@cindex scan line formats

This appendix discusses how MH-E creates, parses, and manipulates scan
lines. If you have your own MH scan or inc format files, you
@strong{can} teach MH-E how to handle them, but it isn't easy as
you'll see.

@cindex @samp{mh-scan-line-formats} customization group
@cindex customization group, @samp{mh-scan-line-formats}

This table lists the options in the @samp{mh-scan-line-formats}
customization group.

@vtable @code
@item mh-scan-format-file
Specifies the format file to pass to the scan program (default: @code{t}).
Need to document this. XXX

@item mh-scan-prog
Program to scan messages (default: @samp{"scan"}).
@end vtable

@cindex @command{scan}
@cindex MH commands, @command{scan}
@vindex mh-progs

The name of the program that generates a listing of one line per
message is held in @code{mh-scan-prog} (default: @samp{"scan"}).
Unless this variable contains an absolute pathname, it is assumed to
be in the @code{mh-progs} directory. You may link another program to
@command{scan} (see @samp{mh-profile}(5)) to produce a different type
of listing@footnote{See the section
@uref{@value{MH-BOOK-HOME}/faswsprs.htm, Find and Specify with scan
pick Ranges Sequences} in the MH book.}.

@vindex mh-scan-format-nmh
@vindex mh-scan-format-mh

The scan format that MH-E uses is held in the variables
@code{mh-scan-format-nmh} and @code{mh-scan-format-mh} depending on
whether you are using nmh or not. The value of
@code{mh-scan-format-nmh} is:

@smallexample
(concat
 "%4(msg)"
 "%<(cur)+%| %>"
 "%<@{replied@}-"
 "%?(nonnull(comp@{to@}))%<(mymbox@{to@})t%>"
 "%?(nonnull(comp@{cc@}))%<(mymbox@{cc@})c%>"
 "%?(nonnull(comp@{bcc@}))%<(mymbox@{bcc@})b%>"
 "%?(nonnull(comp@{newsgroups@}))n%>"
 "%<(zero) %>"
 "%02(mon@{date@})/%02(mday@{date@})%<@{date@} %|*%>"
 "%<(mymbox@{from@})%<@{to@}To:%14(decode(friendly@{to@}))%>%>"
 "%<(zero)%17(decode(friendly@{from@}))%>  "
 "%(decode@{subject@})%<@{body@}<<%@{body@}%>")
@end smallexample

The setting for @code{mh-scan-format-mh} is similar, except that MH
doesn't have the @code{decode} function.

These strings are passed to the scan program via the @option{-format}
arg. The formats are identical to the defaults except that additional
hints for fontification have been added to the fifth column (remember
that in Emacs, the first column is 0).

The values of the fifth column, in priority order, are: @samp{-} if
the message has been replied to, @samp{t} if an address in the
@samp{To:} field matches one of the mailboxes of the current user,
@samp{c} if the @samp{Cc:} field matches, @samp{b} if the @samp{Bcc:}
field matches, and @samp{n} if a non-empty @samp{Newsgroups:} field is
present.

If you change the format of the scan lines you'll need to tell MH-E
how to parse the new format. As you see, quite a lot of variables are
involved to do that. Note that unlike most of the user options
described in this manual, these are variables and therefore cannot be
modified via the customization buffer. The first variable has to do
with pruning out garbage.

@c @dfn{customization buffer}. Define? XXX

@vtable @code
@cindex @command{inc}
@cindex MH commands, @command{inc}
@cindex @command{scan}
@cindex MH commands, @command{scan}
@item mh-scan-valid-regexp
This regular expression describes a valid scan line. This is used to
eliminate error messages that are occasionally produced by
@command{inc}@footnote{See the section
@uref{@value{MH-BOOK-HOME}/reapre.htm, Reading Mail: inc show next
prev} in the MH book.} or @command{scan} (default: @samp{"^ *[0-9]"}).
@end vtable

Next, many variables control how the scan lines are parsed.

@vtable @code
@item mh-scan-body-regexp
This regular expression matches the message body fragment displayed in
scan lines. Note that the default setting of
@samp{mh-folder-font-lock-keywords} expects this expression to contain
at least one parenthesized expression which matches the body text as
in the default of @samp{"\\(<<\\([^\n]+\\)?\\)"}.

@item mh-scan-cur-msg-number-regexp
This regular expression matches the current message. Note that the
default setting of @code{mh-folder-font-lock-keywords} expects this
expression to contain at least one parenthesized expression which
matches the message number as in the default of @samp{"^\\(
*[0-9]+\\+\\).*"}. Don't disable this regexp as it's needed by
non-fontifying functions. See also @code{mh-note-cur} in this
appendix.

@item mh-scan-date-regexp
This regular expression matches a valid date. Note that the default
setting of @code{mh-folder-font-lock-keywords} expects this expression
to contain only one parenthesized expression which matches the date
field as in the default of @samp{"\\([0-9][0-9]/[0-9][0-9]\\)"}.
See also @code{mh-scan-format-regexp} in this appendix.

@item mh-scan-deleted-msg-regexp
This regular expression matches deleted messages. Note that the
default setting of @code{mh-folder-font-lock-keywords} expects this
expression to contain at least one parenthesized expression which
matches the message number as in the default of @samp{"^\\(
*[0-9]+\\)D"}. See also @code{mh-note-deleted} in this appendix.

@item mh-scan-format-regexp
This regular expression matches the output of scan. Note that the
default setting of @code{mh-folder-font-lock-keywords} expects this
expression to contain at least three parenthesized expressions. The
first should match the fontification hint (see
@code{mh-scan-format-nmh}), the second is found in
@code{mh-scan-date-regexp}, and the third should match the user name
as in the default of @samp{"(concat "\\([bct]\\)" mh-scan-date-regexp
"*\\(..................\\)")"}.

@item mh-scan-good-msg-regexp
This regexp specifies the scan lines that are ``good'' messages. Note
that the default setting of @code{mh-folder-font-lock-keywords}
expects this expression to contain at least one parenthesized
expression which matches the message number as in the default of
@samp{"^\\( *[0-9]+\\)[^D^0-9]"}.

@item mh-scan-msg-format-regexp
This regular expression is used to find the message number width in a
scan format. Note that the message number must be placed in a
parenthesized expression as in the default of
@samp{"%\\([0-9]*\\)(msg)"}.

@item mh-scan-msg-format-string
This is a format string for the width of the message number in a scan
format. Use @samp{0%d} for zero-filled message numbers (default:
@samp{"%d"}).

@item mh-scan-msg-number-regexp
This regular expression is used to extract the message number from a
scan line. Note that the message number must be placed in a
parenthesized expression as in the default of @w{@samp{"^
*\\([0-9]+\\)"}}.

@item mh-scan-msg-overflow-regexp
This regular expression matches scan lines in which the message number
overflowed (default: @samp{"^[?0-9][0-9]"}).

@item mh-scan-msg-search-regexp
This regular expression is a @code{format} string that matches the
scan line for a particular message. Use @samp{%d} to represent the
location of the message number within the expression as in the default
of @samp{"^[^0-9]*%d[^0-9]"}.

@item mh-scan-rcpt-regexp
This regular expression specifies the recipient in messages you sent.
Note that the default setting of @code{mh-folder-font-lock-keywords}
expects this expression to contain two parenthesized expressions. The
first is expected to match the @samp{To:} that the default scan format
file generates. The second is expected to match the recipient's name
as in the default of @samp{"\\(To:\\)\\(..............\\)"}.

@item mh-scan-refiled-msg-regexp
This regular expression matches refiled messages. Note that the
default setting of @code{mh-folder-font-lock-keywords} expects this
expression to contain at least one parenthesized expression which
matches the message number as in the default of @samp{"^\\(
*[0-9]+\\)\\^"}. See also @code{mh-note-refiled} in this appendix.

@item mh-scan-subject-regexp
This regular expression matches the subject. Note that the default
setting of @samp{mh-folder-font-lock-keywords} expects this expression
to contain at least three parenthesized expressions. The first is
expected to match the @samp{Re:} string, if any. The second matches an
optional bracketed number after @samp{Re:}, such as in @samp{Re[2]:}
(and is thus a sub-expression of the first expression) and the third
is expected to match the subject line itself as in the default of
@w{@samp{"^ *[0-9]+........[
]*...................\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"}}.
@end vtable

Finally, there are a slew of variables that control how MH-E annotates
the scan lines.

@vtable @code
@item mh-cmd-note
This is the number of characters to skip over before inserting
notation (default: 4). This variable should be set with the function
@code{mh-set-cmd-note}. The variable may be updated dynamically if
@code{mh-adaptive-cmd-note-flag} is non-nil (@pxref{XXX}) and
@code{mh-scan-format-file} is @code{t}. Note how it relates to the
following regular expressions.

@item mh-note-copied
Copied messages are marked by this character (default: @samp{?C}).

@item mh-note-cur
The current message (in MH, not in MH-E) is marked by this character
(default: @samp{?+}). See also @code{mh-scan-cur-msg-number-regexp} in
this appendix.

@item mh-note-deleted
Deleted messages are marked by this character (default: @samp{?D}).
See also @code{mh-scan-deleted-msg-regexp} in this appendix.

@item mh-note-dist
Messages that have been redistributed are marked by this character
(default: @samp{?R}).

@item mh-note-forw
Messages that have been forwarded are marked by this character
(default: @samp{?F}).

@item mh-note-printed
Messages that have been printed are marked by this character (default:
@samp{?P}).

@item mh-note-refiled
Refiled messages are marked by this character (default: @samp{?^}).
See also @code{mh-scan-refiled-msg-regexp} in this appendix.

@item mh-note-repl
Messages that have been replied to are marked by this character
(default: @samp{?-}).

@c If we no longer notate the search sequence, update the following
@c description XXX.

@item mh-note-seq
Messages in a user-defined sequence (as well as messages in the search
sequence) are marked by this character (default: @samp{?%}).
@end vtable

@c Provide a really twisted example. This will also ensure that I've
@c documented everything that needs to be documented. XXX

@node Procmail, Odds and Ends, Scan Line Formats, Top
@appendix Reading Mailing Lists Effectively

@cindex @command{procmail}
@cindex @command{slocal}
@cindex Gnus
@cindex MH commands, @command{slocal}
@cindex Unix commands, @command{procmail}
@cindex mailing lists, reading

This appendix explains how to use @uref{http://www.procmail.org/,
procmail} to file mail from mailing lists into folders which can then
be read easily with MH-E@footnote{The MH equivalent, @command{slocal},
can be used as well, but procmail is more flexible and more packages
exist for procmail than for slocal.}. Some mailing lists have such
high traffic that Gnus must be used and I discuss how to use Gnus
side-by-side with MH-E.

@cindex @file{.procmailrc}
@cindex files, @file{.procmailrc}

First, I'll describe how to put mail from your mailing lists directly
into an MH folder using @command{procmail}. First, add the following
to @file{~/.procmailrc}. While the logging variables aren't strictly
necessary, they are extremely useful.

@smallexample
[1]  # Update PATH so procmail can find myrcvstore, rcvstore and mhparam.
[2]  PATH=$PATH:/usr/lib/mh:/usr/bin/mh:$HOME/bin
[3]
[4]  # Point LOGFILE at the actual log file.
[5]  LOGFILE=$HOME/.procmail.log
[6]
[7]  # This setting provides just the right amount of information.
[8]  LOGABSTRACT=all
[9]
[10] # Uncomment the following line to see how your patterns match.
[11] #VERBOSE=yes
[12]
[13] # Place mail sent to any MH-E mailing list in +mh-e.
[14] :0 w: mh-e$LOCKEXT
[15] * ^TO.*mh-e-.*@.*sourceforge.net
[16] | myrcvstore -create +mh-e
@end smallexample

@cindex @command{rcvstore}
@cindex MH commands, @command{rcvstore}

Line 14 creates a lock file in your mail directory based upon the name
of the folder. This is done because @command{rcvstore} does not
perform locking. While this lock file will prevent @command{procmail}
from writing to a folder concurrently, there is a slight chance that
you might lose a message if you're performing operations on a folder
at the same time @command{rcvstore} is placing a message there. You
have been warned. Now that that disclaimer is out of the way, note
that I've been using this set-up for over a decade and haven't lost
anything to my knowledge@footnote{See
@uref{https://savannah.nongnu.org/bugs/?func=detailbug&bug_id=4361&group_id=2166,
Savannah issue #4361} to see if @command{rcvstore} locking is still an
issue.}.

@cindex @samp{Unseen-Sequence:} MH profile component
@cindex MH profile component, @samp{Unseen-Sequence:}

Line 16 uses the following script, @code{myrcvstore}, to massage the
message as described in the comment and file the message in the given
folder@footnote{The @samp{-create} argument wasn't always the default
to @command{rcvstore}.}.

@smallexample
#! /bin/sh

# Accepts a message on standard input and passes it through rcvstore
# after first passing it through any filters. All arguments are passed
# on to rcvstore.

# Force the "From user date" to become part of header. One reason this
# is done is because the presence of the From field confuses dist so
# that dist adds a new header, rather than using the existing header.
# Note that this should not be done for any message that goes into a
# Gnus incoming file (Gnus will thrown an error) nor should it be
# applied to any message that goes to the system mailbox because the
# entire mailbox will be incorporated as a single message.
formail -c -z -R 'From ' X-Envelope-From: |
rcvstore $@
@end smallexample

If your version of @command{rcvstore} doesn't add messages to the
@samp{unseen} sequence by default, add the following line to your MH
profile:

@example
Unseen-Sequence: unseen
@end example

Now view your new messages with the speedbar (@pxref{Speedbar}) or with
@kbd{F n} (@code{mh-index-new-messages}). @xref{Folders}.

If you're on a mailing list that is so voluminous that it is
impossible to read every message, it usually better to read the
mailing list like a newsgroup in a news reader. Emacs has a built-in
newsreader called Gnus. The remainder of this appendix talks about how
to use Gnus with an MH message store. The version of Gnus that was
used to prepare this manual was 5.10. Versions 5.8 through 5.10 should
work but versions prior to 5.8 use different options.

This table contains a list of Gnus options that you will have to
modify. Note that for them to become accessible, you'll have to load
@file{nnml.el} first. This can be done with @kbd{M-x load-library
@key{RET} nnml @key{RET}}.

@vtable @code
@item gnus-secondary-select-methods
Select the @samp{nnml} value. This select method uses directories for
folders and individual files for messages, just like MH. You do not
have to set an address.

@item mail-sources
Select the @samp{Several files in a directory} value, check the
@samp{Path} box and enter @file{~/Mail} to tell Gnus where to find
your mail.

@item message-mail-user-agent
In order to send mail within Gnus using MH-E, set this option to
@samp{Emacs interface to MH}.

@item nnmail-keep-last-article
Since Gnus keeps track of which messages you have read, it would be
bad if Gnus expired the last message, for example, message 100, and
@command{rcvstore} gave the next new message number 1. Gnus would then
ignore it since it thinks that you've read messages 1-100. Setting
this option to @code{t} ensures that the last message is never
removed thereby eliminating this problem.
@end vtable

Next add the following to @file{~/.procmailrc}. If you don't subscribe
to the gnucash mailing list, substitute one to which you are
subscribed.

@example
MAILDIR=$HOME/`mhparam Path`
# Place mail sent to the gnucash mailing list in gnucash.spool, where
# Gnus will pick it up.
:0:
* ^TO.*gnucash.*@.*gnucash.org
gnucash.spool
@end example

Wait for some messages to appear in @file{gnucash.spool} and run Gnus
with @kbd{M-x gnus @key{RET}}. To view the folder created in the
example above, you would tell Gnus about it the first time only with
@kbd{G m gnucash @key{RET} nnml @key{RET}}. In MH-E, this folder is
known as @samp{+gnucash}.

@node Odds and Ends, History, Procmail, Top
@appendix Odds and Ends

This appendix covers a few topics that don't fit elsewhere. Here I
tell you how to report bugs and how to get on the MH-E mailing lists.
I also point out some additional sources of information.

@menu
* Bug Reports::                 
* Mailing Lists::               
* MH FAQ and Support::          
* Getting MH-E::                
* Contrib::                     
@end menu

@node Bug Reports, Mailing Lists, Odds and Ends, Odds and Ends
@appendixsec Bug Reports

@cindex SourceForge
@cindex bugs

Bug reports should be filed at
@uref{https://sourceforge.net/bugs/?group_id=13357, SourceForge}. You
need to be a SourceForge user to submit bug reports, but this is easy
enough to do that it shouldn't be a restriction for you. Please
include the output of @kbd{M-x mh-version} (@pxref{Miscellaneous}) in
any bug report you send.

@node Mailing Lists, MH FAQ and Support, Bug Reports, Odds and Ends
@appendixsec MH-E Mailing Lists

@cindex SourceForge
@cindex mailing lists

There are several mailing lists for MH-E. They are @i{mh-e-users at
lists.sourceforge.net}, @i{mh-e-announce at lists.sourceforge.net},
and @i{mh-e-devel at lists.sourceforge.net}. You can subscribe or view
the archives at @uref{https://sourceforge.net/mail/?group_id=13357,
SourceForge}. Do not report bugs on these lists; please submit them
via SourceForge (@pxref{Bug Reports}).

@node MH FAQ and Support, Getting MH-E, Mailing Lists, Odds and Ends
@appendixsec MH FAQ and Support

@cindex FAQ
@cindex MH FAQ

A FAQ appears monthly in the newsgroup @samp{comp.mail.mh}. While very
little is there that deals with MH-E specifically, there is an
incredible wealth of material about MH itself which you will find
useful. The subject of the FAQ is @cite{MH Frequently Asked Questions
(FAQ) with Answers}. The FAQ is available at
@uref{http://www.faqs.org/faqs/mail/mh-faq/part1/preamble.html,
faqs.org}.

@cindex support

You can find FAQs on MH-E at the
@uref{https://sourceforge.net/support/?group_id=13357, Support
Requests} page on SourceForge. If you don't find the answer to your
question, file a support request and your question will become a new
FAQ!

@node Getting MH-E, Contrib, MH FAQ and Support, Odds and Ends
@appendixsec Getting MH-E

@cindex MH-E, obtaining
@cindex getting MH-E
@cindex obtaining MH-E

Because MH-E is undergoing a phase of sustained growth, the version of
MH-E in your Emacs is likely to be out of date although it is most
likely to be more up to date than the copy that comes with the MH
distribution in @file{miscellany/mh-e}.

@cindex change log
@cindex release notes

@c intentionally wordy to avoid overfull hbox
New MH-E releases are always available for downloading at
@uref{https://sourceforge.net/project/showfiles.php?group_id=13357,
SourceForge} before they appear in an Emacs release. You can read the
release notes on that page to determine if the given release of MH-E
is already installed in your version of Emacs. You can also read the
change log to see if you are interested in what the given release of
MH-E has to offer (although we have no doubt that you will be
extremely interested in all new releases).

@cindex @samp{MH-E-NEWS}
@cindex @samp{README}
@cindex files, @samp{MH-E-NEWS}
@cindex files, @samp{README}
@cindex news

After you download and extract the MH-E tarball, read the
@file{README} file and @file{MH-E-NEWS}. These correspond to the
release notes and change log mentioned above. The file @file{README}
contains instructions on installing MH-E. If you're already running
Emacs, please quit that session and start again to load in the new
MH-E. Check that you're running the new version with the command
@kbd{M-x mh-version}.

@node Contrib,  , Getting MH-E, Odds and Ends
@appendixsec Contributed Software

This is an appendix about the contributed software. XXX

@node History, Copying, Odds and Ends, Top
@appendix History of MH-E

@cindex Bill Wohler
@cindex Brian Reid
@cindex Gildea, Stephen
@cindex Jim Larus
@cindex Larus, Jim
@cindex Reid, Brian
@cindex SourceForge
@cindex Stephen Gildea
@cindex Wohler, Bill
@cindex history of MH-E

MH-E was originally written by Brian Reid in 1983 and has changed
hands several times since then. Jim Larus wanted to do something
similar for GNU Emacs, and ended up completely rewriting it that same
year. In 1989, Stephen Gildea picked it up and added many
improvements. Bill Wohler then took over in 2000 and moved its
development to @uref{http://sourceforge.net/, SourceForge}.

@menu
* From Brian Reid::             
* From Jim Larus::              
* From Stephen Gildea::         
@end menu

@node From Brian Reid, From Jim Larus, History, History
@appendixsec From Brian Reid

@cindex Brian Reid
@cindex Reid, Brian

One day in 1983 I got the flu and had to stay home from work for three
days with nothing to do. I used that time to write MHE@. The
fundamental idea behind MHE was that it was a ``puppeteer'' driving
the MH programs underneath it. MH had a model that the editor was
supposed to run as a subprocess of the mailer, which seemed to me at
the time to be the tail wagging the dog. So I turned it around and
made the editor drive the MH programs. I made sure that the UCI people
(who were maintaining MH at the time) took in my changes and made them
stick.

Today, I still use my own version of MHE because I don't at all like
the way that GNU MH-E works and I've never gotten to be good enough at
hacking Emacs Lisp to make GNU MH-E do what I want. The Gosling-emacs
version of MHE and the GNU Emacs version of MH-E have almost nothing
in common except similar names. They work differently, have different
conceptual models, and have different key bindings@footnote{After
reading this article, I questioned Brian about his version of MHE, and
received some great ideas for improving MH-E such as a dired-like
method of selecting folders; and removing the prompting when sending
mail, filling in the blanks in the draft buffer instead. I passed them
on to Stephen Gildea, the current maintainer, and he was excited about
the ideas as well. Perhaps one day, MH-E will again resemble MHE,
although none of these ideas are manifest in Version 5.0.}.

Brian Reid, June 1994

@node From Jim Larus, From Stephen Gildea, From Brian Reid, History
@appendixsec From Jim Larus

@cindex Jim Larus
@cindex Larus, Jim

Brian Reid, while at CMU or shortly after going to Stanford wrote a
mail reading program called MHE for Gosling Emacs. It had much the
same structure as MH-E (i.e., invoked MH programs), though it was
simpler and the commands were slightly different. Unfortunately, I no
longer have a copy so the differences are lost in the mists of time.

In '82-83, I was working at BBN and wrote a lot of mlisp code in
Gosling Emacs to make it look more like Tennex Emacs. One of the
packages that I picked up and improved was Reid's mail system. In '83,
I went back to Berkeley. About that time, Stallman's first version of
GNU Emacs came out and people started to move to it from Gosling Emacs
(as I recall, the transition took a year or two). I decided to port
Reid's MHE and used the mlisp to Emacs Lisp translator that came with
GNU Emacs. It did a lousy job and the resulting code didn't work, so I
bit the bullet and rewrote the code by hand (it was a lot smaller and
simpler then, so it took only a day or two).

Soon after that, MH-E became part of the standard Emacs distribution
and suggestions kept dribbling in for improvements. MH-E soon reached
sufficient functionality to keep me happy, but I kept on improving it
because I was a graduate student with plenty of time on my hands and
it was more fun than my dissertation. In retrospect, the one thing
that I regret is not writing any documentation, which seriously
limited the use and appeal of the package.

@cindex @command{xmh}, in MH-E history

In '89, I came to Wisconsin as a professor and decided not to work on
MH-E. It was stable, except for minor bugs, and had enough
functionality, so I let it be for a few years. Stephen Gildea of BBN
began to pester me about the bugs, but I ignored them. In 1990, he
went off to the X Consortium, said good bye, and said that he would
now be using @command{xmh}. A few months later, he came back and said
that he couldn't stand @command{xmh} and could I put a few more bug fixes
into MH-E. At that point, I had no interest in fixing MH-E, so I gave
the responsibility of maintenance to him and he has done a fine job
since then.

Jim Larus, June 1994

@node From Stephen Gildea,  , From Jim Larus, History
@appendixsec From Stephen Gildea

@cindex Gildea, Stephen
@cindex Stephen Gildea

In 1987 I went to work for Bolt Beranek and Newman, as Jim had before
me. In my previous job, I had been using RMAIL, but as my folders tend
to run large, I was frustrated with the speed of RMAIL@. However, I
stuck with it because I wanted the GNU Emacs interface. I am very
familiar and comfortable with the Emacs interface (with just a few
modifications of my own) and dislike having to use applications with
embedded editors; they never live up to Emacs.

MH is the mail reader of choice at BBN, so I converted to it. Since I
didn't want to give up using an Emacs interface, I started using MH-E.
As is my wont, I started hacking on it almost immediately. I first
used version 3.4m. One of the first features I added was to treat the
folder buffer as a file-visiting buffer: you could lock it, save it,
and be warned of unsaved changes when killing it. I also worked to
bring its functionality a little closer to RMAIL@. Jim Larus was very
cooperative about merging in my changes, and my efforts first appeared
in version 3.6, distributed with Emacs 18.52 in 1988. Next I decided
MH-E was too slow and optimized it a lot. Version, 3.7, distributed
with Emacs 18.56 in 1990, was noticeably faster.

When I moved to the X Consortium I became the first person there to
not use xmh. (There is now one other engineer there using MH-E.) About
this point I took over maintenance of MH-E from Jim and was finally
able to add some features Jim hadn't accepted, such as the backward
searching undo. My first release was 3.8 (Emacs 18.58) in 1992.

Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0.
Version 4.0 added many new features, including background folder
collection and support for composing @sc{mime} messages. (Reading
@sc{mime} messages remains to be done, alas.) While writing this book,
Bill Wohler gave MH-E its closest examination ever, uncovering bugs
and inconsistencies that required a new major version to fix, and so
version 5 was released.

Stephen Gildea, June 1994

@node Copying, Key Index, History, Top
@appendix GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo

@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The ``Program,'' below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term ``modification.'')  Each licensee is addressed as ``you.''

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

@item
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and ``any
later version,'' you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 20@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
@group
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end smallexample

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

@node Key Index, Command Index, Copying, Top
@unnumbered Key (Character) Index
@printindex ky

@node Command Index, Option Index, Key Index, Top
@unnumbered Command Index
@printindex fn

@node Option Index, Concept Index, Command Index, Top
@unnumbered Option (Variable) Index
@printindex vr

@node Concept Index, XXX, Option Index, Top
@unnumbered Concept Index
@printindex cp

@node XXX,  , Concept Index, Top
@unnumbered XXX

@bye

@c See existing cross-references to the Emacs manual and the Emacs
@c Lisp manual (search for ``GNU Emacs Manual'' and ``GNU
@c Emacs Lisp Reference Manual'' respectively).

@c Style Guide -- move to Developers Guide when done XXX
@c @samp{Aliasfile:} profile component
@c @samp{To:} header field      (note colon in header field name).
@c login                        not username

@c @ftable sorting:

@c As per index (sort of): Punctuation, keyboard characters (such as
@c RET and BS) upper and lowercase mixed (lower comes before
@c uppercase), control characters go with uppercase C, meta characters
@c go with uppercase M.
@c In some cases, the sort isn't strictly ASCII.
@c For example, SPC (mh-page-msg) reads better before BS
@c (mh-previous-page) and . (mh-show) is better before ,
@c (mh-header-display).

@c @vtable sorting
@c Alphabetical, pull hooks into their own table.