3. Customizing mh-e

Until now, we've talked about the mh-e commands as they work "out of the box." Of course, it is also possible to reconfigure mh-e to fit the needs of even the most demanding user. The following sections describe all of the customization variables, show the defaults, and make recommendations for customization. The outline of this chapter is identical to that of 2. Using mh-e, to make it easier to find the variables you'd need to modify to affect a particular command.

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.

Many string or integer variables are easy enough to modify using Emacs Lisp. Any such modifications should be placed in a file called `.emacs' in your home directory (that is, `~/.emacs'). For example, to modify the variable that controls printing, you could add:

(setq mh-lpr-command-format "nenscript -G -r -2 -i'%s'")

3.4.4 Printing Your Mail talks more about this variable.

Variables can also hold Boolean values. In Emacs Lisp, the Boolean values are nil, which means false, and t, which means true. Usually, variables are turned off by setting their value to nil, as in

(setq mh-bury-show-buffer nil)

which keeps the MH-Show buffer at the top of the buffer stack. To turn a variable on, you use

(setq mh-bury-show-buffer t)

which places the MH-Show buffer at the bottom of the buffer stack. However, the text says to turn on a variable by setting it to a non-nil value, because sometimes values other than t are meaningful (for example, see mhl-formfile, described in 3.1.1 Viewing Your Mail). Other variables, such as hooks, involve a little more Emacs Lisp programming expertise.

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

In general, commands in this text refer to Emacs Lisp functions. Programs outside of Emacs are specifically called MH commands, shell commands, or Unix commands.

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, (14) 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') 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.

3.1 Reading Your Mail

I'll start out by including a function that I use as a front end to mh-e. (15) 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 chapter, simply add the following code to `~/.emacs'. Don't be intimidated by the size of this example; most customizations are only one line.

Starting mh-e

(defvar my-mh-screen-saved nil
  "Set to non-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-nil or prefix argument, inc mailbox as well
when going into mail."
  (interactive "P")                 ; user callable function, P=prefix arg
  (setq my-mh-screen-saved          ; save state
        (cond
         ;; Bring up mh-e screen if arg or normal window configuration.
         ;; 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)                        ; set my-mh-screen-saved to t
         ;; Otherwise, save mh-e screen and restore normal screen.
         (t
          (setq my-mh-screen (current-window-configuration))
          (set-window-configuration my-normal-screen)
          nil))))                   ; set my-mh-screen-saved to nil

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

If you type an argument (C-u) or if my-mh-screen-saved is nil (meaning a non-mh-e window configuration), the current window configuration is saved, either +inbox is displayed or 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.

Now to configure mh-e. The following table lists general mh-e variables and variables that are used while reading mail.

mh-progs

Directory containing MH programs (default: dynamic).

mh-lib

Directory containing MH support files and programs (default: dynamic).

mh-do-not-confirm

Don't confirm on non-reversible commands (default: nil).

mh-summary-height

Number of scan lines to show (includes mode line) (default: 4).

mh-folder-mode-hook

Functions to run in MH-Folder mode (default: nil).

mh-clean-message-header

Remove extraneous headers (default: nil).

mh-invisible-headers

