Copyright © 1995, 2001, 2002, 2003, 2005, 2006 Free Software Foundation, Inc.
The MH-E manual is free documentation; you can redistribute it and/or modify it under the terms of either:
- the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
- 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 or GNU Free Documentation License for more details.
The GNU General Public License and the GNU Free Documentation License appear as appendices to this document. You may also request copies by writing to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
This manual introduces another interface to the MH mail system that is accessible through the GNU Emacs editor, namely, 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.
The MH-E package is distributed with GNU Emacs1, so you shouldn't have to do anything special to use it. This manual covers MH-E version 8.0.3. To help you decide which version you have, see Getting Started.
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 C-h t
(help-with-tutorial). (To learn about this notation, see
Conventions.) If you want to take the plunge, consult the
GNU Emacs Manual,
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.
This manual is available in both Info and online formats. The Info version is distributed with Emacs and can be accessed with the info command (info mh-e) or within Emacs (C-h i m mh-e <RET>). The online version is available at SourceForge. Another great online resource is the book MH & nmh: Email for Users & Programmers (also known as the MH book).
I hope you enjoy this manual! If you have any comments, or suggestions for this document, please let me know.
Bill Wohler <wohler at newt.com>
8 February 1995
24 February 2006
If you're an experienced Emacs user, you can skip the following conventions and definition of terms and go directly to the next section (see Getting Started).
In general, functions in this text refer to Emacs Lisp functions
that one would call from within Emacs Lisp programs (for example,
(mh-inc-folder)). On the other hand, commands are those
things that are run by the user, such as i or M-x
mh-inc-folder. Programs outside of Emacs are specifically called MH
commands, shell commands, or Unix commands.
The conventions for key names are as follows:
Since some keyboards don't have a <META> key, you can generate
M-x, for example, by pressing <ESC> (Escape),
releasing it, and then pressing the x key.
A prefix argument allows you to pass an argument to any Emacs function. To pass an argument, type C-u before the Emacs command or keystroke. Numeric arguments can be passed as well. For example, to insert five f's, use C-u 5 f. There is a default of four when using 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 C-u f, 16 f's with C-u C-u f, 64 f's with C-u C-u C-u f, and so on. Numeric and valueless negative arguments can also be inserted with the <META> key. Examples include M-5 to specify an argument of 5, or M-- which specifies a negative argument with no particular value.
The prefix C-u or M- is not necessary in MH-E's MH-Folder mode (see Reading Mail Tour). In this mode, simply enter the numerical argument before entering the command.
Emacs uses variables to hold values. These can be changed via calls to the function
setq in ~/.emacs.
Variables in MH-E that are normally modified by the user are called options and are modified through the customize functions (such as M-x customize-option or M-x customize-group). See section Easy Customization in The GNU Emacs Manual. See Options.
You can specify various styles for displaying text using faces. MH-E provides a set of faces that you can use to personalize the look of your MH-E buffers. Use the command M-x customize-face to do this. See section Face Customization in The GNU Emacs Manual.
Commands often offer hooks which enable you to extend or modify
the way a command works.
See section
Hooks in The GNU Emacs Manual
for a description about normal hooks and abnormal hooks.
MH-E uses normal hooks in nearly all cases, so you can assume that we
are talking about normal hooks unless we explicitly mention that a
hook is abnormal. We also follow the conventions described in that
section: the name of the abnormal hooks end in -hooks and all
the rest of the MH-E hooks end in -hook. You can add hooks with
either customize-option or add-hook.
There are several other terms that are used in Emacs that you should know. The point is where the cursor currently is. You can save your current place in the file by setting a mark. This operation is useful in several ways. The mark can be later used when defining a 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 C-@ (or C-<SPC>).
The minibuffer is the bottom line of the Emacs window, where all prompting and multiple-character input is directed. You can use completion to enter values such as folders. Completion means that Emacs fills in text for you when you type <SPC> or <TAB>. A second <SPC> or <TAB> will list all possibilities at that point. See the section Completion in The GNU Emacs Manual. Note that <SPC> cannot be used for completing filenames and folders.
The minibuffer is also where you enter Emacs function names after
typing M-x. For example, in the preface, I mentioned that you
could obtain help with C-h t (help-with-tutorial). What
this means is that you can get a tutorial by typing either C-h t
or M-x help-with-tutorial. In the latter case, you are prompted
for help-with-tutorial in the minibuffer after typing
M-x.
The ~ notation in filenames represents your home directory.
This notation is used by many shells including bash,
tcsh, and csh. It is analogous to the environment
variable $HOME. For example, ~/.emacs can be written
$HOME/.emacs or using the absolute path as in
/home/wohler/.emacs instead.
In case of trouble: Emacs can be interrupted at any time with 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 C-g and you'll be back where you started. If you want to exit Emacs entirely, use C-x C-c.
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 Version 8 which is pretty close to Version 6 and Version 7. It differs from Version 4 and Version 5 and is vastly different from Version 3. See History.
To determine which version of MH-E that you have, enter M-x mh-version <RET>. Hopefully it says that you're running Version 8.0.3 which is the latest version as of this printing.
If your version is much older than this, please consider upgrading. You can have your system administrator upgrade the system-wide version, or you can install your own personal version. It's really quite easy. See Getting MH-E, for instructions for getting and installing MH-E.
If the mh-version command displays No MH variant
detected3, then you need
to install MH or tell MH-E where to find MH.
If you don't have MH on your system already, you must install a variant of MH. The Debian mh-e package does this for you automatically (see Getting MH-E). Most people use nmh, but you may be interested in trying out GNU mailutils, which supports IMAP. Your GNU/Linux distribution probably has packages for both of these.
If you've never run MH before, you need to run install-mh from the shell before you continue. This sets up your personal MH environment4. If you don't, you'll be greeted with the error message: Install MH and run install-mh before running MH-E. This is all you need to know about MH to use MH-E, but the more you know about MH, the more you can leverage its power. See the MH book to learn more about MH.
Your MH environment includes your MH profile which is found in the file ~/.mh_profile. This file contains a number of MH profile components. For example, the Path: MH profile component contains the path to your mail directory, which is ~/Mail by default.
There are several options MH-E uses to interact with your MH
installation. The option mh-variant specifies the variant used
by MH-E (see Options). The default setting of this option is
Auto-detect which means that MH-E will automatically choose the
first of nmh, MH, or GNU mailutils that it finds in the directories
listed in mh-path (which you can customize),
mh-sys-path, and exec-path. If MH-E can't find MH at
all, you may have to customize mh-path and add the directory in
which the command mhparam is located. If, on the other hand,
you have both nmh and mailutils installed (for example) and
mh-variant-in-use was initialized to nmh but you want to use
mailutils, then you can set mh-variant to mailutils.
When mh-variant is changed, MH-E resets mh-progs,
mh-lib, mh-lib-progs, mh-flists-present-flag, and
mh-variant-in-use accordingly.
Prior to version 8, it was often necessary to set some of these variables in ~/.emacs; now it is no longer necessary and can actually cause problems.
In addition to setting variables that point to MH itself, MH-E also sets a handful of variables that point to where you keep your mail. During initialization, the function
mh-find-path sets
mh-user-path from your Path: MH profile component (but
defaults to Mail if one isn't present), mh-draft-folder
from Draft-Folder:, mh-unseen-seq from
Unseen-Sequence:, mh-previous-seq from
Previous-Sequence:, and mh-inbox from Inbox:
(defaults to +inbox). The hook mh-find-path-hook is run
after these variables have been set. This hook can be used the change
the value of these variables if you need to run with different values
between MH and MH-E.
This chapter introduces some of the terms you'll need to know and then takes you on a tour of MH-E5. 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.
Let's start our tour by sending ourselves a message which we can later read and process. Enter M-x mh-smail to invoke the MH-E program to send messages. Your message appears in an Emacs buffer whose mode6 is MH-Letter.
Enter your login name in the To: header field. Press the <TAB> twice to move the cursor past the Cc: field, since no carbon copies are to be sent, and on to the Subject: field. Enter Test or anything else that comes to mind.
Press <TAB> again to move the cursor to the body of the message. Enter some text, using normal Emacs commands. You should now have something like this7:
--:-- *scratch* All L1 (Lisp Interaction)-------------------------
To: wohler
cc:
Subject: Test
X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
--------
This is a test message to get the wheels churning...#
--:** {draft} All L5 (MH-Letter)----------------------------------
Type C-c C-c to send message, C-C ? for help
|
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.
There are several commands specific to MH-Letter mode8, but at this time we'll only use C-c C-c to send your message. Type C-c C-c now. That's all there is to it!
To read the mail you've just sent yourself, enter M-x mh-rmail. This incorporates the new mail and puts the output from inc9 (called scan lines after the MH program scan10 which prints a one-line summary of each message) into a buffer called +inbox whose major mode is MH-Folder.
The 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 F r to pull all your messages into MH-E.
You should see the scan line for your message, and perhaps others. Use n or p to move the cursor to your test message and type <RET> to read your message. You should see something like:
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/select} 4 msgs (1-4) Bot L4 (MH-Folder Show)---------
To: wohler
Subject: Test
X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
Date: Fri, 17 Mar 2006 10:49:11 -0800
From: Bill Wohler <wohler@stop.mail-abuse.org>
This is a test message to get the wheels churning...
--:-- {show-+inbox} 4 All L1 (MH-Show)----------------------------
|
If you typed a long message, you can view subsequent pages with <SPC> and previous pages with <DEL>.
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 r. You are prompted in the minibuffer with 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. You can press <TAB> to see these choices. If you simply press <RET>, you'll reply only to the sender. Press <RET> now.
You'll find yourself in an Emacs buffer similar to that when you were sending the original message, like this:
To:
cc:
Subject: Re: Test
In-reply-to: <31054.1142621351@stop.mail-abuse.org>
References: <31054.1142621351@stop.mail-abuse.org>
Comments: In-reply-to Bill Wohler <wohler@stop.mail-abuse.org>
message dated "Fri, 17 Mar 2006 10:49:11 -0800."
X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
--------
#
--:-- {draft} All L10 (MH-Letter)----------------------------------
To: wohler
Subject: Test
X-Mailer: MH-E 8.0; nmh 1.1; GNU Emacs 22.1
Date: Fri, 17 Mar 2006 10:49:11 -0800
From: Bill Wohler <wohler@stop.mail-abuse.org>
This is a test message to get the wheels churning...
--:-- {show-+inbox} 4 All L1 (MH-Show)----------------------------
Type C-c C-c to send message, C-c ? for help
|
By default, MH will not add you to the address list of your replies,
so if you find that the To: header field is missing, don't
worry. In this case, type C-c C-f C-t to create and go to the
To: field, where you can type your login name again. You can
move around with the arrow keys or with C-p
(previous-line), C-n (next-line), C-b
(backward-char), and C-f (forward-char) and can
delete the previous character with <BS>. When you're finished
editing your message, send it with C-c C-c as before.
You'll often want to save messages that were sent to you in an organized fashion. This is done with 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 o to output (refile in MH parlance) that message to a folder. Enter test at the Destination folder: prompt and type y (or <SPC>) when MH-E asks to create the folder +test. Note that a ^ (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.
Your previous reply is now waiting in the system mailbox. You incorporate this mail into your MH-Folder buffer named +inbox with the i command. Do this now. After the mail is incorporated, use n or p to move the cursor to the new message, and read it with <RET>. Let's delete this message by typing d. Note that a 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 x command.
If you want to send another message you can use m instead of M-x mh-smail. So go ahead, send some mail to your friends!
You can get a quick reminder about these commands by typing ?.
This lists several prefix characters. To list the commands
available via the prefix characters, type the prefix character
followed by a ?, for example, F ?. More complete help is
available with the C-h m (describe-mode) command.
You may now wish to exit emacs entirely. Use C-x C-c to exit emacs. If you exited without running x in the +inbox buffer, Emacs will offer to save it for you. Type y or <SPC> to save +inbox changes, which means to perform any refiles and deletes that you did there.
If you don't want to leave Emacs, you can type q to bury (hide) the MH-E folder or delete it entirely with C-x k. You can then later recall it with C-x b or M-x mh-rmail.
On the other hand, if you no longer want to use MH and MH-E, you can take your mail with you. You can copy all of your mail into a single file, mbox-style, by using the MH command packf. For example, to create a file called msgbox with the messages in your +inbox folder, use packf +inbox. The packf command will append the messages to the file if it already exists, so you can use folders -recurse -fast in a script to copy all of your messages into a single file, or using the -file argument, a file for each folder.
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:
Remember that you can also use MH commands when you're not running MH-E (and when you are!).
This chapter begins the meat of the manual which goes into more detail about every MH-E command and option.
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
C-h m (describe-mode) for a brief summary of commands,
? (mh-help) for an even briefer summary11 (C-c ? in MH-Letter mode), or C-h
i to read this manual via Info. The online help is quite good; try
running C-h C-h. This brings up a list of available help topics,
one of which displays the documentation for a given key (like C-h
k C-n). Another useful help feature is to view the manual section
that describes a given key (such as C-h K i). In addition,
review 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.
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, 12 and you can look at the code itself for examples. Look in the Emacs Lisp directory on your system (such as /usr/local/lib/emacs/lisp/mh-e) and find all the 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 C-h f mh-execute-commands <RET>. If you write your own functions, please do not prefix your symbols (variables and functions) with mh-. This prefix is reserved for the MH-E package. To avoid conflicts with existing MH-E symbols, use a prefix like my- or your initials. (Unless, of course, your initials happen to be mh!)
Many string or integer options are easy to modify using M-x
customize-option. For example, to modify the option that controls
printing, you would run M-x customize-option <RET>
mh-lpr-command-format <RET>. In the buffer that appears, modify
the string to the right of the variable. For example, you may change
the lpr command with nenscript -G -r -2 -i'%s'. Then
use the State combo box and select Save for Future
Sessions. To read more about mh-lpr-command-format, see
Printing.
Options can also hold boolean values. In Emacs Lisp, the boolean
values are nil, which means false, and t, which means
true. The customize-option function makes it easy to change
boolean values; simply click on the toggle button in the customize
buffer to switch between on (t) and off
(nil). For example, try setting mh-bury-show-buffer-flag
to off to keep the MH-Show buffer at the top of the buffer
stack. Use the State combo box and choose Set for Current
Session to see how the option affects the show buffer. Then choose
the 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
non-nil value, because sometimes values other than
on are meaningful. An example of this is the variable
mh-mhl-format-file (see Viewing). Other options, such as
hooks, involve a little more Emacs Lisp programming expertise.
You can browse all of the MH-E options with the customize-group
function. Try entering M-x customize-group <RET> mh
<RET> to view the top-level options as well as buttons for all of
the MH-E customization groups. Another way to view the MH-E
customization group is to use M-x mh-customize <RET>.
Many commands that operate on individual messages, such as
mh-forward or mh-refile-msg take a RANGE
argument. This argument can be used in several ways.
If you provide the prefix argument C-u to these commands, then you will be prompted for the message range. This can be any valid MH range which can include messages, sequences (see Sequences), and the abbreviations (described in the mh(1) man page):
For example, a range that shows all of these things is 1 2 3 5-10 last:5 unseen.
If the option transient-mark-mode is turned on 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.
The mh-range customization group contains a single option which affects how ranges are interpreted.
mh-interpret-number-as-range-flag
Since one of the most frequent ranges used is last:N, MH-E will
interpret input such as 200 as last:200 if the
mh-interpret-number-as-range-flag option is on (which is the
default). If you need to scan just the message 200, then use the range
200:1 or 200-200.
When you choose a folder in MH-E via a command such as o
(mh-refile-msg), completion is used to enter the folder
(see the section
Completion in The GNU Emacs Manual).
In addition, MH-E has several ways of choosing a suitable default so
that the folder can often be selected with a single <RET> key.
The mh-folder-selection customization group contains some options which are used to help with this.
mh-default-folder-for-message-functionnil).
mh-default-folder-listnil).
mh-default-folder-must-exist-flagmh-default-folder-prefix"").
You can set the option mh-default-folder-for-message-function
to a function that provides a default folder for the message to be
refiled. When this function is called, the current buffer contains the
message being refiled and point is at the start of the message. This
function should return the default folder as a string with a leading
+ sign. It can also return 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:
mh-default-folder-list is used. Each element in this list
contains a 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.
mh-default-folder-prefix corresponding to
the address is used. The prefix is used to prevent clutter in your
mail directory. See Aliases.
If the derived folder does not exist, and
mh-default-folder-must-exist-flag is 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.
This chapter talks about getting mail from your system mailbox into your MH +inbox folder. The following command accomplishes that and is found in the Folder menu.
mh-inc-folder).
The following options in the mh-inc customization group are used.
mh-inc-prog"inc").
mh-inc-spool-listnil).
The following hook is available.
mh-inc-folder-hookmh-inc-folder after incorporating mail into a
folder (default: nil).
If at any time you receive new mail, incorporate the new mail into
your +inbox buffer with i (mh-inc-folder). Note
that i will display the +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 as well as the destination folder (for
example, C-u i ~/mbox <RET> +tmp <RET>).
Emacs can notify you when you have new mail by displaying Mail in the mode line. To enable this behavior, and to have a clock in the mode line as well, add the following to ~/.emacs:
(display-time)
The name of the program that incorporates new mail is stored in
mh-inc-prog; it is "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
mh-progs directory (see Getting Started). You may also link
a file to inc that uses a different format (see
mh-profile(5), and sections
Reading Mail: inc show next prev and MH Format Strings in
the MH book). You'll then need to modify several variables
appropriately (see Scan Line Formats).
You can use the mh-inc-spool-list variable to direct MH-E to
retrieve mail from arbitrary spool files other than your system
mailbox, file it in folders other than your +inbox, and assign
key bindings to incorporate this mail.
Suppose you are subscribed to the mh-e-devel mailing list and you use procmail to filter this mail into ~/mail/mh-e with the following recipe in .procmailrc:
PATH=$PATH:/usr/bin/mh
MAILDIR=$HOME/`mhparam Path`
:0:
* ^From mh-e-devel-admin@stop.mail-abuse.org
mh-e
In order to incorporate ~/mail/mh-e into +mh-e with an
I m (mh-inc-spool-mh-e) command, customize this option,
and click on the INS button. Enter a Spool File of
~/mail/mh-e, a Folder of mh-e, and a Key
Binding of m.
You can use xbuffy to automate the incorporation of this mail using the Emacs 22 command emacsclient as follows:
box ~/mail/mh-e
title mh-e
origMode
polltime 10
headertime 0
command emacsclient --eval '(mh-inc-spool-mh-e)'
In XEmacs, the command gnuclient is used in a similar fashion.
You can set the hook mh-inc-folder-hook, which is called after
new mail is incorporated by the i (mh-inc-folder)
command. A good use of this hook is to rescan the whole folder either
after running M-x mh-rmail the first time or when you've changed
the message numbers from outside of MH-E.
(defun my-mh-inc-folder-hook ()
"Hook to rescan folder after incorporating mail."
(if (buffer-modified-p) ; if outstanding refiles and deletes,
(mh-execute-commands)) ; carry them out
(mh-rescan-folder) ; synchronize with +inbox
(mh-show)) ; show the current message
(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook)
Rescan folder after incorporating new mail via mh-inc-folder-hook
The MH-E entry point for reading mail is M-x mh-rmail. This command incorporates your mail and creates a buffer called +inbox in MH-Folder mode. The command M-x mh-rmail shows you only new mail, not mail you have already read13.
There are some commands that need to read mail, such as Mouse-2
over the Mail button that display-time adds to the mode
line. You can configure Emacs to have these commands use MH-E by
setting the option read-mail-command to mh-rmail.
The +inbox buffer contains 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 or by using the Message menu. See scan(1) for a description of the contents of the scan lines, and see the Figure in Reading Mail Tour, for an example.
mh-help).
mh-show).
mh-header-display).
mh-decode-mime-flag
(mh-toggle-mh-decode-mime-flag).
mh-page-msg).
mh-previous-page).
mh-write-msg-to-file).
mh-pipe-msg).
mh-delete-msg-no-motion).
mh-delete-msg).
mh-prefix-help).
mh-page-digest).
mh-page-digest-backwards).
mh-burst-digest).
mh-goto-msg).
mh-delete-subject-or-thread).
mh-prefix-help).
mh-next-button).
mh-prev-button).
mh-mime-save-parts).
mh-display-with-external-viewer).
mh-folder-inline-mime-part).
mh-folder-save-mime-part).
mh-display-buttons-for-inline-parts-flag
(mh-toggle-mime-buttons).
mh-folder-toggle-mime-part).
mh-modify).
mh-first-msg).
mh-last-msg).
mh-next-unread-msg).
mh-previous-unread-msg).
mh-next-undeleted-msg).
mh-previous-undeleted-msg).
mh-prefix-help).
mh-ps-print-toggle-color).
mh-ps-print-toggle-faces).
mh-ps-print-msg-file).
mh-print-msg).
mh-ps-print-msg).
mh-prefix-help).
mh-store-msg).
mh-show-mouse).
Within the MH-Show buffer, the following command is defined.
mh-press-button).
The following table lists options in the mh-show customization group that are used while reading mail.
mh-bury-show-buffer-flagmh-clean-message-header-flagmh-decode-mime-flagmh-display-buttons-for-alternatives-flagmh-display-buttons-for-inline-parts-flagmh-do-not-confirm-flagmh-fetch-x-image-urlmh-graphical-smileys-flagmh-graphical-emphasis-flagmh-highlight-citation-stylemh-invisible-header-fields-defaultmh-invisible-header-fieldsnil).
mh-lpr-command-format"lpr -J '%s'").
mh-max-inline-image-heightmh-max-inline-image-widthmh-mhl-format-filemh-mime-save-parts-default-directorymh-print-background-flagmh-show-buffer-mode-line-buffer-idmode-line-buffer-identification for
show buffers (default: " {show-%s} %d").
mh-show-maximum-sizemh-show-use-xface-flagmh-store-default-directorymh-summary-heightThe following hooks are available.
mh-delete-msg-hooknil).
mh-show-hooknil).
mh-show-mode-hookmh-show-mode (default: nil).
The following faces are available.
mh-show-ccmh-show-datemh-show-frommh-show-headermh-show-pgg-badmh-show-pgg-goodmh-show-pgg-unknownmh-show-signaturemh-show-subjectmh-show-tomh-show-xfaceThe functions and variables introduced here are explained in more detail in the following sections.
The command <RET> (mh-show) displays the message that the
cursor is on while Mouse-2 (mh-show-mouse) displays the
message that the mouse cursor is on. If the message is already
displayed, it scrolls to the beginning of the message. Use <SPC>
(mh-page-msg) and <BS> (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 10 <SPC>). The <SPC>
command will also show the next undeleted message if it is used at the
bottom of a message. 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 command , (comma;
mh-header-display).
The option mh-show-maximum-size provides an opportunity to skip
over large messages which may be slow to load. The default value of 0
means that all message are shown regardless of size.
A litany of options control what displayed messages look like.
First, the appearance of the header fields can be modified by
customizing the associated face: mh-show-to, mh-show-cc,
mh-show-from, mh-show-date, and mh-show-subject.
The face mh-show-header is used to deemphasize the other, less
interesting, header fields.
Normally messages are delivered with a handful of uninteresting header
fields. These are hidden by turning on the option
mh-clean-message-header-flag (which it is by default). The
header fields listed in the option
mh-invisible-header-fields-default 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 option
mh-invisible-header-fields with a couple of caveats. Regular
expressions are not allowed. Unique fields should have a :
suffix; otherwise, the element can be used to render invisible an
entire class of fields that start with the same prefix. If you think a
header field should be generally ignored, report a bug (see Bug Reports).
MH-E can display the content of Face:, X-Face:, and
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
From: header field. If more than one of these fields appear,
then the first field found in the order Face:, X-Face:,
and X-Image-URL: will be used. The option
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.
The first header field used, if present, is the Gnus-specific Face: field14.
Next is the traditional X-Face: header field15. MH-E
renders the foreground and background of the image using the
associated attributes of the face mh-show-xface.
Finally, MH-E will display images referenced by the
X-Image-URL: header field if neither the Face: nor the
X-Face: fields are present16. 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. The option mh-fetch-x-image-url
controls the fetching of the X-Image-URL: header field image
with the following values:
There isn't a value of 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 (which is why you shouldn't blindly answer yes if you've set this option to Ask Before Fetching). 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.
The cache of images is found in the directory .mhe-x-image-cache within your MH directory. You can add your own face to the From: field too. See Picture.
Normally MH-E takes care of displaying messages itself (rather than
calling an MH program to do the work). If you'd rather have
mhl display the message (within MH-E), change the option
mh-mhl-format-file from its default value of Use Default
mhl Format (Printing Only). You can set this option to Use
Default mhl Format to get the same output as you would get if you ran
mhl from the shell. If you have a format file that you want
MH-E to use, you can set this option to Specify an mhl Format
File and enter the name of your format file (mhl(1) or
section Using mhl in
the MH book tells you how to write one). Your format file should
specify a non-zero value for overflowoffset to allow MH-E to
parse the header. Note that mhl is always used for printing
and forwarding; in this case, the value of mh-mhl-format-file
is consulted if you have specified a format file.
If the sender of the message has cited other messages in his message,
then MH-E will highlight these citations to emphasize the sender's
actual response. The option mh-highlight-citation-style can be
customized to change the highlighting style. The Multicolor
method uses a different color for each indentation while the
Monotone method highlights all citations in red. To disable
highlighting of citations entirely, choose None.
Email addresses and URLs in the message are highlighted if the option
goto-address-highlight-p is on, which it is by default. To view
the web page for a highlighted URL or to send a message using a
highlighted email address, use Mouse-2 or C-c <RET>
(goto-address-at-point). See Sending Mail, to see how to
configure Emacs to send the message using MH-E.
It is a long standing custom to inject body language using a
cornucopia of punctuation, also known as the smileys. MH-E can
render these as graphical widgets if the option
mh-graphical-smileys-flag is turned on, which it is by default.
Smileys include patterns such as :-) and ;-). Similarly, a few
typesetting features are indicated in ASCII text with certain
characters. If your terminal supports it, MH-E can render these
typesetting directives naturally if the option
mh-graphical-emphasis-flag is turned on, which it is by
default. For example, _underline_ will be
underlined,*bold* will appear in bold, /italics/ will appear in italics,
and so on. See the option gnus-emphasis-alist for the whole
list. Both of these options are disabled if the option
mh-decode-mime-flag is turned off. See Viewing Attachments.
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 signature separator ("-- ") to do this. You can also
customize the face mh-show-signature so the appearance of the
signature block is more to your liking.
Two hooks can be used to control how messages are displayed. The first
hook, mh-show-mode-hook, is called early on in the process of
the message display. It is usually used to perform some action on the
message's content. The second hook, 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 mh-show-mode-hook is too
early.
For those who like to modify their mode lines, use
mh-show-buffer-mode-line-buffer-id to modify the mode line in
the MH-Show buffers. Place the two escape strings %s and
%d, which will display the folder name and the message number,
respectively, somewhere in the string in that order. The default value
of "{show-%s} %d" yields a mode line of
-----{show-+inbox} 4 (MH-Show)--Bot--------------------------------
MH has the ability to display mime (Multipurpose Internet Mail Extensions) messages which are simply messages with additional body parts or attachments. You can use the MH commands show17 or mhshow18 from the shell to read mime messages19.
MH-E can handle attachments as well if the Gnus mm-decode
package is present. If so, the option mh-decode-mime-flag will
be on. Otherwise, you'll see the mime body parts rather than text
or attachments. There isn't much point in turning off the option
mh-decode-mime-flag; however, you can inspect it if it appears
that the body parts are not being interpreted correctly or toggle it
with the command ; (semicolon;
mh-toggle-mh-decode-mime-flag) to view the raw message. This
option also controls the display of quoted-printable messages and
other graphical widgets. See Viewing.
Attachments in MH-E are indicated by buttons like this:
[1. image/jpeg; foo.jpg]...
To view the contents of the button, use either Mouse-1 or
Mouse-2 on the button or <RET> (mh-press-button) when
the cursor is over the button. This command is a toggle so if you use
it again on the same attachment, it is hidden. If Emacs does not know
how to display the attachment, then Emacs offers to save the
attachment in a file. To move the cursor to the next button, use the
command K <TAB> (mh-next-button). If the end of the
buffer is reached then the search wraps over to the start of the
buffer. To move the cursor to the previous button, use the command
K S-<TAB> (mh-prev-button). If the beginning of the
buffer is reached then the search wraps over to the end of the buffer.
Another way to view the contents of a button is to use the command
K v (mh-folder-toggle-mime-part). This command displays
(or hides) the attachment associated with the button under the cursor.
If the cursor is not located over a button, then the cursor first
moves to the next button, wrapping to the beginning of the message if
necessary. This command has the advantage over the previous commands
of working from the MH-Folder buffer. You can also provide a numeric
prefix argument (as in 4 K v) to view the attachment labeled
with that number. If Emacs does not know how to display the
attachment, then Emacs offers to save the attachment in a file.
If Emacs does not know how to view an attachment, you could save it
into a file and then run some program to open it. It is easier,
however, to launch the program directly from MH-E with the command
K e (mh-display-with-external-viewer). While you'll most
likely use this to view spreadsheets and documents, it is also useful
to use your browser to view HTML attachments with higher fidelity than
what Emacs can provide. This command displays the attachment
associated with the button under the cursor. If the cursor is not
located over a button, then the cursor first moves to the next button,
wrapping to the beginning of the message if necessary. You can provide
a numeric prefix argument (as in 4 K e) to view the attachment
labeled with that number. This command tries to provide a reasonable
default for the viewer by calling the Emacs function
mailcap-mime-info. This function usually reads the file
/etc/mailcap.
Use the command K o (mh-folder-save-mime-part) to save
attachments (the mnemonic is “output”). This command saves the
attachment associated with the button under the cursor. If the cursor
is not located over a button, then the cursor first moves to the next
button, wrapping to the beginning of the message if necessary. You can
also provide a numeric prefix argument (as in 3 K o) to save the
attachment labeled with that number. This command prompts you for a
filename and suggests a specific name if it is available.
You can save all of the attachments at once with the command K a
(mh-mime-save-parts). The attachments are saved in the
directory specified by the option
mh-mime-save-parts-default-directory unless you use a prefix
argument (as in C-u K a) in which case you are prompted for the
directory. These directories may be superseded by MH profile
components, since this function calls on mhstore
(mhn) to do the work.
The default value for the option
mh-mime-save-parts-default-directory is Prompt Always so
that you are always prompted for the directory in which to save the
attachments. However, if you usually use the same directory within a
session, then you can set this option to Prompt the First Time
to avoid the prompt each time. you can make this directory permanent
by choosing Directory and entering the directory's name.
The sender can request that attachments should be viewed inline so
that they do not really appear like an attachment at all to the
reader. Most of the time, this is desirable, so by default MH-E
suppresses the buttons for inline attachments. On the other hand, you
may receive code or HTML which the sender has added to his message as
inline attachments so that you can read them in MH-E. In this case, it
is useful to see the buttons so that you know you don't have to cut
and paste the code into a file; you can simply save the attachment. If
you want to make the buttons visible for inline attachments, you can
use the command K t (mh-toggle-mime-buttons) to toggle
the visibility of these buttons. You can turn on these buttons
permanently by turning on the option
mh-display-buttons-for-inline-parts-flag.
MH-E cannot display all attachments inline however. It can display text (including html) and images.
Some older mail programs do not insert the needed
plumbing20 to tell MH-E whether to display the attachments inline
or not. If this is the case, MH-E will display these images inline if
they are smaller than the window. However, you might want to allow
larger images to be displayed inline. To do this, you can change the
options mh-max-inline-image-width and
mh-max-inline-image-height from their default value of zero to
a large number. The size of your screen is a good choice for these
numbers.
Sometimes, a mail program will produce multiple alternatives of an
attachment in increasing degree of faithfulness to the original
content. By default, only the preferred alternative is displayed. If
the option mh-display-buttons-for-alternatives-flag is on, then
the preferred part is shown inline and buttons are shown for each of
the other alternatives.
Many people prefer to see the text/plain alternative rather
than the text/html alternative. To do this in MH-E, customize
the option mm-discouraged-alternatives, and add
text/html. The next best alternative, if any, will be shown.
You can view the raw contents of an attachment with the command K
i (mh-folder-inline-mime-part). This command displays (or
hides) the contents of the attachment associated with the button under
the cursor verbatim. If the cursor is not located over a button, then
the cursor first moves to the next button, wrapping to the beginning
of the message if necessary. You can also provide a numeric prefix
argument (as in 4 K i) to view the attachment labeled with that
number.
For additional information on buttons, see the chapters Article Buttons and MIME Commands in the The Gnus Manual.
MH-E can display messages that have been sent in HTML21. The content of the message will appear in the MH-Show buffer as you would expect if the entire message is HTML, or there is an inline HTML body part. However, if there is an HTML body part that is an attachment, then you'll see a button like this:
[1. text/html; foo.html]...
To see how to read the contents of this body part, see Viewing Attachments.
The browser that MH-E uses is determined by the option
mm-text-html-renderer. 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. In particular, find and disable the option to render
images as this can tip off spammers that the email address they have
used is valid.
If you're confused about which mm-text-html-renderer to use,
here's a brief description of each, sorted by popularity, that
includes the results of a quick poll of MH-E users from 2005-12-23.
mh-folder-toggle-mime-part).
For a couple more sources of information about
mm-text-html-renderer,
see section Display Customization in the The Emacs MIME Manual and the the
documentation for the Gnus command W h (see section
Article Washing in the
The Gnus Manual).
A digest is a message that contains other messages. Special MH-E
commands let you read digests conveniently. You can use <SPC> and
<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
D <SPC> (mh-page-digest). To return to a previous message,
use D <BS> (mh-page-digest-backwards).