Headers to hide (default: `"^Received: \\| ^Message-Id: \\| ^Remailed-\\| ^Via: \\| ^Mail-from: \\| ^Return-Path: \\| ^In-Reply-To: \\| ^Resent-"').

mh-visible-headers

Headers to display (default: nil).

mhl-formfile

Format file for mhl (default: nil).

mh-show-hook

Functions to run when showing message (default: nil).

mh-show-mode-hook

Functions to run when showing message (default: nil).

mh-bury-show-buffer

Leave show buffer at bottom of stack (default: t).

mh-show-buffer-mode-line-buffer-id

Name of show buffer in mode line (default: `"{show-%s} %d"').

The two variables mh-progs and mh-lib are used to tell mh-e where the MH programs and supporting files are kept, respectively. mh-e does try to figure out where they are kept for itself by looking in common places and in the user's `PATH' environment variable, but if it cannot find the directories, or finds the wrong ones, you should set these variables. The name of the directory should be placed in double quotes, and there should be a trailing slash (`/'). See the example in 1.2 Getting Started.

If you never make mistakes, and you do not like confirmations for your actions, you can set mh-do-not-confirm to a non-nil value to disable confirmation for unrecoverable commands such as M-k (mh-kill-folder) and M-u (mh-undo-folder). Here's how you set boolean values:

(setq mh-do-not-confirm t)

The variable 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:

(setq mh-summary-height 2)              ; only show the current scan line

Normally the buffer for displaying messages is buried at the bottom at the buffer stack. You may wish to disable this feature by setting mh-bury-show-buffer to 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 M-x electric-buffer-list to see what I mean.

The hook 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:

Create additional key bindings via mh-folder-mode-hook

(defvar my-mh-init-done nil "Non-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)             ; only need to bind the keys once 
      (progn
        (local-set-key "/" 'search-msg)
        (local-set-key "b" 'mh-burst-digest)    ; better use of b
        (setq my-mh-init-done t))))

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

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

3.1.1 Viewing Your Mail

Several variables control what displayed messages look like. Normally messages are delivered with a handful of uninteresting header fields. You can make them go away by setting mh-clean-message-header to a non-nil value. The header can then be cleaned up in two ways. By default, the header fields in mh-invisible-headers are removed. On the other hand, you could set mh-visible-headers to the fields that you would like to see. If this variable is set, mh-invisible-headers is ignored. I suggest that you not set mh-visible-headers since if you use this variable, you might miss a lot of header fields that you'd rather not miss. As an example of how to set a string variable, mh-visible-headers can be set to show a minimum set of header fields (see (section `Syntax of Regular Expressions' in The GNU Emacs Manual, for a description of the special characters in this string):

(setq mh-visible-headers "^From: \\|^Subject: \\|^Date: ")

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), set the variable mhl-formfile to a non-nil value. You can set this variable either to t to use the default format file or to a filename if you have your own format file (mhl(1) tells you how to write one). When writing your own format file, use a nonzero value for overflowoffset to ensure the header is RFC 822 compliant and parsable by mh-e. mhl is always used for printing and forwarding; in this case, the value of mhl-formfile is consulted if it is a filename.

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 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 `From:' and `Subject:' header fields. This is a very nice feature indeed.

Emphasize header fields in different fonts via mh-show-mode-hook

(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))

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 example, if you wanted to keep mh-e in sync with MH, you could use mh-show-hook as follows:

(add-hook 'mh-show-hook 'mh-update-sequences)

The function mh-update-sequences is documented in 2.4.6 Finishing Up. 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----------------------------------

3.1.2 Moving Around

When you use t (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 mh-recenter-summary-p to a non-nil value causes the toggle to display as many scan lines as possible, with the cursor at the middle. The effect of mh-recenter-summary-p is rather useful, but it can be annoying on a slow network connection.

3.2 Sending Mail

You may wish to start off by adding the following useful key bindings to your `.emacs' file:

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

In addition, several variables are useful when sending mail or replying to mail. They are summarized in the following table.

mh-comp-formfile

Format file for drafts (default: `"components"').

mh-repl-formfile

Format file for replies (default: `"replcomps"').

mh-letter-mode-hook

Functions to run in MH-Letter mode (default: nil).

mh-compose-letter-function

Functions to run when starting a new draft (default: nil).

mh-reply-default-reply-to

Whom reply goes to (default: nil).

mh-forward-subject-format

Format string for forwarded message subject (default: `"%s: %s"').

mh-redist-full-contents

send requires entire message (default: nil).

mh-new-draft-cleaned-headers

Remove these header fields from re-edited draft (default: `"^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\| ^Sender:\\| ^Delivery-Date:\\| ^Return-Path:"').

Since mh-e does not use comp to create the initial draft, you need to set mh-comp-formfile to the name of your components file if it isn't `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 `/usr/local/lib/mh'). Replies, on the other hand, are built using repl. You can change the location of the field file from the default of `replcomps' by modifying mh-repl-formfile.

Two hooks are provided to run commands on your freshly created draft. The first hook, mh-letter-mode-hook, allows you to do some processing before editing a letter. For example, you may wish to modify the header after repl has done its work, or you may have a complicated `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.

Prepare draft for editing via mh-letter-mode-hook

(defvar letter-mode-init-done nil
  "Non-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)    ; 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 "  ")            ; I find indented text easier to read
  (save-excursion
    (goto-char (point-max))          ; go to end of message to
    (mh-insert-signature)))          ;   insert signature

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

The function, add-enriched-text is defined in the example in 3.3.2 Editing Multimedia Messages.

The second hook, a function really, is mh-compose-letter-function. Like 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 `To:', `Subject:', and `cc:' header fields.

3.2.1 Replying to Mail

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

3.2.2 Forwarding Mail

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

To: Bill Wohler <wohler@newt.com>
Subject: Re: 49er football
From: Greg DesBrisay <gd@cellnet.com>

and creates a subject header field of:

Subject: Greg DesBrisay: Re: 49er football

3.2.3 Redistributing Your Mail

The variable mh-redist-full-contents must be set to non-nil if dist requires the whole letter for redistribution, which is the case if send is compiled with the BERK (16) 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 nil.

3.2.4 Editing Old Drafts and Bounced Messages

The header fields specified by mh-new-draft-cleaned-headers are removed from an old draft that has been recreated with M-e (mh-extract-rejected-mail) or M-a (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,

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

This appends the regular expression `\\|^Some-Field:' to the variable (see section `Syntax of Regular Expressions' in The GNU Emacs Manual). The `\\|' means or, and the `^' (caret) matches the beginning of the line. This is done to be very specific about which fields match. The literal `:' is appended for the same reason.

3.3 Editing a Draft

There are several variables used during the draft editing phase. Examples include changing the name of the file that holds your signature or telling mh-e about new multimedia types. They are:

mh-yank-from-start-of-msg

How to yank when region not set (default: t).

mh-ins-buf-prefix

Indent for yanked messages (default: `"> "').

mail-citation-hook

Functions to run on yanked messages (default: nil).

mh-delete-yanked-msg-window

Delete message window on yank (default: nil).

mh-mime-content-types

List of valid content types (default: `'(("text/plain")
("text/richtext") ("multipart/mixed") ("multipart/alternative")
("multipart/digest") ("multipart/parallel") ("message/rfc822")
("message/partial") ("message/external-body")
("application/octet-stream") ("application/postscript")
("image/jpeg") ("image/gif") ("audio/basic") ("video/mpeg"))').

mh-mhn-args

Additional arguments for mhn (default: nil).

mh-signature-file-name

File containing signature (default: `"~/.signature"').

mh-before-send-letter-hook

Functions to run before sending draft (default: nil).

mh-send-prog

MH program used to send messages (default: `"send"').

3.3.1 Editing Textual Messages

The following two sections include variables that customize the way you edit a draft. The discussion here applies to editing multimedia messages as well.

3.3.1.1 Inserting letter to which you're replying

To control how much of the message to which you are replying is yanked by C-c C-y (mh-yank-cur-msg) into your reply, modify mh-yank-from-start-of-msg. The default value of t means that the entire message is copied. If it is set to 'body (don't forget the apostrophe), then only the message body is copied. If it is set to 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. The string contained in mh-ins-buf-prefix is inserted before each line of a message that is inserted into a draft with C-c C-y (mh-yank-cur-msg). I suggest that you not modify this variable. The default value of `"> "' 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 mail-citation-hook is nil by default, which means that when a message is inserted into the letter, each line is prefixed by mh-ins-buf-prefix. Otherwise, it can be set to a function that modifies an included citation. (17) If you like to yank all the text from the message you're replying to in one go, set mh-delete-yanked-msg-window to non-nil to delete the window containing the original message after yanking it to make more room on your screen for your reply.

3.3.1.2 Inserting your signature

You can change the name of the file inserted with C-c C-s (mh-insert-signature) by changing mh-signature-file-name (default: `"~/.signature"').

3.3.2 Editing Multimedia Messages

The variable mh-mime-content-types contains a list of the currently valid content types. They are listed in the table in 3.3 Editing a Draft. If you encounter a new content type, you can add it like this:

(setq mh-mime-content-types (append mh-mime-content-types
                                    '(("new/type"))))

Emacs macros can be used to insert enriched text directives like `<bold>'. The following code will make, for example, C-c t b insert the `<bold>' directive.

Emacs macros for entering enriched text

(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") ("f" . "fixed")
                              ("s" . "smaller") ("B" . "bigger")
                              ("u" . "underline") ("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")
  ;; Set type to the directive indicated by the last keystroke.
  (let ((type (cdr (assoc (char-to-string (logior last-input-char ?`))
                          enriched-text-types))))
    (save-restriction              ; restores state from narrow-to-region
      (narrow-to-region begin end) ; narrow view to region
      (goto-char (point-min))      ; move to beginning of text
      (insert "<" type ">")        ; insert beginning directive
      (goto-char (point-max))      ; move to end of text
      (insert "</" type ">"))))    ; insert terminating directive

To use the function add-enriched-text, first create keybindings for it (see section 3.2 Sending Mail). Then, set the mark with C-@ or C-SPC, type in the text to be highlighted, and type C-c t b. This adds `<bold>' where you set the mark and adds `</bold>' at the location of your cursor, giving you something like: `You should be <bold>very</bold>'. You may also be interested in investigating sgml-mode.

3.3.2.1 Readying multimedia messages for sending

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

3.3.3 Sending a Message

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

Spell-check message via mh-before-send-letter-hook

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

In case the MH send program is installed under a different name, use mh-send-prog to tell mh-e the name.

3.4 Moving Your Mail Around

If you change the name of some of the MH programs or have your own printing programs, the following variables can help you. They are described in detail in the subsequent sections.

mh-inc-prog

Program to incorporate mail (default: `"inc"').

mh-inc-folder-hook

Functions to run when incorporating mail (default: nil).

mh-delete-msg-hook

Functions to run when deleting messages (default: nil).

mh-print-background

Print in foreground or background (default: nil).

mh-lpr-command-format

Command used to print (default: `"lpr -J '%s'"').

mh-default-folder-for-message-function

Function to generate a default folder (default: nil).

mh-auto-folder-collect

Collect folder names in background at startup (default: t).

mh-recursive-folders

Collect nested folders (default: nil).

mh-refile-msg-hook

Functions to run when refiling message (default: nil).

mh-store-default-directory

Default directory for storing files created by uuencode or shar (default: nil).

mh-sortm-args

Additional arguments for sortm (default: nil).

mh-scan-prog

Program to scan messages (default: `"scan"').

mh-before-quit-hook

Functions to run before quitting (default: nil). See also mh-quit-hook.

mh-quit-hook

Functions to run after quitting (default: nil). See also mh-before-quit-hook.

3.4.1 Incorporating Your Mail

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. You may also link a file to inc that uses a different format (see mh-profile(5)). You'll then need to modify several variables appropriately; see mh-scan-prog below. 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.

Rescan folder after incorporating new mail via mh-inc-folder-hook

(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)

3.4.2 Deleting Your Mail

The hook 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.

3.4.3 Organizing Your Mail with Folders

By default, operations on folders work only one level at a time. Set mh-recursive-folders to non-nil to operate on all folders. This mostly means that you'll be able to see all your folders when you press TAB when prompted for a folder name. The variable mh-auto-folder-collect is normally turned on to generate a list of folder names in the background as soon as mh-e is loaded. Otherwise, the list is generated when you need a folder name the first time (as with o (mh-refile-msg)). If you have a lot of folders and you have mh-recursive-folders set, this could take a while, which is why it's nice to do the folder collection in the background.

The function mh-default-folder-for-message-function is used by o (mh-refile-msg) and C-c C-f C-f (mh-to-fcc) to generate a default folder. The generated folder name should be a string with a `+' before it. For each of my correspondents, I use the same name for both an alias and a folder. So, I wrote a function that takes the address in the `From:' header field, finds it in my alias file, and returns the alias, which is used as a default folder name. This is the most complicated example given here, and it demonstrates several features of Emacs Lisp programming. You should be able to drop this into `~/.emacs', however. If you use this to store messages in a subfolder of your Mail directory, you can modify the line that starts `(format +%s...' and insert your subfolder after the folder symbol `+'.

Creating useful default folder for refiling via mh-default-folder-for-message-function

(defun my-mh-folder-from-address ()
  "Determine folder name from address.
Takes the address in the From: header field, and returns its corresponding
alias from the user's personal aliases file. Returns nil if the address
was not found."
  (require 'rfc822)                         ; for the rfc822 functions
  (search-forward-regexp "^From: \\(.*\\)") ; grab header field contents
  (save-excursion                     ; save state
    (let ((addr (car (rfc822-addresses  ; get address
                      (buffer-substring (match-beginning 1)
                                        (match-end 1)))))
          (buffer (get-buffer-create " *temp*")) ; set local variables
          folder)
      (set-buffer buffer)             ; jump to temporary buffer
      (unwind-protect                 ; run kill-buffer when done
          (progn                      ; function grouping construct
            (insert-file-contents (expand-file-name "aliases"
                                                    mh-user-path))
            (goto-char (point-min))   ; grab aliases file and go to start
            (setq folder
                  ;; Search for the given address, even commented-out
                  ;; addresses are found!
                  ;; The function search-forward-regexp sets values that are
                  ;; later used by match-beginning and match-end.
                  (if (search-forward-regexp (format "^;*\\(.*\\):.*%s"
                                                     addr) nil t)
                      ;; NOTE WELL: this is what the return value looks like.
                      ;; You can modify the format string to match your own
                      ;; Mail hierarchy.
                      (format "+%s" (buffer-substring (match-beginning 1)
                                                      (match-end 1))))))
        (kill-buffer buffer))          ; get rid of our temporary buffer
      folder)))                        ; function's return value

(setq mh-default-folder-for-message-function 'my-mh-folder-from-address)

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

The variable mh-sortm-args holds extra arguments to pass on to the sortm command. Note: this variable is only consulted when a prefix argument is given to M-x mh-sort-folder. It is used to override any arguments given in a sortm: entry in your MH profile (`~/.mh_profile').

3.4.3.1 Scan line formatting

The name of the program that generates a listing of one line per message is held in mh-scan-prog (default: `"scan"'). Unless this variable contains an absolute pathname, it is assumed to be in the mh-progs directory. You may link another program to scan (see mh-profile(5)) to produce a different type of listing.

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. The first variable has to do with pruning out garbage.

mh-valid-scan-line

This regular expression describes a valid scan line. This is used to eliminate error messages that are occasionally produced by inc or scan (default: `"^ *[0-9]"').

Next, two variables control how the message numbers are parsed.

mh-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 quoted parentheses, (\\(...\\)), as in the default of `"^ *\\([0-9]+\\)"'.

mh-msg-search-regexp

Given a message number (which is inserted in `%d'), this regular expression will match the scan line that it represents (default: `"^[^0-9]*%d[^0-9]"').

Finally, there are a slew of variables that control how mh-e marks up the scan lines.

mh-cmd-note

Number of characters to skip over before inserting notation (default: 4). Note how it relates to the following regular expressions.

mh-deleted-msg-regexp

This regular expression describes deleted messages (default: `"^....D"'). See also mh-note-deleted.

mh-refiled-msg-regexp

This regular expression describes refiled messages (default: `"^....\\^"'). See also mh-note-refiled.

mh-cur-scan-msg-regexp

This regular expression matches the current message (default: `"^....\\+"'). See also mh-note-cur.

mh-good-msg-regexp

This regular expression describes which messages should be shown when mh-e goes to the next or previous message. Normally, deleted or refiled messages are skipped over (default: `"^....[^D^]"').

mh-note-deleted

Messages that have been deleted to are marked by this string (default: `"D"'). See also mh-deleted-msg-regexp.

mh-note-refiled

Messages that have been refiled are marked by this string (default: `"^"'). See also mh-refiled-msg-regexp.

mh-note-copied

Messages that have been copied are marked by this string (default: `"C"').

mh-note-cur

The current message (in MH, not in mh-e) is marked by this string (default: `"+"'). See also mh-cur-scan-msg-regexp.

mh-note-repl

Messages that have been replied to are marked by this string (default: `"-"').

mh-note-forw

Messages that have been forwarded are marked by this string (default: `"F"').

mh-note-dist

Messages that have been redistributed are marked by this string (default: `"R"').

mh-note-printed

Messages that have been printed are marked by this string (default: `"P"').

mh-note-seq

Messages in a sequence are marked by this string (default: `"%"').

3.4.4 Printing Your Mail

Normally messages are printed in the foreground. If this is slow on your system, you may elect to set mh-print-background to non-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 mh-lpr-command-format controls how the printing is actually done. The string can contain one escape, `%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 `"lpr -J '%s'"'.

3.4.5 Files and Pipes

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

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

Subsequent incarnations of mh-store-msg offer the last directory used as the default. By the way, mh-store-msg calls the Emacs Lisp function 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 uuencode or shar. For example, you can extract the contents of the current buffer in your home directory by typing M-x mh-store-buffer RET ~ RET.

3.4.6 Finishing Up

The two variables mh-before-quit-hook and mh-quit-hook are called by q (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 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.

3.5 Searching Through Messages

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 mh-pick-mode-hook, which is called when M-s (mh-search-folder) is run on a new pattern.

The string mh-partial-folder-mode-line-annotation is used to annotate the mode line when only a portion of the folder is shown. For example, this will be displayed after running M-s (mh-search-folder) to list messages based on some search criteria (see 2.5 Searching Through Messages). The default annotation of `"select"' yields a mode line that looks like:

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

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.