Mercurial > emacs
diff man/mh-e.texi @ 69313:a81d6bd38fa8
Move from SourceForge repository to Savannah. This is version 7.93,
which is a total rewrite from the previous edition 1.3 for MH-E
version 5.0.2, and corresponds to MH-E version 7.93.
| author | Bill Wohler <wohler@newt.com> |
|---|---|
| date | Tue, 07 Mar 2006 00:34:25 +0000 |
| parents | dc2d5a6655a3 |
| children | abc374b7aa85 |
line wrap: on
line diff
--- a/man/mh-e.texi Mon Mar 06 22:31:36 2006 +0000 +++ b/man/mh-e.texi Tue Mar 07 00:34:25 2006 +0000 @@ -1,928 +1,3807 @@ \input texinfo @c -*-texinfo-*- +@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 +@settitle The MH-E Manual @c %**end of header -@c Version variables. -@set EDITION 1.3 -@set VERSION 5.0.2 -@set UPDATED 18 February 2001 -@set UPDATE-MONTH February 2001 - +@c Version of the software and manual. +@set VERSION 7.93 +@c EDITION of the manual. It is either empty for the first edition or +@c has the form ", nth Edition" (without the quotes). +@set EDITION +@set UPDATED 2006-03-05 +@set UPDATE-MONTH March, 2006 + +@c Other variables. +@set MH-BOOK-HOME http://www.ics.uci.edu/~mh/book/mh +@set MH-E-HOME http://mh-e.sourceforge.net/ + +@c Copyright @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 (C) 1995, 2001, 2002, 2003, 2004, - 2005, 2006 Free Software Foundation, Inc. +This is version @value{VERSION}@value{EDITION} of @cite{The MH-E +Manual}, last updated @value{UPDATED} + +Copyright @copyright{} 1995, + 2001, 2002, 2003, 2005, 2006 Free Software Foundation, Inc. @quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify -this GNU Manual, like GNU software. Copies published by the Free -Software Foundation raise funds for GNU development.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. +The MH-E manual is free documentation; you can redistribute it and/or +modify it under the terms of either: + +@enumerate a +@item +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. + +@item +the GNU General Public License as published by the Free Software +Foundation; either version 2, or (at your option) any later version. +@end enumerate + +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. @end quotation @end copying -@setchapternewpage odd - +@c Info Directory Entry @dircategory Emacs @direntry * MH-E: (mh-e). Emacs interface to the MH mail system. @end direntry +@c Title Page +@setchapternewpage odd @titlepage -@sp 10 -@center @titlefont{mh-e} -@sp 2 -@center The Emacs Interface to MH -@sp 2 -@center by Bill Wohler -@sp 2 -@center Edition @value{EDITION} for mh-e Version @value{VERSION} -@sp 2 -@center @value{UPDATE-MONTH} - +@title The MH-E Manual +@subtitle Version @value{VERSION}@value{EDITION} +@subtitle @value{UPDATE-MONTH} +@author Bill Wohler + +@c Copyright Page @page @vskip 0pt plus 1filll -Copyright @copyright{} 1995, 2001, 2002, 2006 Free Software Foundation, Inc. @insertcopying @end titlepage @ifnottex +@html +<!-- +@end html @node Top, Preface, (dir), (dir) -@top MH and Emacs -This is Edition @value{EDITION} of @cite{mh-e, The Emacs Interface to -MH}, last updated @value{UPDATED} for mh-e Version @value{VERSION}. +@top The MH-E Manual +@html +--> +@end html +@insertcopying +@end ifnottex + +@c Table of Contents +@contents + +@html +<!-- +@end html @menu -* Preface:: Introduction to mh-e. -* Tour Through mh-e:: Use mh-e quickly! -* Using mh-e:: Documentation for all commands. -* Customizing mh-e:: Documentation for all variables. -* Odds and Ends:: Getting mh-e, reporting bugs, mailing - list and FAQ. -* History:: The authors speak up! -* Copying:: The GNU General Public License -* Command Index:: -* Variable Index:: -* Concept Index:: +* Preface:: Preface +* Conventions:: GNU Emacs Terms and Conventions +* Getting Started:: Getting Started +* Tour Through MH-E:: Tour Through MH-E +* Using This Manual:: Using This Manual +* 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 +* Menu Bar:: The Menu Bar +* Tool Bar:: The Tool Bar +* Searching:: Searching Through Messages +* Threading:: Viewing Message Threads +* Limits:: Limiting Display +* Sequences:: Using Sequences +* Junk:: Dealing With Junk Mail +* Miscellaneous:: Miscellaneous Commands, Variables, and Buffers +* Scan Line Formats:: Scan Line Formats +* Procmail:: Reading Mailing Lists Effectively +* Odds and Ends:: Odds and Ends +* History:: History of MH-E +* GFDL:: GNU Free Documentation License +* GPL:: GNU Public License +* Key Index:: Key (Character) Index +* Command Index:: Command Index +* Option Index:: Option (Variable) Index +* Concept Index:: Concept Index + +@detailmenu + --- The Detailed Node Listing --- + +Tour Through MH-E + +* Sending Mail Tour:: +* Reading Mail Tour:: +* Processing Mail Tour:: +* Leaving MH-E:: +* More About MH-E:: + +Using This Manual + +* Options:: +* Ranges:: +* Folder Selection:: + +Reading Your Mail + +* Viewing:: +* Viewing Attachments:: +* HTML:: +* Digests:: +* Reading PGP:: +* Printing:: +* Files and Pipes:: +* Navigating:: +* Miscellaneous Commands and Options:: + +Sending Mail + +* Composing:: +* Replying:: +* Forwarding:: +* Redistributing:: +* Editing Again:: + +Editing a Draft + +* Editing Message:: +* Inserting Letter:: +* Inserting Messages:: +* Signature:: +* Picture:: +* Adding Attachments:: +* Sending PGP:: +* Checking Recipients:: +* Sending Message:: +* Killing Draft:: + +Odds and Ends + +* Bug Reports:: +* Mailing Lists:: +* MH FAQ and Support:: +* Getting MH-E:: + +History of MH-E + +* From Brian Reid:: +* From Jim Larus:: +* From Stephen Gildea:: +* From Bill Wohler:: + +@end detailmenu @end menu -@end ifnottex - -@node Preface, Tour Through mh-e, Top, Top + +@html +--> +@end html + +@node Preface, Conventions, 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 history - -The mh-e package is distributed with GNU Emacs, @footnote{Note that -mh-e is supported with MH 6 and @w{Emacs 18} and up. -Reportedly, large parts of it work with @w{MH 5} and also with -Lucid/XEmacs and Epoch, but there are no guarantees. It is also -distributed with Lucid/XEmacs, as well as with MH itself.} 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}. 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}). (This notation is described in -@ref{Conventions}.) If you want to take the plunge, consult the +This manual introduces another interface to the MH mail system 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. + +The MH-E package is distributed with GNU Emacs@footnote{Version +@value{VERSION} of MH-E will appear in GNU Emacs 22.1. It is supported +in GNU Emacs 21, as well as XEmacs 21 (except for versions +21.5.9-21.5.16). It is compatible with MH versions 6.8.4 and higher, +all versions of nmh, and GNU mailutils 0.4 and higher.}, so you +shouldn't have to do anything special to use it. This manual covers +MH-E version @value{VERSION}. @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, The GNU Emacs Manual}, +@ref{top, , GNU Emacs Manual, emacs, GNU Emacs Manual}, @end ifinfo +@ifhtml +@uref{http://www.gnu.org/software/emacs/manual/html_node/, +@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 +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. -I hope you enjoy these chapters! If you have any comments, or -suggestions for this document, please let me know. +This manual is available in both Info and online formats. The Info +version is distributed with Emacs and can be accessed with the +@command{info} command (@samp{info mh-e}) or within Emacs (@kbd{M-x +info @key{RET} m mh-e @key{RET}}). The online version is available at +@uref{http://mh-e.sourceforge.net/manual/, SourceForge}. Another great +online resource is the book @uref{http://www.ics.uci.edu/~mh/book/, +@cite{MH & nmh: Email for Users & Programmers}} (also known as +@dfn{the MH book}). + +I hope you enjoy this manual! 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@@newt.com}>@* -8 February 1995 - -@node Tour Through mh-e, Using mh-e, 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 major -section in @ref{Using mh-e}, 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 type, you'll read @ref{Using mh-e} to be able to use all -the features of mh-e. If you're the adventurous type, you'll read -@ref{Customizing mh-e} to make mh-e do what you want. I suggest you -read this chapter first to get the big picture, and then you can read -the other two 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, terms and conventions +Bill Wohler <@i{wohler at newt.com}>@* +8 February 1995@* +24 February 2006 + +@node Conventions, Getting Started, Preface, Top +@chapter 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 @ref{Getting -Started} below. The conventions are as follows: +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. +@c ------------------------- @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 +@kbd{M-x}, for example, by pressing @key{ESC} (Escape), +@emph{releasing it}, and then pressing the @kbd{x} key. +@c ------------------------- +@item @key{RET} +Press the @key{RETURN} or @key{ENTER} key. This is normally used to complete a command. -@item SPC +@c ------------------------- +@item @key{SPC} Press the space bar. -@item TAB +@c ------------------------- +@item @key{TAB} Press the @key{TAB} key. -@item DEL +@c ------------------------- +@item @key{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.} +@c ------------------------- +@item @key{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 +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 +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 +@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 2 -@need 1000 +@sp 1 @center @strong{NOTE} @quotation -The prefix @kbd{C-u} or @kbd{M-} is not necessary in mh-e's MH-Folder -modes (@pxref{Reading Mail Tour}). In these modes, simply enter the +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 - -@cindex point +@sp 1 + +@cindex Emacs, variables +@cindex variables + +Emacs uses @dfn{variables} to hold values. These can be changed via +calls to the function @code{setq} in @file{~/.emacs}. + +@cindex Emacs, options +@cindex options +@findex customize-group +@findex customize-option + +Variables in MH-E that are normally 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}). +@ifnothtml +@xref{Easy Customization,,,emacs,The GNU Emacs Manual}, in @cite{The +GNU Emacs Manual}. +@end ifnothtml +@ifhtml +See section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Easy-Customization.html, +Easy Customization} in @cite{The GNU Emacs Manual}. +@end ifhtml +@xref{Options}. + +@cindex Emacs, faces +@cindex faces +@cindex highlighting +@findex customize-face + +You can specify various styles for displaying text using @dfn{faces}. +MH-E provides a set of faces that you can use to personalize the look +of your MH-E buffers. Use the command @kbd{M-x customize-face} to do +this. +@ifnothtml +@xref{Face Customization,,,emacs,The GNU Emacs Manual}, in @cite{The +GNU Emacs Manual}. +@end ifnothtml +@ifhtml +See section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Face-Customization.html, +Face Customization} in @cite{The GNU Emacs Manual}. +@end ifhtml + +@cindex hooks +@cindex normal hooks +@cindex abnormal hooks + +Commands often offer @dfn{hooks} which enable you to extend or modify +the way a command works. +@ifnothtml +@ref{Hooks, , Hooks, emacs, The GNU Emacs Manual}, in @cite{The GNU +Emacs Manual} +@end ifnothtml +@ifhtml +See section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Hooks.html, +Hooks} in @cite{The GNU Emacs Manual} +@end ifhtml +for a description about @dfn{normal hooks} and @dfn{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 @code{-hooks} and all the rest +of the MH-E hooks end in @code{-hook}. + +@cindex Emacs, mark @cindex Emacs, point +@cindex Emacs, region @cindex mark -@cindex Emacs, mark +@cindex point @cindex region -@cindex Emacs, 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}). - +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-@key{SPC}}). + +@cindex Emacs, completion +@cindex Emacs, file completion +@cindex Emacs, folder completion +@cindex Emacs, minibuffer +@cindex completion +@cindex file completion +@cindex folder completion @cindex minibuffer -@cindex Emacs, minibuffer -@cindex file completion -@cindex Emacs, file completion 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 first paragraph, I mentioned that you -could obtain help with @kbd{C-h t} (@code{help-with-tutorial}). What +prompting and multiple-character input is directed. You can use +@dfn{completion} to enter values such as folders. Completion means +that Emacs fills in text for you when you type @key{SPC} or @key{TAB}. +A second @key{SPC} or @key{TAB} will list all possibilities at that +point. +@ifnothtml +@xref{Completion, , Completion, emacs, The GNU Emacs Manual}. +@end ifnothtml +@ifhtml +See the section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, +Completion} in @cite{The GNU Emacs Manual}. +@end ifhtml +Note that @key{SPC} cannot be used for completing filenames and +folders. + +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}. - +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 ~ + +The @samp{~} notation in filenames represents your home directory. +This notation is used by many shells including @command{bash}, +@code{tcsh}, and @command{csh}. It is analogous to the environment +variable @samp{$HOME}. For example, @file{~/.emacs} can be written +@file{$HOME/.emacs} or using the absolute path as in +@file{/home/wohler/.emacs} instead. + +@cindex Emacs, interrupting +@cindex Emacs, quitting @cindex interrupting -@cindex Emacs, interrupting @cindex quitting -@cindex Emacs, 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 +@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 +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 - -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 5} which -is similar to @w{Version 4} and vastly different from @w{Version 3}. - -First, enter @kbd{M-x load-library @key{RET} mh-e -@key{RET}}. @footnote{You wouldn't ordinarily do this.} 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. - -Having loaded mh-e successfully, 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 an old version of mh-e. - -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; instructions for getting -and installing mh-e are in @ref{Getting mh-e}. - -@cindex @code{install-mh} -@cindex MH commands, @code{install-mh} - -Also, older versions of mh-e assumed that you had already set up your MH -environment. Newer versions set up a new MH environment for you by -running @code{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 @code{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} - -If, during the tour described in this chapter, you see a message like: -@samp{Searching for program: no such file or directory, -/usr/local/bin/mhpath}, it means that the MH programs and files are kept -in a nonstandard directory. In this case, simply add the following to -@file{~/.emacs} and restart @code{emacs}. - -@vindex @code{mh-progs}, example -@vindex @code{mh-lib}, example - -@c XXX Real example for really naive user? -@example -@group -(setq mh-progs "@var{/path/to/MH/binary/directory/}") -(setq mh-lib "@var{/path/to/MH/library/directory/}") -@end group -@end example - -@cindex ~ - -The @samp{~} notation used by @file{~/.emacs} above represents your home -directory. This is used by the @code{bash} and @code{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 +@node Getting Started, Tour Through MH-E, Conventions, Top +@chapter 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}. It differs +from @w{Version 4} and @w{Version 5} and is vastly different from +@w{Version 3}. @xref{History}. + +@findex mh-version + +To determine which version of MH-E that you have, enter @kbd{M-x +mh-version @key{RET}}. Hopefully it says that you're running +@w{Version @value{VERSION}} 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. @xref{Getting MH-E}, for instructions for getting and +installing MH-E. + +If the @code{mh-version} command displays @samp{No MH variant +detected}, then you need to install MH or tell MH-E where to find +MH@footnote{In very old versions of MH-E, you may get the error +message, @samp{Cannot find the commands `inc' and `mhl' and the file +`components'} if MH-E can't find MH. In this case, you need to update +MH-E, and you may need to install MH too. However, newer versions of +MH-E are better at finding MH if it is on your system.}. + +The option @code{mh-variant} specifies the variant used by MH-E +(@pxref{Options}). The default setting of this option is +@samp{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 @code{mh-path} (which you can customize), +@code{mh-sys-path}, and @code{exec-path}. If MH-E can't find MH at +all, you may have to customize @code{mh-path} and add the directory in +which the command @code{mhparam} is located. If, on the other hand, +you have both nmh and mailutils installed (for example) and +@code{mh-variant-in-use} was initialized to nmh but you want to use +mailutils, then you can set @code{mh-variant} to @samp{mailutils}. + +When @code{mh-variant} is changed, MH-E resets @code{mh-progs}, +@code{mh-lib}, @code{mh-lib-progs}, @code{mh-flists-present-flag}, and +@code{mh-variant-in-use} accordingly. + +@sp 1 +@center @strong{NOTE} + +@quotation +Prior to version 8, it was often necessary to set some of these +variables in @file{~/.emacs}; now it is no longer necessary and can +actually cause problems. +@end quotation +@sp 1 + +@cindex @command{install-mh} +@cindex MH commands, @command{install-mh} + +If you've never run MH before, you need to run @command{install-mh} +from the shell before you continue. This sets up your personal MH +environment@footnote{See the section +@uref{@value{MH-BOOK-HOME}/setup.htm, Setting Up MH} in the MH book.}. +If you don't, you'll be greeted with the error message: @samp{Install +MH and run install-mh before running MH-E}. + +@cindex @samp{Draft-Folder:} MH profile component +@cindex @samp{Path:} MH profile component +@cindex @samp{Previous-Sequence:} MH profile component +@cindex @samp{Unseen-Sequence:} MH profile component +@cindex MH profile component, @samp{Draft-Folder:} +@cindex MH profile component, @samp{Path:} +@cindex MH profile component, @samp{Previous-Sequence:} +@cindex MH profile component, @samp{Unseen-Sequence:} +@findex mh-find-path +@vindex mh-draft-folder +@vindex mh-find-path-hook +@vindex mh-inbox +@vindex mh-previous-seq +@vindex mh-unseen-seq +@vindex mh-user-path + +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 @code{mh-find-path} sets +@code{mh-user-path} from your @samp{Path:} MH profile component (but +defaults to @samp{Mail} if one isn't present), @code{mh-draft-folder} +from @samp{Draft-Folder:}, @code{mh-unseen-seq} from +@samp{Unseen-Sequence:}, @code{mh-previous-seq} from +@samp{Previous-Sequence:}, and @code{mh-inbox} from @samp{Inbox:} +(defaults to @samp{+inbox}). The hook @code{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. + +@node Tour Through MH-E, Using This Manual, Getting Started, 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 +* Sending Mail Tour:: +* Reading Mail Tour:: +* Processing Mail Tour:: +* Leaving MH-E:: +* More About MH-E:: +@end menu + +@node Sending Mail Tour, Reading Mail Tour, Tour Through MH-E, Tour Through MH-E @section Sending Mail @cindex sending mail -@findex @code{mh-smail} +@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. +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. I've left -out the menubar in all of the example screens.} - -@example -@group +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 menu bar. Under +Emacs 21, you would also see a tool bar. I've left out the menu bar and +tool bar in all of the example screens.}: + @cartouche - - - - - - ------Emacs: *scratch* (Lisp Interaction)--All------------------- +@smallexample + + + + + + +--:-- *scratch* (Lisp Interaction)--L1--All------------------------- To: wohler cc: Subject: Test -------- - This is a test message to get the wheels churning...# - - ---**-@{draft@} (MH-Letter)--All------------------------------------- - +This is a test message to get the wheels churning...# + + +--:** @{draft@} (MH-Letter)--L5--All----------------------------------- + +@end smallexample @end cartouche -@i{mh-e message composition window} -@end group -@end example - -@cindex MH-Letter mode -@cindex modes, MH-Letter +@i{MH-E message composition window} 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 +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 mode, 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 +@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 reading mail -@findex @code{mh-rmail} -@cindex @code{inc} -@cindex MH commands, @code{inc} -@cindex @code{scan} -@cindex MH commands, @code{scan} +@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 @code{inc} -(called @dfn{scan lines} after the MH program @code{scan} which prints a -one-line summary of each message) into a buffer called @samp{+inbox} -whose major mode is MH-Folder. - -@sp 2 -@need 1000 +This incorporates the new mail and puts 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 old -mail. If you were to run this tour again, you would use @kbd{M-r} to -pull all your messages into mh-e. +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 - -You should see the scan line for your message, and perhaps others. Use +@sp 1 + +@kindex @key{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: - -@example -@group +@key{RET} to read your message. You should see something like: + @cartouche - 3 24Aug root received fax files on Wed Aug 24 11:00:13 PDT 1994 -# 4+ 24Aug To:wohler Test<<This is a test message to get the wheels chu - ---%%-@{+inbox@} 4 msgs (1-4) (MH-Folder Show)--Bot------------------ +@smallexample + 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@@newt.com> - - This is a test message to get the wheels churning... - - - - - ------@{show-+inbox@} 4 (MH-Show)--Bot------------------------------- - +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 smallexample @end cartouche @i{After incorporating new messages} -@end group -@end example - -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 + +@kindex @key{DEL} +@kindex @key{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. +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: -@example -@group @cartouche +@smallexample To: wohler Subject: Re: Test In-reply-to: Bill Wohler's message of Wed, 24 Aug 1994 13:01:13 -0700 - <199408242001.NAA00505@@newt.com> + <199408242001.NAA00505@@stop.mail-abuse.org> -------- # ---**-@{draft@} (MH-Letter)--All------------------------------------- +--:-- @{draft@} (MH-Letter)--L11--Bot--------------------------------- To: wohler Subject: Test Date: Wed, 24 Aug 1994 13:01:13 -0700 -From: Bill Wohler <wohler@@newt.com> - - This is a test message to get the wheels churning... - ------@{show-+inbox@} 4 (MH-Show)--Bot------------------------------- +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 smallexample @end cartouche @i{Composition window during reply} -@end group -@end example - -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 folder - -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 (@code{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. + +@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 folder:} 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 - -Your previous reply is now waiting in the system mailbox. You +@kindex @key{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, +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 @code{mh-smail} +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! - -@node Leaving mh-e, More About mh-e, Processing Mail Tour, Tour Through mh-e -@section Leaving mh-e +@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 @code{emacs} entirely. Use @kbd{C-x C-c} to -exit @code{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. +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 them entirely with @kbd{C-x k}. You can then -later recall them with @kbd{C-x b} or @kbd{M-x mh-rmail}. - -@node More About mh-e, , Leaving mh-e, Tour Through mh-e -@section More About mh-e +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}. + +@cindex @command{packf} +@cindex MH commands, @command{packf} +@cindex exporting folders +@cindex folders, exporting +@cindex mbox-style folder + +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 @command{packf}. For +example, to create a file called @file{msgbox} with the messages in +your @samp{+inbox} folder, use @samp{packf +inbox}. The +@command{packf} command will append the messages to the file if it +already exists, so you can use @samp{folders -recurse -fast} in a +script to copy all of your messages into a single file, or using the +@samp{-file} argument, a file for each folder. + +@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 @ref{Using mh-e} and -@ref{Customizing mh-e} to find out how you can: +more. If you think that MH-E is for you, read the rest of the manual +to find out how you can: @itemize @bullet @item -Print your messages. (@ref{Printing} and @ref{Customizing Printing}.) +Print your messages (@ref{Printing}). +@c ------------------------- +@item +Edit messages and include your signature (@ref{Editing Drafts}). +@c ------------------------- @item -Edit messages and include your signature. (@ref{Draft Editing} -and @ref{Customizing Draft Editing}.) +Forward messages (@ref{Forwarding}). +@c ------------------------- +@item +Read digests (@ref{Digests}). +@c ------------------------- @item -Forward messages. (@ref{Forwarding} and @ref{Customizing Forwarding}.) +Edit bounced messages (@ref{Editing Again}). +@c ------------------------- +@item +Send multimedia messages (@ref{Adding Attachments}). +@c ------------------------- @item -Read digests. (@ref{Viewing}.) +Read HTML messages (@ref{HTML}). +@c ------------------------- @item -Edit bounced messages. (@ref{Old Drafts} and @ref{Customizing Old Drafts}.) +Use @ref{Aliases} and @ref{Identities}. +@c ------------------------- @item -Send multimedia messages. (@ref{Editing MIME} and @ref{Customizing Editing MIME}.) +Create different views of your mail (@ref{Threading} and @ref{Limits}). +@c ------------------------- +@item +Deal with junk mail (@ref{Junk}). +@c ------------------------- @item -Process mail that was sent with @code{shar} or @code{uuencode}. -(@ref{Files and Pipes}.) +Handle signed and encrypted messages (@ref{Reading PGP} and +@ref{Sending PGP}). +@c ------------------------- +@item +Process mail that was sent with @command{shar} or @command{uuencode} +(@ref{Files and Pipes}). +@c ------------------------- @item -Use sequences conveniently. (@ref{Sequences}.) +Use sequences conveniently (@ref{Sequences}). +@c ------------------------- @item -Show header fields in different fonts. (@ref{Customizing Viewing}.) +Use the @ref{Speedbar}, @ref{Tool Bar}, and @ref{Menu Bar}. +@c ------------------------- @item -Find previously refiled messages. (@ref{Searching}.) +Show header fields in different fonts (@ref{Reading Mail}). +@c ------------------------- @item -Place messages in a file. (@ref{Files and Pipes}.) +Find previously refiled messages (@ref{Searching}). +@c ------------------------- +@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 mh-e, Customizing mh-e, Tour Through mh-e, Top -@chapter Using mh-e - -This chapter leaves the tutorial style and goes into more detail about -every mh-e command. The default, or "out of the box," behavior is -documented. If this is not to your liking (for instance, you print with -something other than @code{lpr)}, see the associated section in -@ref{Customizing mh-e} which is organized exactly like this chapter. - -@cindex Emacs, functions; describe-mode +Remember that you can also use MH commands when you're not running +MH-E (and when you are!). + +@node Using This Manual, Incorporating Mail, Tour Through MH-E, Top +@chapter Using This Manual + +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 - -There are many commands, but don't get intimidated. There are command -summaries at the beginning of each section. 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 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}). In addition, review @ref{Conventions}, if any of the GNU Emacs -conventions are strange to you. - -Let's get started! +@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}. 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, 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}}. It is also available online at @* +@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You +can also 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{@xref{Top, The GNU Emacs Lisp Reference Manual, , elisp, GNU +Emacs Lisp Reference Manual}, which may be available online in the +Info system. It is also available online at +@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You +can also 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{The +@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/, +The GNU Emacs Lisp Reference Manual} may also be available online in +the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}. You can +also 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/mh-e}) 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. @menu -* Reading Mail:: -* Sending Mail:: -* Draft Editing:: -* Moving Mail:: -* Searching:: -* Sequences:: -* Miscellaneous:: +* Options:: +* Ranges:: +* Folder Selection:: @end menu -@node Reading Mail, Sending Mail, Using mh-e, Using mh-e -@section Reading Your Mail - -@cindex reading mail -@findex @code{mh-rmail} -@cindex MH-Folder mode -@cindex modes, MH-Folder - -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 old mail. @footnote{If you want to see your old mail as well, -use @kbd{M-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{M-f} (for example, @kbd{C-u M-x mh-rmail @key{RET} bob -@key{RET}}). Both @kbd{M-r} and @kbd{M-f} are described in -@ref{Organizing}.} 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-letter commands -discussed in this chapter. See @code{scan}(1) for a description of the -contents of the scan lines, and see the Figure in @ref{Reading Mail -Tour}, for an example. +@node Options, Ranges, Using This Manual, Using This Manual +@section Options + +@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} combo box 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} combo box 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{mh-mhl-format-file}, +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 +@findex mh-customize + +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. Another way to view the MH-E +customization group is to use @kbd{M-x mh-customize @key{RET}}. + +@node Ranges, Folder Selection, Options, Using This Manual +@section Ranges + +@c Sync with mh-folder-mode docstring. + +@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 valid 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. +@c ------------------------- +@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 predefined symbols: first, prev, cur, next or last. +@c ------------------------- +@item first:N +@itemx prev:N +@itemx next:N +@itemx last:N +The first, previous, next or last messages, if they exist. +@c ------------------------- +@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. + +@cindex @samp{mh-range} customization group +@cindex customization group, @samp{mh-range} + +The @samp{mh-range} customization group contains a single option which +affects how ranges are interpreted. + +@vtable @code +@item mh-interpret-number-as-range-flag +On means interpret a number as a range (default: @samp{on}). +@end vtable + +Since one of the most frequent ranges used is @samp{last:N}, MH-E will +interpret input such as @samp{200} as @samp{last:200} if the +@code{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 +@samp{200:1} or @samp{200-200}. + +@node Folder Selection, , Ranges, Using This Manual +@section Folder Selection + +@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/Completion.html, +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}). +@c ------------------------- +@item mh-default-folder-list +List of addresses and folders (default: @code{nil}). +@c ------------------------- +@item mh-default-folder-must-exist-flag +On means guessed folder name must exist to be used (default: +@samp{on}). +@c ------------------------- +@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. 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 +@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. +@c ------------------------- +@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, Using This Manual, Top +@chapter Incorporating Your Mail + +@cindex incorporating + +This chapter talks about getting mail from your system mailbox into +your MH @samp{+inbox} folder. The following command accomplishes that +and is found in the @samp{Folder} menu. @table @kbd -@item RET -Display a message (@code{mh-show}). - -@item SPC -Go to next page in message (@code{mh-page-msg}). - -@item BS -Go to previous page in message (@code{mh-previous-page}). - +@cindex @samp{Folder > Incorporate New Mail} menu item +@cindex menu item, @samp{Folder > Incorporate New Mail} +@findex mh-inc-folder +@kindex i +@item i +Incorporate new mail into a folder (@code{mh-inc-folder}). +@end table + +@cindex @samp{mh-inc} customization group +@cindex customization group, @samp{mh-inc} + +The following options in the @samp{mh-inc} customization group are +used. + +@vtable @code +@item mh-inc-prog +Program to incorporate mail (default: @samp{"inc"}). +@c ------------------------- +@item mh-inc-spool-list +Alternate spool files (default: @code{nil}). +@end vtable + +The following hook is available. + +@vtable @code +@item mh-inc-folder-hook +Hook run by @samp{mh-inc-folder} after incorporating mail into a +folder (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 as well as the destination folder (for +example, @kbd{C-u i ~/mbox @key{RET} +tmp @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 (@pxref{Getting Started}). 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 use the @code{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 @samp{+inbox}, and assign +key bindings to incorporate this mail. + +@cindex @command{procmail} +@cindex @file{.procmailrc} +@cindex Unix commands, @command{procmail} +@cindex files, @file{.procmailrc} + +Suppose you are subscribed to the @i{mh-e-devel} mailing list and you +use @command{procmail} to filter this mail into @file{~/mail/mh-e} +with the following recipe in @file{.procmailrc}: + +@smallexample +MAILDIR=$HOME/mail +:0: +* ^From mh-e-devel-admin@@stop.mail-abuse.org +mh-e +@end smallexample + +In order to incorporate @file{~/mail/mh-e} into @samp{+mh-e} with an +@kbd{I m} (@code{mh-inc-spool-mh-e}) command, customize this option, +and click on the @samp{INS} button. Enter a @samp{Spool File} of +@samp{~/mail/mh-e}, a @samp{Folder} of @samp{mh-e}, and a @samp{Key +Binding} of @samp{m}. + +@cindex @command{emacsclient} +@cindex @command{gnuclient} +@cindex @command{xbuffy} +@cindex @samp{gnuserv} +@cindex Unix commands, @command{emacsclient} +@cindex Unix commands, @command{gnuclient} +@cindex Unix commands, @command{xbuffy} + +You can use @command{xbuffy} to automate the incorporation of this +mail using the Emacs 22 command @command{emacsclient} as follows: + +@smallexample +box ~/mail/mh-e + title mh-e + origMode + polltime 10 + headertime 0 + command emacsclient --eval '(mh-inc-spool-mh-e)' +@end smallexample + +In XEmacs, the command @command{gnuclient} is used in a similar +fashion. + +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 + +@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 command @kbd{M-x mh-rmail} 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 or by using the @samp{Message} menu. +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 ? +@findex mh-help +@item ? +Display cheat sheet for the MH-E commands (@code{mh-help}). +@c ------------------------- +@cindex @samp{Message > Show Message} menu item +@cindex menu item, @samp{Message > Show Message} +@kindex @key{RET} +@findex mh-show +@item @key{RET} +Display message (@code{mh-show}). +@c ------------------------- +@cindex @samp{Message > Show Message with Header} menu item +@cindex menu item, @samp{Message > Show Message with Header} +@kindex , (comma) +@findex mh-header-display @item , (comma) -Display a message with all header fields (@code{mh-header-display}). - -@item M-SPC -Go to next message in digest (@code{mh-page-digest}). - -@item M-BS -Go to previous message in digest (@code{mh-page-digest-backwards}). - -@item M-b +Display message with all header fields (@code{mh-header-display}). +@c ------------------------- +@kindex ; (semicolon) +@findex mh-toggle-mh-decode-mime-flag +@item ; (semicolon) +Toggle the value of @code{mh-decode-mime-flag} +(@code{mh-toggle-mh-decode-mime-flag}). +@c ------------------------- +@kindex @key{SPC} +@findex mh-page-msg +@item @key{SPC} +Display next page in message (@code{mh-page-msg}). +@c ------------------------- +@kindex @key{BS} +@findex mh-previous-page +@item @key{BS} +Display previous page in message (@code{mh-previous-page}). +@c ------------------------- +@cindex @samp{Message > Write Message to File...} menu item +@cindex menu item, @samp{Message > Write Message to File...} +@kindex > +@findex mh-write-msg-to-file +@item > +Append message to end of file (@code{mh-write-msg-to-file}). +@c ------------------------- +@cindex @samp{Message > Pipe Message to Command...} menu item +@cindex menu item, @samp{Message > Pipe Message to Command...} +@kindex | +@findex mh-pipe-msg +@item | +Pipe message through shell command (@code{mh-pipe-msg}). +@c ------------------------- +@kindex C-d +@findex mh-delete-msg-no-motion +@item C-d +Delete range, don't move to next message +(@code{mh-delete-msg-no-motion}). +@c ------------------------- +@cindex @samp{Message > Delete Message} menu item +@cindex menu item, @samp{Message > Delete Message} +@kindex d +@findex mh-delete-msg +@item d +Delete range (@code{mh-delete-msg}). +@c ------------------------- +@kindex D ? +@findex mh-prefix-help +@item D ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@kindex D @key{SPC} +@findex mh-page-digest +@item D @key{SPC} +Display next message in digest (@code{mh-page-digest}). +@c ------------------------- +@kindex D @key{BS} +@findex mh-page-digest-backwards +@item D @key{BS} +Display previous message in digest (@code{mh-page-digest-backwards}). +@c ------------------------- +@cindex @samp{Message > Burst Digest Message} menu item +@cindex menu item, @samp{Message > Burst Digest Message} +@kindex D b +@findex mh-burst-digest +@item D b Break up digest into separate messages (@code{mh-burst-digest}). - +@c ------------------------- +@cindex @samp{Message > Go to Message by Number...} menu item +@cindex menu item, @samp{Message > Go to Message by Number...} +@kindex g +@findex mh-goto-msg +@item g +Go to a message (@code{mh-goto-msg}). +@c ------------------------- +@kindex k +@findex mh-delete-subject-or-thread +@item k +Delete messages with same subject or thread +(@code{mh-delete-subject-or-thread}). +@c ------------------------- +@kindex K ? +@findex mh-prefix-help +@item K ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@kindex K @key{TAB} +@findex mh-next-button +@item K @key{TAB} +Go to the next button (@code{mh-next-button}). +@c ------------------------- +@kindex K S-@key{TAB} +@findex mh-prev-button +@item K S-@key{TAB} +Go to the previous button (@code{mh-prev-button}). +@c ------------------------- +@kindex K a +@findex mh-mime-save-parts +@item K a +Save attachments (@code{mh-mime-save-parts}). +@c ------------------------- +@kindex K e +@findex mh-display-with-external-viewer +@item K e +View attachment externally (@code{mh-display-with-external-viewer}). +@c ------------------------- +@kindex K i +@findex mh-folder-inline-mime-part +@item K i +Show attachment verbatim (@code{mh-folder-inline-mime-part}). +@c ------------------------- +@kindex K o +@findex mh-folder-save-mime-part +@item K o +Save (output) attachment (@code{mh-folder-save-mime-part}). +@c ------------------------- +@kindex K t +@findex mh-toggle-mime-buttons +@item K t +Toggle option @code{mh-display-buttons-for-inline-parts-flag} +(@code{mh-toggle-mime-buttons}). +@c ------------------------- +@kindex K v +@findex mh-folder-toggle-mime-part +@item K v +View attachment (@code{mh-folder-toggle-mime-part}). +@c ------------------------- +@cindex @samp{Message > Modify Message} menu item +@cindex menu item, @samp{Message > Modify Message} +@kindex M +@findex mh-modify +@item M +Edit message (@code{mh-modify}). +@c ------------------------- +@cindex @samp{Message > Go to First Message} menu item +@cindex menu item, @samp{Message > Go to First Message} +@kindex M-< +@findex mh-first-msg +@item M-< +Display first message (@code{mh-first-msg}). +@c ------------------------- +@cindex @samp{Message > Go to Last Message} menu item +@cindex menu item, @samp{Message > Go to Last Message} +@kindex M-> +@findex mh-last-msg +@item M-> +Display last message (@code{mh-last-msg}). +@c ------------------------- +@kindex M-n +@findex mh-next-unread-msg +@item M-n +Display next unread message (@code{mh-next-unread-msg}). +@c ------------------------- +@kindex M-p +@findex mh-previous-unread-msg +@item M-p +Display previous unread message (@code{mh-previous-unread-msg}). +@c ------------------------- +@cindex @samp{Message > Next Message} menu item +@cindex menu item, @samp{Message > Next Message} +@kindex n +@findex mh-next-undeleted-msg @item n Display next message (@code{mh-next-undeleted-msg}). - +@c ------------------------- +@cindex @samp{Message > Previous Message} menu item +@cindex menu item, @samp{Message > Previous Message} +@kindex p +@findex mh-previous-undeleted-msg @item p Display previous message (@code{mh-previous-undeleted-msg}). - -@item g -Go to a message (@code{mh-goto-msg}). - -@item M-< -Go to first message (@code{mh-first-msg}). - -@item M-> -Go to last message (@code{mh-last-msg}). - -@item t -Toggle between MH-Folder and MH-Folder Show modes (@code{mh-toggle-showing}). +@c ------------------------- +@kindex P ? +@findex mh-prefix-help +@item P ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@kindex P C +@findex mh-ps-print-toggle-color +@item P C +Toggle whether color is used in printing messages +(@code{mh-ps-print-toggle-color}). +@c ------------------------- +@kindex P F +@findex mh-ps-print-toggle-faces +@item P F +Toggle whether printing is done with faces or not +(@code{mh-ps-print-toggle-faces}). +@c ------------------------- +@kindex P f +@findex mh-ps-print-msg-file +@item P f +Print range to file (@code{mh-ps-print-msg-file}). +@c ------------------------- +@cindex @samp{Message > Print Message} menu item +@cindex menu item, @samp{Message > Print Message} +@kindex P l +@findex mh-print-msg +@item P l +Print range the old fashioned way +(@code{mh-print-msg}). +@c ------------------------- +@kindex P p +@findex mh-ps-print-msg +@item P p +Print range (@code{mh-ps-print-msg}). +@c ------------------------- +@kindex X ? +@findex mh-prefix-help +@item X ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@cindex @samp{Message > Unpack Uuencoded Message...} menu item +@cindex menu item, @samp{Message > Unpack Uuencoded Message...} +@kindex X s +@kindex X u +@findex mh-store-msg +@item X s +@itemx X u +Unpack message created with @command{uudecode} or @command{shar} +(@code{mh-store-msg}). +@c ------------------------- +@kindex Mouse-2 +@findex mh-show-mouse +@item Mouse-2 +Move point to mouse event and show message (@code{mh-show-mouse}). +@end table + +Within the MH-Show buffer, the following command is defined. + +@table @kbd +@kindex @key{RET} +@kindex Mouse-1 +@kindex Mouse-2 +@findex mh-press-button +@item @key{RET} +@itemx Mouse-1 +@itemx Mouse-2 +View contents of button (@code{mh-press-button}). @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 +On means show buffer is buried (default: @samp{on}). +@c ------------------------- +@item mh-clean-message-header-flag +On means remove extraneous header fields (default: @samp{on}). +@c ------------------------- +@item mh-decode-mime-flag +On means attachments are handled (default: @samp{on} if the Gnus +@samp{mm-decode} package is present). +@c ------------------------- +@item mh-display-buttons-for-alternatives-flag +On means display buttons for all alternative attachments (default: +@samp{off}). +@c ------------------------- +@item mh-display-buttons-for-inline-parts-flag +On means display buttons for all inline attachments (default: +@samp{off}). +@c ------------------------- +@item mh-do-not-confirm-flag +On means non-reversible commands do not prompt for confirmation +(default: @samp{off}). +@c ------------------------- +@item mh-fetch-x-image-url +Control fetching of @samp{X-Image-URL:} header field image (default: +@code{Never Fetch}). +@c ------------------------- +@item mh-graphical-smileys-flag +On means graphical smileys are displayed (default: @samp{on}). +@c ------------------------- +@item mh-graphical-emphasis-flag +On means graphical emphasis is displayed (default: @samp{on}). +@c ------------------------- +@item mh-highlight-citation-style +Style for highlighting citations (default: @samp{Multicolor}). +@c ------------------------- +@item mh-invisible-header-fields-default +List of hidden header fields (default: a checklist too long to list +here). +@c ------------------------- +@item mh-invisible-header-fields +Additional header fields to hide (default: @code{nil}). +@c ------------------------- +@item mh-lpr-command-format +Command used to print (default: @samp{"lpr -J '%s'"}). +@c ------------------------- +@item mh-max-inline-image-height +Maximum inline image height if \"Content-Disposition:\" is not +present (default: 0). +@c ------------------------- +@item mh-max-inline-image-width +Maximum inline image width if \"Content-Disposition:\" is not +present(default: 0). +@c ------------------------- +@item mh-mhl-format-file +Specifies the format file to pass to the @command{mhl} program +(default: @samp{Use Default mhl Format (Printing Only)}). +@c ------------------------- +@item mh-mime-save-parts-default-directory +Default directory to use for @kbd{K a}. +@c ------------------------- +@item mh-print-background-flag +On means messages should be printed in the background (default: +@samp{off}). +@c ------------------------- +@item mh-show-maximum-size +Maximum size of message (in bytes) to display automatically (default: +0). +@c ------------------------- +@item mh-show-use-xface-flag +On means display face images in MH-Show buffers (default: @code{on}). +@c ------------------------- +@item mh-store-default-directory +Default directory for @kbd{X s} (default: @samp{Current}). +@c ------------------------- +@item mh-summary-height +Number of lines in MH-Folder buffer (including the mode line) +(default: depends on size of frame). +@end vtable + +The following hooks are available. + +@vtable @code +@item mh-delete-msg-hook +Hook run after marking each message for deletion (default: @code{nil}). +@c ------------------------- +@item mh-show-hook +Hook run after @key{RET} shows a message (default: @code{nil}). +@c ------------------------- +@item mh-show-mode-hook +Hook run upon entry to @code{mh-show-mode} (default: @code{nil}). +@end vtable + +The following faces are available. + +@vtable @code +@item mh-show-cc +Face used to highlight @samp{cc:} header fields. +@c ------------------------- +@item mh-show-date +Face used to highlight @samp{Date:} header fields. +@c ------------------------- +@item mh-show-from +Face used to highlight @samp{From:} header fields. +@c ------------------------- +@item mh-show-header +Face used to deemphasize less interesting header fields. +@c ------------------------- +@item mh-show-pgg-bad +Bad PGG signature face. +@c ------------------------- +@item mh-show-pgg-good +Good PGG signature face. +@c ------------------------- +@item mh-show-pgg-unknown +Unknown or untrusted PGG signature face. +@c ------------------------- +@item mh-show-signature +Signature face. +@c ------------------------- +@item mh-show-subject +Face used to highlight @samp{Subject:} header fields. +@c ------------------------- +@item mh-show-to +Face used to highlight @samp{To:} header fields. +@c ------------------------- +@item mh-show-xface +X-Face image face. +@end vtable + +The functions and variables introduced here are explained in more +detail in the following sections. + @menu -* Viewing:: -* Moving Around:: +* Viewing:: +* Viewing Attachments:: +* HTML:: +* Digests:: +* Reading PGP:: +* Printing:: +* Files and Pipes:: +* Navigating:: +* Miscellaneous Commands and Options:: @end menu -@node Viewing, Moving Around, Reading Mail, Reading Mail -@subsection Viewing Your Mail - -@findex @code{mh-show} -@findex @code{mh-page-msg} -@findex @code{mh-previous-page} -@findex @code{mh-header-display} - -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. - -@menu -* Reading Digests:: -* Reading MIME:: -@end menu - -@node Reading Digests, Reading MIME, Viewing, Viewing -@subsubsection Reading Digests +@node Viewing, Viewing Attachments, Reading Mail, Reading Mail +@section Viewing Your Mail + +@findex mh-header-display +@findex mh-page-msg +@findex mh-previous-page +@findex mh-show +@findex mh-show-mouse +@kindex , (comma) +@kindex . (period) +@kindex @key{BS} +@kindex @key{RET} +@kindex @key{SPC} +@kindex Mouse-2 + +The command @key{RET} (@code{mh-show}) displays the message that the +cursor is on while @kbd{Mouse-2} (@code{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 @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 @key{SPC}}). The @key{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 @kbd{,} (comma; +@code{mh-header-display}). + +The option @code{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. + +@vindex mh-show-cc +@vindex mh-show-date +@vindex mh-show-from +@vindex mh-show-header +@vindex mh-show-subject +@vindex mh-show-to + +First, the appearance of the header fields can be modified by +customizing the associated face: @code{mh-show-to}, @code{mh-show-cc}, +@code{mh-show-from}, @code{mh-show-date}, and @code{mh-show-subject}. +The face @code{mh-show-header} is used to deemphasize the other, less +interesting, header fields. + +@cindex regular expressions, @code{mh-invisible-header-fields} +@vindex mh-clean-message-header-flag +@vindex mh-invisible-header-fields-default +@vindex mh-invisible-header-fields + +Normally messages are delivered with a handful of uninteresting header +fields. These are hidden by turning on the option +@code{mh-clean-message-header-flag} (which it is by default). The +header fields listed in the option +@code{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 +@code{mh-invisible-header-fields} 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 a +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:} +@vindex mh-show-use-xface-flag + +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. 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. + +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/}.}. + +@cindex @command{uncompface} +@cindex Emacs, packages, x-face +@cindex Unix commands, @command{uncompface} +@cindex x-face package +@vindex mh-show-xface + +Next is the traditional @samp{X-Face:} header field@footnote{The +display of this field requires the +@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, +@command{uncompface} program}. 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 +@uref{ftp://ftp.jpl.org/pub/elisp/, @samp{x-face} package}.}. MH-E +renders the foreground and background of the image using the +associated attributes of the face @code{mh-show-xface}. + +@cindex @command{convert} +@cindex @command{wget} +@cindex ImageMagick +@cindex Unix commands, @command{convert} +@cindex Unix commands, @command{wget} +@vindex mh-fetch-x-image-url + +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 @uref{http://www.gnu.org/software/wget/wget.html, +@command{wget} program} to fetch the image and the @command{convert} +program from the @uref{http://www.imagemagick.org/, ImageMagick +suite}.}. 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 @code{mh-fetch-x-image-url} +controls the fetching of the @samp{X-Image-URL:} header field image +with the following 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. +@c ------------------------- +@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 (which is why you shouldn't blindly answer +yes if you've set this option to @samp{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. + +@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. @xref{Picture}. + +@cindex @command{mhl} +@cindex MH commands, @command{mhl} +@vindex mh-mhl-format-file + +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), change the option +@code{mh-mhl-format-file} from its default value of @samp{Use Default +mhl Format (Printing Only)}. You can set this option to @samp{Use +Default mhl Format} to get the same output as you would get if you ran +@command{mhl} from the shell. If you have a format file that you want +MH-E to use, you can set this option to @samp{Specify an mhl Format +File} and enter the name of your 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). Your format file should +specify a non-zero value for @samp{overflowoffset} to allow MH-E to +parse the header. Note that @command{mhl} is always used for printing +and forwarding; in this case, the value of @code{mh-mhl-format-file} +is consulted if you have specified a format file. + +@vindex mh-highlight-citation-style +@cindex citations, highlighting +@cindex highlighting citations + +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 @code{mh-highlight-citation-style} can be +customized to change the highlighting style. The @samp{Multicolor} +method uses a different color for each indentation while the +@samp{Monotone} method highlights all citations in red. To disable +highlighting of citations entirely, choose @samp{None}. + +@cindex URLs, highlighting +@cindex email addresses, highlighting +@cindex highlighting URLs +@cindex highlighting email addresses +@cindex links, following +@findex goto-address-at-point +@kindex C-c @key{RET} +@kindex Mouse-2 +@vindex goto-address-highlight-p + +Email addresses and URLs in the message are highlighted if the option +@code{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 @kbd{Mouse-2} or @kbd{C-c @key{RET}}. +See @ref{Sending Mail}, to see how to configure Emacs to send the +message using MH-E. + +@cindex boldface, showing +@cindex emphasis +@cindex italics, showing +@cindex smileys +@cindex typesetting +@cindex underline, showing +@vindex gnus-emphasis-alist +@vindex mh-decode-mime-flag +@vindex mh-graphical-emphasis-flag +@vindex mh-graphical-smileys-flag + +It is a long standing custom to inject body language using a +cornucopia of punctuation, also known as the @dfn{smileys}. MH-E can +render these as graphical widgets if the option +@code{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 +@code{mh-graphical-emphasis-flag} is turned on, which it is by +default. For example, _underline_ will be +@ifhtml +@html +<u>underlined</u>, +@end html +@end ifhtml +@ifnothtml +underlined, +@end ifnothtml +*bold* will appear in @b{bold}, /italics/ will appear in @i{italics}, +and so on. See the option @code{gnus-emphasis-alist} for the whole +list. Both of these options are disabled if the option +@code{mh-decode-mime-flag} is turned off. @xref{Viewing Attachments}. + +@cindex signature separator +@cindex vCard +@vindex mh-show-signature + +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. You can also +customize the face @code{mh-show-signature} so the appearance of the +signature block is more to your liking. + +@vindex mh-show-hook +@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 +the message display. It is usually used to perform some action on the +message's content. 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 attachments +@cindex body parts +@cindex multimedia mail + +MH has the ability to display @dfn{@sc{mime}} (Multipurpose Internet +Mail Extensions) messages which are simply messages with additional +@dfn{body parts} or @dfn{attachments}. You can 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}.}. + +@cindex Emacs, packages, mm-decode +@cindex mm-decode package +@findex mh-toggle-mh-decode-mime-flag +@kindex ; (semicolon) +@vindex mh-decode-mime-flag + +MH-E can handle attachments as well if the Gnus @samp{mm-decode} +package is present. If so, the option @code{mh-decode-mime-flag} will +be on. Otherwise, you'll see the @sc{mime} body parts rather than text +or attachments. There isn't much point in turning off the option +@code{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 @kbd{;} (semicolon; +@code{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. @xref{Viewing}. + +@cindex buttons +@kindex Mouse-1 +@kindex Mouse-2 +@kindex @key{RET} +@findex mh-press-button +@findex mh-next-button +@findex mh-prev-button +@kindex K @key{TAB} +@kindex K S-@key{TAB} + +Attachments in MH-E are indicated by buttons like this: + +@example +[1. image/jpeg; foo.jpg]... +@end example + +To view the contents of the button, use either @kbd{Mouse-1} or +@kbd{Mouse-2} on the button or @key{RET} (@code{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 @kbd{K @key{TAB}} (@code{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 +@kbd{K S-@key{TAB}} (@code{mh-prev-button}). If the beginning of the +buffer is reached then the search wraps over to the end of the buffer. + +@cindex attachments, viewing +@cindex viewing attachments +@findex mh-folder-toggle-mime-part +@kindex K v + +Another way to view the contents of a button is to use the command +@kbd{K v} (@code{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 @kbd{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. + +@cindex @file{/etc/mailcap} +@cindex files, @file{/etc/mailcap} +@findex mailcap-mime-info +@findex mh-display-with-external-viewer +@kindex K e + +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 +@kbd{K e} (@code{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 @kbd{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 +@code{mailcap-mime-info}. This function usually reads the file +@file{/etc/mailcap}. + +@cindex attachments, saving +@cindex saving attachments + +@findex mh-folder-save-mime-part +@kindex K o + +Use the command @kbd{K o} (@code{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 @kbd{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. + +@cindex @command{mhn} +@cindex @command{mhstore} +@cindex MH commands, @command{mhn} +@cindex MH commands, @command{mhstore} +@findex mh-mime-save-parts +@kindex K a +@vindex mh-mime-save-parts-default-directory + +You can save all of the attachments at once with the command @kbd{K a} +(@code{mh-mime-save-parts}). The attachments are saved in the +directory specified by the option +@code{mh-mime-save-parts-default-directory} unless you use a prefix +argument (as in @kbd{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 @command{mhstore} +(@command{mhn}) to do the work. + +The default value for the option +@code{mh-mime-save-parts-default-directory} is @samp{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 @samp{Prompt the First Time} +to avoid the prompt each time. you can make this directory permanent +by choosing @samp{Directory} and entering the directory's name. + +@cindex attachments, inline +@cindex inline attachments +@findex mh-toggle-mime-buttons +@kindex K t +@vindex mh-display-buttons-for-inline-parts-flag + +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 @kbd{K t} (@code{mh-toggle-mime-buttons}) to toggle +the visibility of these buttons. You can turn on these buttons +permanently by turning on the option +@code{mh-display-buttons-for-inline-parts-flag}. + +MH-E cannot display all attachments inline however. It can display +text (including @sc{html}) and images. + +@cindex @samp{Content-Disposition:} header field +@cindex header field, @samp{Content-Disposition:} +@cindex inline images +@vindex mh-max-inline-image-height +@vindex mh-max-inline-image-width + +Some older mail programs do not insert the needed +plumbing@footnote{This plumbing is the @samp{Content-Disposition:} +header field.} 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 @code{mh-max-inline-image-width} and +@code{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. + +@cindex alternatives +@cindex attachments, alternatives +@vindex mh-display-buttons-for-alternatives-flag + +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 @code{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. + +@kindex K i +@findex mh-folder-inline-mime-part + +You can view the raw contents of an attachment with the command @kbd{K +i} (@code{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 @kbd{4 K i}) to view the attachment labeled with that +number. + +For additional information on buttons, see +@ifinfo +@ref{Article Buttons,,,gnus}, and @ref{MIME Commands,,,gnus}. +@end ifinfo +@ifnotinfo +the chapters @uref{http://www.gnus.org/manual/gnus_101.html#SEC101, +Article Buttons} and +@uref{http://www.gnus.org/manual/gnus_108.html#SEC108, MIME Commands} +in the @cite{The Gnus Manual}. +@end ifnotinfo + +@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 a version of Gnus that is at least 5.10.}. 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: + +@example +[1. text/html; foo.html]... +@end example + +See @ref{Viewing Attachments} to see how to read the contents of this +body part. + +The browser that MH-E uses is determined by the option +@code{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 @code{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. + +@table @asis + +@item @samp{w3m} 7 +The @samp{w3m} browser requires an external program. It's quick, +produces pretty nice output, and best of all, it's the only browser +that highlights links. These can be clicked with @kbd{Mouse-2} to view +the content of the link in @samp{w3m} or with @kbd{S-Mouse-2} to view +the content of the link in an external browser. The @samp{w3m} browser +handles tables well and actually respects the table's width parameter +(which can cause text to wrap if the author didn't anticipate that the +page would be viewed in Emacs). +@c ------------------------- +@item @samp{w3m-standalone} 3 +This browser, along with @samp{nil} for the external browser, are the +only choices that work without having to download a separate lisp +package or external program. This browser is quick, but does not show +links. It handles simple tables but some tables get rendered much +wider than the Emacs frame. This browser was the only one not to +handle the escape @samp{–} (it printed a @samp{?}), but it did +render @samp{®}. +@c ------------------------- +@item @samp{links} 1 +The @samp{links} browser requires an external program. It's quick, and +produces nicer output than @samp{lynx} on single column mails in +tables. However, it doesn't show links and it doesn't do as nice a job +on multi-column tables as some lines wrap. At least it fits in 80 +columns and thus seems better than @samp{w3} and +@samp{w3m-standalone}. Converts escapes such as @samp{®} to (R). +@c ------------------------- +@item @samp{lynx} 1 +The @samp{lynx} browser requires an external program. It's quick and +produces pretty decent output but it doesn't show links. It doesn't +seem to do multi-column tables which makes output much cleaner. It +centers the output and wraps long lines more than most. Handles +@samp{®}. +@c ------------------------- +@item @samp{nil} 1 +This choice obviously requires an external browser. Like +@samp{w3m-standalone}, it works out of the box. With this setting, +HTML messages have a button for the body part which you can view with +@kbd{K v} (@code{mh-folder-toggle-mime-part}). +@c ------------------------- +@item @samp{w3} 0 +This choice does not require an external program as all of the +rendering is done in lisp. You do need to get the package separately. +This browser is @strong{slow}, and doesn't appear to have been updated +since 2001 and the author hasn't responded to my emails. It displays +unknown tags instead of hiding them, so you get to see all the +Microsoft crap in certain messages. Tends to make multi-column tables +wider than even a full-screen Emacs can handle. Like @samp{w3m}, you +can follow links, but you have to find them first as they are not +highlighted. Performs well on single-column tables and handles escapes +such as @samp{®}. +@c ------------------------- +@item @samp{html2text} 0 +The @samp{html2text} browser requires an external program. I noticed +that it can do some nasty things with simple HTML mails (like filling +the entire message as if it were one paragraph, including signature). +On another message, it displayed half of the HTML tags for some +reason. +@end table + +For a couple more sources of information about +@code{mm-text-html-renderer}, +@ifinfo +@xref{Display Customization,,,emacs-mime}, and the documentation for +the Gnus command @kbd{W h} (@pxref{Article Washing,,,gnus},). +@end ifinfo +@ifnotinfo +see section @uref{http://www.gnus.org/manual/emacs-mime_6.html, +Display Customization} in the @cite{The Emacs MIME Manual} and the the +documentation for the Gnus command @kbd{W h} (see section +@uref{http://www.gnus.org/manual/gnus_99.html, Article Washing} in the +@cite{The Gnus Manual}). +@end ifnotinfo + +@node Digests, Reading PGP, HTML, Reading Mail +@section Digests @cindex digests -@findex @code{mh-page-digest} -@findex @code{mh-page-digest-backwards} - -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{M-SPC} -(@code{mh-page-digest}). To return to a previous message, use -@kbd{M-BS} (@code{mh-page-digest-backwards}). - -@cindex @code{burst} -@cindex MH commands, @code{burst} +@findex mh-page-digest +@findex mh-page-digest-backwards +@kindex @key{BS} +@kindex @key{SPC} +@kindex D @key{BS} +@kindex D @key{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 @key{SPC}} (@code{mh-page-digest}). To return to a previous message, +use @kbd{D @key{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 @code{mh-burst-digest} - -@c There was a page break at the colon in the following paragraph which -@c broke the transition to the example. -@need 2000 - -Another handy command is @kbd{M-b} (@code{mh-burst-digest}). This -command uses the MH command @code{burst} 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{Moving Around}) so that -the scan lines fill the screen and messages aren't displayed. Then use -@kbd{d} (@pxref{Deleting}) 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 in @ref{Editing -Textual}. - -@node Reading MIME, , Reading Digests, Viewing -@subsubsection Reading Multimedia Mail - -@cindex multimedia mail -@cindex MIME -@cindex @code{show} -@cindex MH commands, @code{show} -@cindex @code{mhshow} -@cindex MH commands, @code{mhshow} - -MH has the ability to read @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 @code{show} or @code{mhshow} -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 @code{xterm --e} if you use @code{mhlist} or @code{mhstore}.} - -@node Moving Around, , Viewing, Reading Mail -@subsection Moving Around +@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 key server +@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 key server 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: + +@smallexample +@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 smallexample + +@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: + +@smallexample +@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 smallexample + +If there is a problem decrypting the message, the button will say: + +@smallexample +[[PGP Encrypted Part:Failed]] +@end smallexample + +You can read the contents of this button using the methods described in +@ref{Viewing Attachments}. If the message were corrupted, you'd see +this: + +@smallexample +[[PGP Encrypted Part:Failed] +Invalid base64 data] +@end smallexample + +If your passphrase were incorrect, you'd see something like this: + +@smallexample +[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 smallexample + +@vindex mh-show-pgg-bad +@vindex mh-show-pgg-good +@vindex mh-show-pgg-unknown + +The appearance of the buttons is controlled by the faces +@code{mh-show-pgg-good}, @code{mh-show-pgg-bad}, and +@code{mh-show-pgg-unknown} depending on the validity of the signature. +The latter is used whether the signature is unknown or untrusted. + +@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 printing +@findex mh-ps-print-msg +@findex mh-ps-print-msg-file +@kindex P f +@kindex P p + +To print messages in MH-E, use the command @kbd{P p} +(@code{mh-ps-print-msg}). You can print all the messages in a range +(as in @kbd{C-u P p 1 3 5-7 last:5 frombob @key{RET}}, +@pxref{Ranges}). You can also send the output to a file with @kbd{P f} +(@code{mh-ps-print-msg-file}). This command will print inline text +attachments but will not decrypt messages. However, when a message is +displayed in an MH-Show buffer, then that buffer is used verbatim for +printing with the caveat that only text attachments, if opened inline, +are printed. Therefore, encrypted messages can be printed by showing +and decrypting them first. The commands @kbd{P p} and @kbd{P f} do not +use the options @code{mh-lpr-command-format} or +@code{mh-print-background-flag}, described below. + +@findex mh-ps-print-toggle-color +@kindex P C +@vindex ps-print-color-p + +Colors are emulated on black-and-white printers with shades of gray. +This might produce illegible output, even if your screen colors only +use shades of gray. If this is the case, try using the command @kbd{P +C} (@code{mh-ps-print-toggle-color}) to toggle between color, no +color, and a black and white representation of the colors and see +which works best. You change this setting permanently by customizing +the option @code{ps-print-color-p}. + +@findex mh-ps-print-toggle-faces +@kindex P F + +Another related function is the command @kbd{P F} +(@code{mh-ps-print-toggle-faces}). This command toggles between using +faces and not. When faces are enabled, the printed message will look +very similar to the message in the MH-Show buffer. + +@cindex ps-print package +@cindex Emacs, packages, ps-print + +MH-E uses the @samp{ps-print} package to do the printing, so you can +customize the printing further by going to the @samp{ps-print} +customization group. + +@cindex @command{lpr} +@cindex @command{mhl} +@cindex MH commands, @command{mhl} +@cindex Unix commands, @command{lpr} +@findex mh-print-msg +@kindex P l + +An alternative to using the @samp{ps-print} package is the command +@kbd{P l} (@code{mh-print-msg}) (the @i{l} is for @i{l}ine printer or +@i{l}pr). You can print all the messages in a range. 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. + +@vindex mh-lpr-command-format +@vindex mh-print-background-flag + +The command @kbd{P l} uses two options. The option +@code{mh-lpr-command-format} contains the Unix command line which +performs the actual printing. The string can contain one escape, +@samp{%s}, which is replaced by the name of the folder and the message +number and is useful for print job names. The default setting is +@samp{"lpr -J '%s'"}. I use @samp{"mpage -h'%s' -b Letter -H1of -mlrtb +-P"} which produces a nice header and adds a bit of margin so the text +fits within my printer's margins. Normally messages are printed in the +foreground. If this is slow on your system, you may elect to turn on +the option @code{mh-print-background-flag} 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. These options are not used by the +commands @kbd{P p} or @kbd{P f}. + +@node Files and Pipes, Navigating, Printing, Reading Mail +@section Files and Pipes + +@cindex files +@cindex pipes + +@findex mh-refile-or-write-again +@findex mh-write-msg-to-file +@kindex ! +@kindex > + +MH-E does offer a couple of commands that are not a part of MH@. The +first one, @kbd{>} (@code{mh-write-msg-to-file}), writes a message to +a file. 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 > /tmp/foobar @key{RET}}). Subsequent writes to the same file +can be made with the command @kbd{!} +(@code{mh-refile-or-write-again}). + +@findex mh-pipe-msg +@kindex | + +You can also pipe the message through a Unix shell command with the +command @kbd{|} (@code{mh-pipe-msg}). You are prompted for the Unix +command through which you wish to run your message. If you give a +prefix 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 +@vindex mh-store-default-directory + +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; however, 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. If you would +like to change the initial default directory, customize the option +@code{mh-store-default-directory}, change the value from +@samp{Current} to @samp{Directory}, and then enter the name of the +directory for storing the content of these messages. + +@findex mh-store-buffer + +By the way, @kbd{X s} 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, Miscellaneous Commands and Options, Files and Pipes, Reading Mail +@section Navigating @cindex moving between messages -@findex @code{mh-next-undeleted-msg} -@findex @code{mh-previous-undeleted-msg} -@findex @code{mh-goto-msg} -@findex @code{mh-last-msg} -@findex @code{mh-first-msg} - -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 +@cindex navigation +@findex mh-first-msg +@findex mh-goto-msg +@findex mh-last-msg +@findex mh-next-undeleted-msg +@findex mh-next-unread-msg +@findex mh-previous-undeleted-msg +@findex mh-previous-unread-msg +@kindex M-< +@kindex M-> +@kindex M-n +@kindex M-p +@kindex g +@kindex n +@kindex p + +To move on to the next message, use the command @kbd{n} +(@code{mh-next-undeleted-msg}); use @kbd{p} +(@code{mh-previous-undeleted-msg}) to read the previous message. To +move to the next unread message, use @kbd{M-n} +(@code{mh-next-unread-msg}); use @kbd{M-p} +(@code{mh-previous-unread-msg}) to move to the previous unread +message. 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 - -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 -@kbd{RET} to look at deleted or refiled messages. +@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 command @kbd{d} +(@code{mh-delete-msg}). 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. +You may also specify a range (for example, @kbd{C-u d 1 3 5-7 last:5 +frombob @key{RET}}, @pxref{Ranges}). + +@findex mh-delete-msg-no-motion +@kindex C-d + +The command @kbd{C-d} (@code{mh-delete-msg-no-motion}) marks the +message (or messages in range) for deletion but leaves the cursor at +the current message in case you wish to perform other operations on +the message. + +@findex mh-delete-subject +@findex mh-delete-subject-or-thread +@kindex k + +And to delete more messages faster, you can use @kbd{k} +(@code{mh-delete-subject-or-thread}) to delete all the messages with +the same subject as the current message. This command puts these +messages in a sequence named @samp{subject}. You can undo this action +by using @kbd{u} (@code{mh-undo}) with a prefix argument and then +specifying the @samp{subject} sequence. However, if the buffer is +displaying a threaded view of the folder then @kbd{k} behaves like +@kbd{T d} (@code{mh-thread-delete}). @xref{Threading}. + +@findex mh-execute-commands +@kindex x + +However you mark a message for deletion, the command @kbd{x} +(@code{mh-execute-commands}) actually carries out the deletion +(@pxref{Folders}). + +@vindex mh-delete-msg-hook + +The hook @code{mh-delete-msg-hook} is called after you mark a message +for deletion. For example, a past maintainer of MH-E used this once +when he kept statistics on his mail usage. + +@node Miscellaneous Commands and Options, , Navigating, Reading Mail +@section Miscellaneous Commands and Options + +This section contains a few more miscellaneous commands and options. + +@cindex editing message +@findex mh-modify +@kindex M + +There are times when you need to edit a message. For example, you may +need to fix a broken Content-Type header field. You can do this with +the command @kbd{M} (@code{mh-modify}). It displays the raw message in +an editable buffer. When you are done editing, save and kill the +buffer as you would any other. + +@vindex mh-do-not-confirm-flag + +Commands such as @code{mh-pack-folder} prompt to confirm whether to +process outstanding moves and deletes or not before continuing. +Turning on the option @code{mh-do-not-confirm-flag} means that these +actions will be performed---which is usually desired but cannot be +retracted---without question@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} was modified in version 6.0 to always ask for +confirmation subject to @code{mh-kill-folder-suppress-prompt-hook}. +@xref{Folders}.}. @cindex MH-Folder mode @cindex modes, MH-Folder +@vindex mh-summary-height + +The option @code{mh-summary-height} controls the number of scan lines +displayed in the MH-Folder window, including the mode line. The +default value of this option is @samp{Automatic} which means that the +MH-Folder buffer will maintain the same proportional size if the frame +is resized. If you'd prefer a fixed height, then choose the +@samp{Fixed Size} option and enter the number of lines you'd like to +see. + +@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 turning off +the option @code{mh-bury-show-buffer-flag}. 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. + +@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 @key{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 Folders, Sending Mail, Reading Mail, Top +@chapter Organizing Your Mail with Folders + +@cindex folders +@cindex using folders + +This chapter discusses the things you can do with folders within MH-E. +The commands in this chapter are also found in the @samp{Folder} and +@samp{Message} menus. + +@table @kbd +@kindex ? +@findex mh-help +@item ? +Display cheat sheet for the MH-E commands (@code{mh-help}). +@c ------------------------- +@kindex ! +@findex mh-refile-or-write-again +@item ! +Repeat last output command (@code{mh-refile-or-write-again}). +@c ------------------------- +@cindex @samp{Message > Copy Message to Folder...} menu item +@cindex menu item, @samp{Message > Copy Message to Folder...} +@kindex c +@findex mh-copy-msg +@item c +Copy range to folder (@code{mh-copy-msg}). +@c ------------------------- +@kindex F ? +@findex mh-prefix-help +@item F ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@kindex F ' +@findex mh-index-ticked-messages +@item F ' +Display ticked messages (@code{mh-index-ticked-messages}). +@c ------------------------- +@kindex F c +@findex mh-catchup +@item F c +Delete range from the @samp{unseen} sequence (@code{mh-catchup}). +@c ------------------------- +@kindex F k +@findex mh-kill-folder +@item F k +Remove folder (@code{mh-kill-folder}). +@c ------------------------- +@cindex @samp{Folder > List Folders} menu item +@cindex menu item, @samp{Folder > List Folders} +@kindex F l +@findex mh-list-folders +@item F l +List all folders (@code{mh-list-folders}). +@c ------------------------- +@cindex @samp{Folder > View New Messages} menu item +@cindex menu item, @samp{Folder > View New Messages} +@kindex F n +@findex mh-index-new-messages +@item F n +Display unseen messages (@code{mh-index-new-messages}). +@c ------------------------- +@cindex @samp{Folder > Pack Folder} menu item +@cindex menu item, @samp{Folder > Pack Folder} +@kindex F p +@findex mh-pack-folder +@item F p +Pack folder (@code{mh-pack-folder}). +@c ------------------------- +@kindex F q +@findex mh-index-sequenced-messages +@item F q +Display messages in any sequence (@code{mh-index-sequenced-messages}). +@c ------------------------- +@cindex @samp{Folder > Rescan Folder} menu item +@cindex menu item, @samp{Folder > Rescan Folder} +@kindex F r +@findex mh-rescan-folder +@item F r +Rescan folder (@code{mh-rescan-folder}). +@c ------------------------- +@cindex @samp{Folder > Search...} menu item +@cindex menu item, @samp{Folder > Search...} +@kindex F s +@findex mh-search +@item F s +Search your MH mail (@code{mh-search}). +@c ------------------------- +@cindex @samp{Folder > Sort Folder} menu item +@cindex menu item, @samp{Folder > Sort Folder} +@kindex F S +@findex mh-sort-folder +@item F S +Sort folder (@code{mh-sort-folder}). +@c ------------------------- +@kindex F u +@findex mh-undo-folder +@item F u +Undo all refiles and deletes in the current folder (@code{mh-undo-folder}). +@c ------------------------- +@cindex @samp{Folder > Visit a Folder...} menu item +@cindex menu item, @samp{Folder > Visit a Folder...} +@kindex F v +@findex mh-visit-folder +@item F v +Visit folder (@code{mh-visit-folder}). +@c ------------------------- +@cindex @samp{Message > Refile Message} menu item +@cindex menu item, @samp{Message > Refile Message} +@kindex o +@findex mh-refile-msg +@item o +Refile (output) range into folder (@code{mh-refile-msg}). +@c ------------------------- +@cindex @samp{Folder > Quit MH-E} menu item +@cindex menu item, @samp{Folder > Quit MH-E} +@kindex q +@findex mh-quit +@item q +Quit the current MH-E folder (@code{mh-quit}). +@c ------------------------- +@cindex @samp{Folder > Toggle Show/Folder} menu item +@cindex menu item, @samp{Folder > Toggle Show/Folder} +@kindex t +@findex mh-toggle-showing +@item t +Toggle between MH-Folder and MH-Folder Show modes +(@code{mh-toggle-showing}). +@c ------------------------- +@cindex @samp{Message > Undo Delete/Refile} menu item +@cindex menu item, @samp{Message > Undo Delete/Refile} +@kindex u +@findex mh-undo +@item u +Undo pending deletes or refiles in range (@code{mh-undo}). +@c ------------------------- +@cindex @samp{Message > Execute Delete/Refile} menu item +@cindex menu item, @samp{Message > Execute Delete/Refile} +@kindex x +@findex mh-execute-commands +@item x +Process outstanding delete and refile requests +(@code{mh-execute-commands}). +@end table + +@cindex @samp{mh-folder} customization group +@cindex customization group, @samp{mh-folder} + +The @samp{mh-folder} customization group is used to tune these +commands. + +@vtable @code +@item mh-new-messages-folders +Folders searched for the @samp{unseen} sequence (default: +@code{Inbox}). +@c ------------------------- +@item mh-ticked-messages-folders +Folders searched for @code{mh-tick-seq} (default: @code{t}). +@c ------------------------- +@item mh-large-folder +The number of messages that indicates a large folder (default: 200). +@c ------------------------- +@item mh-recenter-summary-flag +On means to recenter the summary window (default: @samp{off}). +@c ------------------------- +@item mh-recursive-folders-flag +On means that commands which operate on folders do so recursively +(default: @samp{off}). +@c ------------------------- +@item mh-sortm-args +Additional arguments for @command{sortm} (default: @code{nil}). +@end vtable + +The following hooks are available. + +@vtable @code +@item mh-after-commands-processed-hook +Hook run by @kbd{x} after performing outstanding refile and delete +requests (default: @code{nil}). +@c ------------------------- +@item mh-before-commands-processed-hook +Hook run by @kbd{x} before performing outstanding refile and delete +requests (default: @code{nil}). +@c ------------------------- +@item mh-before-quit-hook +Hook run by q before quitting MH-E (default: @code{nil}). +@c ------------------------- +@item mh-folder-mode-hook +Hook run by @code{mh-folder-mode} when visiting a new folder (default: +@code{nil}). +@c ------------------------- +@item mh-kill-folder-suppress-prompt-hook +Abnormal hook run at the beginning of @code{mh-kill-folder} (default: +@code{'mh-search-p}). +@c ------------------------- +@item mh-quit-hook +Hook run by q after quitting MH-E (default: @code{nil}). +@c ------------------------- +@item mh-refile-msg-hook +Hook run by o after marking each message for refiling (default: +@code{nil}). +@end vtable + +The following faces are available for customizing the appearance of +the MH-Folder buffer. @xref{Scan Line Formats}. + +@vtable @code +@item mh-folder-address +Recipient face. +@c ------------------------- +@item mh-folder-body +Body text face. +@c ------------------------- +@item mh-folder-cur-msg-number +Current message number face. +@c ------------------------- +@item mh-folder-date +Date face. +@c ------------------------- +@item mh-folder-deleted +Deleted message face. +@c ------------------------- +@item mh-folder-followup +@samp{Re:} face. +@c ------------------------- +@item mh-folder-msg-number +Message number face. +@c ------------------------- +@item mh-folder-refiled +Refiled message face. +@c ------------------------- +@vindex mh-scan-format-nmh +@vindex mh-scan-sent-to-me-sender-regexp +@item mh-folder-sent-to-me-hint +Fontification hint face in messages sent directly to us. The detection +of messages sent to us is governed by the scan format +@code{mh-scan-format-nmh} and regular expression +@code{mh-scan-sent-to-me-sender-regexp}. +@c ------------------------- +@vindex mh-scan-format-nmh +@vindex mh-scan-sent-to-me-sender-regexp +@item mh-folder-scan-format +Sender face in messages sent directly to us. The detection of messages +sent to us is governed by the scan format @code{mh-scan-format-nmh} +and regular expression @code{mh-scan-sent-to-me-sender-regexp}. +@c ------------------------- +@item mh-folder-subject +Subject face. +@c ------------------------- +@item mh-folder-tick +Ticked message face. +@c ------------------------- +@item mh-folder-to +@samp{To:} face. +@end vtable + +The hook @code{mh-folder-mode-hook} is called when visiting a new +folder in 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 "//" 'my-search-msg) + (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}} + (setq my-mh-init-done t)))) + +(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook) + +(defun my-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} + ; @r{ when done} + +@i{Create additional key bindings via mh-folder-mode-hook} + +@end group +@end smalllisp + +@cindex @command{folder} +@cindex @command{refile} +@cindex MH commands, @command{folder} +@cindex MH commands, @command{refile} +@findex mh-refile-msg +@kindex o +@vindex mh-refile-msg-hook + +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 command @kbd{o} (@code{mh-refile-msg}) +(mnemonic: ``output''). 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. The hook @code{mh-refile-msg-hook} is called +after a message is marked to be refiled. + +If you are refiling several messages into the same folder, you can use +the command @kbd{!} (@code{mh-refile-or-write-again}) to repeat the +last refile or write (see the description of @kbd{>} +(@code{mh-write-msg-to-file} in @ref{Files and Pipes}). You can use a +range in either case (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 and 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. + +The command @kbd{x} runs @code{mh-before-commands-processed-hook} +before the commands are processed and +@code{mh-after-commands-processed-hook} after the commands are +processed. Variables that are useful with the former hook include +@code{mh-delete-list} and @code{mh-refile-list} which can be used to +see which changes will be made to the current folder, +@code{mh-current-folder}. Variables that are useful with the latter +hook include @code{mh-folders-changed}, which lists which folders were +affected by deletes and refiles. This list will always include the +current folder @code{mh-current-folder}. + +If you wish to copy a message to another folder, you can use the +command @kbd{c} (@code{mh-copy-msg}) (see the @option{-link} argument +to @command{refile}(1)). Like the command @kbd{o}, this command +prompts you for the name of the target folder and you can specify a +range (@pxref{Ranges}). Note that unlike the command @kbd{o}, 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 junk mail -@findex @code{mh-toggle-showing} +@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 +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. -@node Sending Mail, Draft Editing, Reading Mail, Using mh-e -@section Sending Mail +@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} 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 command @kbd{F v} (@code{mh-visit-folder}) 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 and @code{mh-large-folder} is ignored. 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 forget where you've refiled your messages, you can find them +using @kbd{F s} (@code{mh-search}). @xref{Searching}. + +@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 +@findex mh-index-new-messages +@kindex F n +@vindex mh-new-messages-folders + +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 command @kbd{F n} +(@code{mh-index-new-messages}). All messages in the @samp{unseen} +sequence from the folders in @code{mh-new-messages-folders} are +listed. However, this list of folders can be overridden with a prefix +argument: 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 command @kbd{F '} (@code{mh-index-ticked-messages}). All +messages in the @samp{tick} sequence from the folders in +@code{mh-ticked-messages-folders} are listed. With a prefix argument, +enter a space-separated list of folders, or nothing to search all +folders. + +@findex mh-index-sequenced-messages +@kindex F q +@vindex mh-new-messages-folders + +You can display messages in any sequence with the command @kbd{F q} +(@code{mh-index-sequenced-messages}). All messages from the folders in +@code{mh-new-messages-folders} in the sequence you provide are listed. +With a prefix argument, enter a space-separated list of folders at the +prompt, or nothing to search all folders. + +Set the options @code{mh-new-messages-folders} and +@code{mh-ticked-messages-folders} to @samp{Inbox} to search the +@samp{+inbox} folder or @samp{All} to search all of the top level +folders. Otherwise, list the folders that should be searched with the +@samp{Choose Folders} menu item. See @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{F S} (@code{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 (@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. + +@vindex mh-kill-folder-suppress-prompt-hooks + +The hook @code{mh-kill-folder-suppress-prompt-hooks} is an abnormal +hook run at the beginning of the command @kbd{k}. The hook functions +are called with no arguments and should return a non-nil value to +suppress the normal prompt when you remove a folder. This is useful +for folders that are easily regenerated. The default value of +@code{mh-search-p} suppresses the prompt on folders generated by +searching. + +@sp 1 +@center @strong{NOTE} + +@quotation +Use this hook with care. If there is a bug in your hook which returns +@code{t} on @samp{+inbox} and you hit @kbd{k} by accident in the +@code{+inbox} folder, you will not be happy. +@end quotation +@sp 1 + +@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 option @code{mh-sortm-args} holds extra arguments to pass on to +the command @command{sortm}@footnote{See the section +@uref{@value{MH-BOOK-HOME}/sorsor.htm, Sorting Messages: sortm} in the +MH book.} when a prefix argument is used with @kbd{F S}. Normally +default arguments to @command{sortm} are specified in the MH profile. +This option may be used to provide an alternate view. For example, +@samp{'(\"-nolimit\" \"-textfield\" \"subject\")} is a useful setting. + +@cindex exiting +@cindex quitting +@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}. It also removes any MH-E working +buffers whose name begins with @samp{ *mh-} or @samp{*MH-E } +(@pxref{Miscellaneous}). You can later restore your MH-E session by +selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail} +again. + +@vindex mh-before-quit-hook +@vindex mh-quit-hook + +The two hooks @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{Miscellaneous Commands and Options}, you would also want to set +@code{mh-quit-hook} to the following: + +@c XXX Replace this with my example for killing the mail buffers. + +@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 + +@cindex folders, renaming +@cindex renaming folders +@findex dired-do-rename +@kindex R + +You can use dired to manipulate the folders themselves. For example, I +renamed my @samp{+out} folder to the more common @samp{+outbox} by +running dired on my mail directory (@kbd{M-x dired RET ~/Mail RET}), +moving my cursor to @samp{out} and using the command @kbd{R} +(@code{dired-do-rename}). + +@node Sending Mail, Editing Drafts, Folders, Top +@chapter Sending Mail @cindex sending mail -@findex @code{mh-smail} - -You can send a mail message in several ways. You can call @kbd{M-x +@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} +$ @kbd{emacs -f mh-smail} @end example -From within mh-e's MH-Folder mode, other methods of sending mail -are available as well: +@findex goto-address-at-point +@vindex mail-user-agent + +There are some commands that need to send a mail message, such as +@code{goto-address-at-point}. You can configure Emacs to have these +commands use MH-E by setting the option @code{mail-user-agent} to +@samp{Emacs interface to MH}. + +From within MH-E's MH-Folder mode, other methods of sending mail are +available as well. These can also be found in the @samp{Message} menu. @table @kbd -@item m -Compose a message (@code{mh-send}). - +@cindex @samp{Message > Edit Message Again} menu item +@cindex menu item, @samp{Message > Edit Message Again} +@kindex e +@findex mh-edit-again +@item e +Edit a message to send it again (@code{mh-edit-again}). +@c ------------------------- +@cindex @samp{Message > Re-edit a Bounced Message} menu item +@cindex menu item, @samp{Message > Re-edit a Bounced Message} +@kindex E +@findex mh-extract-rejected-mail +@item E +Edit a message that was returned by the mail system +(@code{mh-extract-rejected-mail}). +@c ------------------------- +@cindex @samp{Message > Forward Message...} menu item +@cindex menu item, @samp{Message > Forward Message...} +@kindex f +@findex mh-forward +@item f +Forward message (@code{mh-forward}). +@c ------------------------- +@cindex @samp{Message > Reply to Message...} menu item +@cindex menu item, @samp{Message > Reply to Message...} +@kindex r +@findex mh-reply @item r Reply to a message (@code{mh-reply}). - -@item f -Forward message(s) (@code{mh-forward}). - +@c ------------------------- +@cindex @samp{Message > Compose a New Message} menu item +@cindex menu item, @samp{Message > Compose a New Message} +@kindex s +@findex mh-send +@item s +Compose a message (@code{mh-send}). +@c ------------------------- +@cindex @samp{Message > Redistribute Message...} menu item +@cindex menu item, @samp{Message > Redistribute Message...} +@kindex M-d +@findex mh-redistribute @item M-d Redistribute a message (@code{mh-redistribute}). - -@item M-e -Edit a message that was bounced by mailer (@code{mh-extract-rejected-mail}). - -@item M-a -Edit a message to send it again (@code{mh-edit-again}). +@c ------------------------- +@findex mh-smail +@item M-x mh-smail +Compose a message with the MH mail system. +@c ------------------------- +@findex mh-smail-other-window +@item M-x mh-smail-other-window +Compose a message with the MH mail system in other window. @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-compose-forward-as-mime-flag +On means that messages are forwarded as attachments (default: +@samp{on}). +@c ------------------------- +@item mh-compose-letter-function +Hook run when starting a new draft (default: @code{nil}). +@c ------------------------- +@item mh-compose-prompt-flag +On means prompt for header fields when composing a new draft (default: +@samp{off}). +@c ------------------------- +@item mh-forward-subject-format +Format string for forwarded message subject (default: @samp{"%s: +%s"}). +@c ------------------------- +@item mh-insert-x-mailer-flag +On means append an @samp{X-Mailer:} header field to the header +(default: @samp{on}). +@c ------------------------- +@item mh-redist-full-contents-flag +On means the @command{dist} command needs entire letter for +redistribution (default: @samp{off}). +@c ------------------------- +@item mh-reply-default-reply-to +Sets the person or persons to whom a reply will be sent (default: +@samp{Prompt}). +@c ------------------------- +@item mh-reply-show-message-flag +On means the MH-Show buffer is displayed using @kbd{r} +(@code{mh-reply}) (default: @samp{on}). +@end vtable + +The following hooks are available. + +@vtable @code +@item mh-forward-hook +Hook run by @code{mh-forward} on a forwarded letter (default: +@code{nil}). +@c ------------------------- +@item mh-letter-mode-hook +Hook run by @code{mh-letter-mode} on a new letter (default: +@code{nil}). +@end vtable + +The functions and options 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 @file{.emacs} @cindex MH-Folder mode +@cindex composing mail +@cindex draft +@cindex files, @file{.emacs} @cindex modes, MH-Folder +@cindex sending mail +@findex mh-smail +@findex mh-smail-other-window + +Outside of an MH-Folder buffer, you must call either @kbd{M-x +mh-smail} or @kbd{M-x mh-smail-other-window} to compose a new message. +The former command always creates a two-window layout with the current +buffer on top and the draft on the bottom. Use the latter command if +you would rather preserve the window layout. You may find adding the +following key bindings to @file{~/.emacs} useful: + +@smalllisp +(global-set-key "\C-xm" 'mh-smail) +(global-set-key "\C-x4m" 'mh-smail-other-window) +@end smalllisp + @cindex MH-Letter mode +@cindex draft folder @cindex modes, MH-Letter -@findex @code{mh-send} +@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}, you are prompted -for the @samp{To:}, @samp{cc:}, and @samp{Subject:} header fields. Once -you've specified the recipients and subject, your message appears in an -Emacs buffer whose mode is MH-Letter (see the Figure in @ref{Sending -Mail} 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 -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 (e.g., @file{+drafts}), and add a -profile component called @samp{Draft-Folder:} which contains -@file{+drafts} (see @code{mh-profile}(5)).} (a message you're composing) -in just a moment. - -@findex @code{mh-smail} -@findex @code{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}. - -@menu -* Replying:: -* Forwarding:: -* Redistributing:: -* Old Drafts:: -@end menu - -@node Replying, Forwarding, Sending Mail, Sending Mail -@subsection Replying to Mail - +(@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 +(@pxref{Editing Drafts}). + +@vindex mh-compose-prompt-flag + +If you prefer to be prompted for the recipient and subject fields +before the MH-Letter buffer appears, turn on the option +@code{mh-compose-prompt-flag}. + +@cindex @samp{X-Mailer:} header field +@cindex header field, @samp{X-Mailer:} +@vindex mh-insert-x-mailer-flag + +MH-E adds an @samp{X-Mailer:} header field to the header that includes +the version of MH-E and Emacs that you are using. If you don't want to +participate in our marketing, you can turn off the option +@code{mh-insert-x-mailer-flag}. + +@cindex @command{repl} +@cindex @file{components} +@cindex MH commands, @command{repl} +@cindex Mail mode +@cindex files, @file{components} +@cindex modes, Mail +@vindex mail-mode-hook +@vindex mh-letter-mode-hook +@vindex text-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@footnote{Actually, because +MH-Letter mode inherits from Mail mode, the hooks +@code{text-mode-hook} and @code{mail-mode-hook} are run (in that +order) before @code{mh-letter-mode-hook}.}. 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. You can add the hook using @code{add-hook} or by running +@kbd{M-x customize-option @key{RET} mh-letter-mode-hook +@key{RET}}---all of the other hooks are set in a similar fashion. + +@findex mh-insert-signature, example + +@smalllisp +@group +(defvar letter-mode-init-done-flag nil + "Non-nil means one-time MH-E settings have been made.") + +(defun my-mh-letter-mode-hook () + "Prepare letter for editing." + (when (not letter-mode-init-done) ; @r{only need to bind the keys once} + (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)) + (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 -@cindex @code{mhl} -@cindex MH commands, @code{mhl} -@cindex @file{mhl.reply} -@cindex files, @file{mhl.reply} -@findex @code{mh-reply} +@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 @code{mhl} with the format file @file{mhl.reply}. See -@code{mhl}(1) 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. - -@example +command. + +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} @@ -935,810 +3814,2356 @@ @kbd{all} @kbd{cc} @r{Forms a reply to the sender, plus all recipients.} @end group -@end example - -@cindex @code{repl} -@cindex MH commands, @code{repl} - -Depending on your answer, @code{repl} is given a different argument to -form your reply. Specifically, a choice of @kbd{from} or none at all -runs @code{repl -nocc all}, and a choice of @kbd{to} runs @code{repl -cc -to}. Finally, either @kbd{cc} or @kbd{all} runs @code{repl -cc all --nocc me}. +@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 MH-Show mode +@cindex draft @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 (described in -@ref{Draft Editing}), is in the other window. +@cindex modes, MH-Show + +Two windows are then created. One window contains the message to which +you are replying in an MH-Show buffer. Your draft, in MH-Letter mode +(@pxref{Editing Drafts}), is in the other window. + +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. + +@vindex mh-yank-behavior + +Alternatively, you can customize the option @code{mh-yank-behavior} +and choose one of its @samp{Automatically} variants to do the same +thing. @xref{Inserting Letter}. If you do so, the prefix argument has +no effect. + +Another way to include the message automatically in your draft is to +use @samp{repl: -filter repl.filter} in your MH profile. + +If you include the message automatically, you can hide the MH-Show +buffer by turning off the option @code{mh-reply-show-message-flag}. If you wish to customize the header or other parts of the reply draft, -please see @code{repl}(1) and @code{mh-format}(5). +please see @command{repl}(1) and @code{mh-format}(5). + +@vindex mh-reply-default-reply-to + +The @code{mh-reply-default-reply-to} option is set to @samp{Prompt} by +default so that you are prompted for the recipient of a reply. If you +find that most of the time that you specify @kbd{cc} when you reply to +a message, set this option to @samp{cc}. Other choices include +@samp{from}, @samp{to}, or @samp{all}. You can always edit the +recipients in the draft. @node Forwarding, Redistributing, Replying, Sending Mail -@subsection Forwarding Mail - +@section Forwarding Mail + +@cindex @command{forw} +@cindex MH commands, @command{forw} +@cindex draft @cindex forwarding -@cindex @code{forw} -@cindex MH commands, @code{forw} -@findex @code{mh-forward} - -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 @code{forw}. You are given a chance to add some text (see -@ref{Draft Editing}). - -You can forward several messages by using a prefix argument; in this -case, you are prompted for the name of a @dfn{sequence}, a symbolic name -that represents a list or range of message numbers (for example, -@kbd{C-u f forbob @key{RET}}). All of the messages in the sequence are -inserted into your draft. By the way, although sequences are often -mentioned in this chapter, you don't have to worry about them for now; -the full description of sequences in mh-e is at the end in -@ref{Sequences}. To learn more about sequences in general, please see -@code{mh-sequence}(5). - -@node Redistributing, Old Drafts, Forwarding, Sending Mail -@subsection Redistributing Your Mail - +@findex mh-forward +@kindex f +@vindex mh-forward-hook + +To forward a message, use the @kbd{f} (@code{mh-forward}) command. You +are prompted for the @samp{To:} and @samp{cc:} recipients. 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 can then 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. The +hook @code{mh-forward-hook} is called on the draft. + +@cindex @file{.mh_profile} +@cindex @samp{forw:} MH profile component +@cindex MH profile component, @samp{forw:} +@cindex files, @file{.mh_profile} +@vindex mh-compose-forward-as-mime-flag + +By default, the option @code{mh-compose-forward-as-mime-flag} is on +which means that the forwarded messages are included as attachments. +If you would prefer to forward your messages verbatim (as text, +inline), then turn off this option. Forwarding messages verbatim works +well for short, textual messages, but your recipient won't be able to +view any non-textual attachments that were in the forwarded message. +Be aware that if you have @samp{forw: -mime} in your MH profile, then +forwarded messages will always be included as attachments regardless +of the settings of @code{mh-compose-forward-as-mime-flag}. + +@vindex mh-forward-subject-format + +The format of the @samp{Subject:} header field for forwarded messages +is controlled by the option @code{mh-forward-subject-format}. This +option 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: + +@smallexample +@group +To: Bill Wohler <wohler@@stop.mail-abuse.org> +Subject: Re: 49er football +From: Greg DesBrisay <gd@@stop.mail-abuse.org> +@end group +@end smallexample + +and creates a subject header field of: + +@smallexample +Subject: Greg DesBrisay: Re: 49er football +@end smallexample + +@node Redistributing, Editing Again, Forwarding, Sending Mail +@section Redistributing Your Mail + +@cindex @command{dist} +@cindex MH commands, @command{dist} @cindex redistributing -@findex @code{mh-redistribute} - -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 @code{dist}(1). Also -investigate the @kbd{M-a} (@code{mh-edit-again}) command in @ref{Old -Drafts}, for another way to redistribute messages. - -@node Old Drafts, , Redistributing, Sending Mail -@subsection Editing Old Drafts and Bounced Messages - -@cindex re-editing drafts +@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. +When you run this command, you are prompted for the recipients. + +For more information on redistributing messages, see +@command{dist}(1). Also investigate the command @kbd{e} +(@code{mh-edit-again}) for another way to redistribute messages +(@pxref{Editing Again}). + +@cindex @command{send} +@cindex MH commands, @command{send} +@vindex mh-redist-full-contents-flag + +The option @code{mh-redist-full-contents-flag} must be turned on 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} option (which many +people abhor). If you find that MH will not allow you to redistribute +a message that has been redistributed before, turn off this option. + +@node Editing Again, , Redistributing, Sending Mail +@section Editing Old Drafts and Bounced Messages + @cindex @file{draft} @cindex files, @file{draft} -@findex @code{mh-edit-again} +@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{M-a} (@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{M-f drafts @key{RET}}, -use @kbd{n} to move to the appropriate message, and then use @kbd{M-a} -to prepare the message for editing. - -The @kbd{M-a} command can also be used to take messages that were sent +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 @code{mh-extract-rejected-mail} - -Don't use @kbd{M-a} 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{M-e} (@code{mh-extract-rejected-mail}) to prepare +@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 +unneeded header fields. Fix whatever addressing problem you had, and send the message again with @kbd{C-c C-c}. -@node Draft Editing, Moving Mail, Sending Mail, Using mh-e -@section Editing a Draft - +@node Editing Drafts, Aliases, Sending Mail, Top +@chapter Editing a Draft + +@cindex MH-Letter mode +@cindex draft @cindex editing draft -@cindex MH-Letter mode @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. +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. These can also be found in the @samp{Letter} menu. @table @kbd -@item C-c C-y -Insert contents of message to which you're replying (@code{mh-yank-cur-msg}). - -@item C-c C-i -Insert a message from a folder (@code{mh-insert-letter}). - -@item C-c C-f C-t -Move to @samp{To:} header field (@code{mh-to-field}). - +@kindex @key{SPC} +@findex mh-letter-complete-or-space +@item @key{SPC} +Perform completion or insert space (@code{mh-letter-complete-or-space}). +@c ------------------------- +@kindex M-@key{TAB} +@findex mh-letter-complete +@item M-@key{TAB} +Perform completion on header field or word preceding point +(@code{mh-letter-complete}). +@c ------------------------- +@kindex , (comma) +@findex mh-letter-confirm-address +@item , (comma) +Flash alias expansion (@code{mh-letter-confirm-address}). +@c ------------------------- +@kindex @key{TAB} +@findex mh-letter-next-header-field-or-indent +@item @key{TAB} +Cycle to next field (@code{mh-letter-next-header-field-or-indent}). +@c ------------------------- +@kindex S-@key{TAB} +@findex mh-letter-previous-header-field +@item S-@key{TAB} +Cycle to the previous header field +(@code{mh-letter-previous-header-field}). +@c ------------------------- +@kindex C-c ? +@findex mh-help +@item C-c ? +Display cheat sheet for the MH-E commands (@code{mh-help}). +@c ------------------------- +@cindex @samp{Letter > Send This Draft} menu item +@cindex menu item, @samp{Letter > Send This Draft} +@kindex C-c C-c +@findex mh-send-letter +@item C-c C-c +Save draft and send message (@code{mh-send-letter}). +@c ------------------------- +@kindex C-c C-d +@findex mh-insert-identity +@item C-c C-d +Insert fields specified by the given identity +(@code{mh-insert-identity}). @xref{Identities}. +@c ------------------------- +@cindex @samp{Letter > Pull in All Compositions (MH)} menu item +@cindex menu item, @samp{Letter > Pull in All Compositions (MH)} +@kindex C-c C-e +@findex mh-mh-to-mime +@item C-c C-e +Compose @sc{mime} message from MH-style directives +(@code{mh-mh-to-mime}). +@c ------------------------- +@kindex C-c C-f C-a +@kindex C-c C-f a +@findex mh-to-field +@item C-c C-f C-a +@itemx C-c C-f a +Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-b +@kindex C-c C-f b +@item C-c C-f C-b +@itemx C-c C-f b +Move to @samp{Bcc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-c +@kindex C-c C-f c @item C-c C-f C-c -Move to @samp{cc:} header field (@code{mh-to-field}). - +@itemx C-c C-f c +Move to @samp{Cc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-d +@kindex C-c C-f d +@item C-c C-f C-d +@itemx C-c C-f d +Move to @samp{Dcc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-f +@kindex C-c C-f f +@findex mh-to-fcc +@item C-c C-f C-f +@itemx C-c C-f f +Move to @samp{Fcc:} header field (@code{mh-to-fcc}). +@c ------------------------- +@kindex C-c C-f C-l +@kindex C-c C-f l +@item C-c C-f C-l +@itemx C-c C-f l +Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-m +@kindex C-c C-f m +@item C-c C-f C-m +@itemx C-c C-f m +Move to @samp{From:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-r +@kindex C-c C-f r +@item C-c C-f C-r +@itemx C-c C-f r +Move to @samp{Reply-To:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-s +@kindex C-c C-f s @item C-c C-f C-s +@itemx C-c C-f s Move to @samp{Subject:} header field (@code{mh-to-field}). - -@item C-c C-f C-f -Move to @samp{From:} header field (@code{mh-to-field}). - -@item C-c C-f C-b -Move to @samp{Bcc:} header field (@code{mh-to-field}). - -@item C-c C-f C-f -Move to @samp{Fcc:} header field (@code{mh-to-fcc}). - -@item C-c C-f C-d -Move to @samp{Dcc:} header field (@code{mh-to-field}). - -@item C-c C-w -Display expanded recipient list (@code{mh-check-whom}). - +@c ------------------------- +@kindex C-c C-f C-t +@kindex C-c C-f t +@item C-c C-f C-t +@itemx C-c C-f t +Move to @samp{To:} header field (@code{mh-to-field}). +@c ------------------------- +@cindex @samp{Letter > Insert a Message...} menu item +@cindex menu item, @samp{Letter > Insert a Message...} +@kindex C-c C-i +@findex mh-insert-letter +@item C-c C-i +Insert a message (@code{mh-insert-letter}). +@c ------------------------- +@kindex C-c C-m C-e +@findex mh-mml-secure-message-encrypt +@item C-c C-m C-e +Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). +@c ------------------------- +@cindex @samp{Letter > Compose Forward...} menu item +@cindex menu item, @samp{Letter > Compose Forward...} +@kindex C-c C-m C-f +@kindex C-c C-m f +@findex mh-compose-forward +@item C-c C-m C-f +@itemx C-c C-m f +Add tag to forward a message (@code{mh-compose-forward}). +@c ------------------------- +@cindex @samp{Letter > Compose Get File (MH)...} menu item +@cindex menu item, @samp{Letter > Compose Get File (MH)...} +@kindex C-c C-m C-g +@kindex C-c C-m g +@findex mh-mh-compose-anon-ftp +@item C-c C-m C-g +@itemx C-c C-m g +Add tag to include anonymous ftp reference to a file +(@code{mh-mh-compose-anon-ftp}). +@c ------------------------- +@cindex @samp{Letter > Compose Insertion...} menu item +@cindex menu item, @samp{Letter > Compose Insertion...} +@kindex C-c C-m C-i +@kindex C-c C-m i +@findex mh-compose-insertion +@item C-c C-m C-i +@itemx C-c C-m i +Add tag to include a file such as an image or sound +(@code{mh-compose-insertion}). +@c ------------------------- +@cindex @samp{Letter > Pull in All Compositions (MML)} menu item +@cindex menu item, @samp{Letter > Pull in All Compositions (MML)} +@kindex C-c C-m C-m +@kindex C-c C-m m +@findex mh-mml-to-mime +@item C-c C-m C-m +@itemx C-c C-m m +Compose @sc{mime} message from MML tags (@code{mh-mml-to-mime}). +@c ------------------------- +@kindex C-c C-m C-n +@kindex C-c C-m n +@findex mh-mml-unsecure-message +@item C-c C-m C-n +@itemx C-c C-m n +Remove any secure message tags (@code{mh-mml-unsecure-message}). +@c ------------------------- +@kindex C-c C-m C-s +@findex mh-mml-secure-message-sign +@item C-c C-m C-s +Add tag to sign the message (@code{mh-mml-secure-message-sign}). +@c ------------------------- +@cindex @samp{Letter > Compose Compressed tar (MH)...} menu item +@cindex menu item, @samp{Letter > Compose Compressed tar (MH)...} +@kindex C-c C-m C-t +@kindex C-c C-m t +@findex mh-mh-compose-external-compressed-tar +@item C-c C-m C-t +@itemx C-c C-m t +Add tag to include anonymous ftp reference to a compressed tar file +(@code{mh-mh-compose-external-compressed-tar}). +@c ------------------------- +@cindex @samp{Letter > Revert to Non-MIME Edit (MH)} menu item +@cindex menu item, @samp{Letter > Revert to Non-MIME Edit (MH)} +@kindex C-c C-m C-u +@kindex C-c C-m u +@findex mh-mh-to-mime-undo +@item C-c C-m C-u +@itemx C-c C-m u +Undo effects of @kbd{C-c C-e} (@code{mh-mh-to-mime-undo}). +@c ------------------------- +@kindex C-c C-m C-x +@kindex C-c C-m x +@findex mh-mh-compose-external-type +@item C-c C-m C-x +@itemx C-c C-m x +Add tag to refer to a remote file +(@code{mh-mh-compose-external-type}). +@c ------------------------- +@kindex C-c C-m e e +@findex mh-mml-secure-message-encrypt +@item C-c C-m e e +Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). +@c ------------------------- +@kindex C-c C-m e s +@findex mh-mml-secure-message-signencrypt +@item C-c C-m e s +Add tag to encrypt and sign the message@* +(@code{mh-mml-secure-message-signencrypt}). +@c ------------------------- +@kindex C-c C-m s e +@findex mh-mml-secure-message-signencrypt +@item C-c C-m s e +Add tag to encrypt and sign the message@* +(@code{mh-mml-secure-message-signencrypt}). +@c ------------------------- +@kindex C-c C-m s s +@findex mh-mml-secure-message-sign +@item C-c C-m s s +Add tag to sign the message (@code{mh-mml-secure-message-sign}). +@c ------------------------- +@cindex @samp{Letter > Split Current Line} menu item +@cindex menu item, @samp{Letter > Split Current Line} +@kindex C-c C-o +@findex mh-open-line +@item C-c C-o +Insert a newline and leave point before it (@code{mh-open-line}). +@c ------------------------- +@cindex @samp{Letter > Kill This Draft} menu item +@cindex menu item, @samp{Letter > Kill This Draft} +@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}). +@c ------------------------- +@cindex @samp{Letter > Insert Signature} menu item +@cindex menu item, @samp{Letter > Insert Signature} +@kindex C-c C-s +@findex mh-insert-signature @item C-c C-s Insert signature in message (@code{mh-insert-signature}). - -@item C-c C-m C-f -Include forwarded message (@sc{mime}) (@code{mh-mhn-compose-forw}). - -@item C-c C-m C-e -Include anonymous ftp reference (@sc{mime}) (@code{mh-mhn-compose-anon-ftp}). - -@item C-c C-m C-t -Include anonymous ftp reference to compressed tar file (@sc{mime}) -(@code{mh-mhn-compose-external-compressed-tar}). - -@item C-c C-m C-i -Include binary, image, sound, etc. (@sc{mime}) -(@code{mh-mhn-compose-insertion}). - -@item C-c C-e -Run through @code{mhn} before sending (@code{mh-edit-mhn}). - -@item C-c C-m C-u -Undo effects of @code{mhn} (@code{mh-revert-mhn-edit}). - -@item C-c C-c -Save draft and send message (@code{mh-send-letter}). - -@item C-c C-q -Quit editing and delete draft message (@code{mh-fully-kill-draft}). +@c ------------------------- +@kindex C-c C-t +@findex mh-letter-toggle-header-field-display +@item C-c C-t +Toggle display of header field at point +(@code{mh-letter-toggle-header-field-display}). +@c ------------------------- +@cindex @samp{Letter > Check Recipient} menu item +@cindex menu item, @samp{Letter > Check Recipient} +@kindex C-c C-w +@findex mh-check-whom +@item C-c C-w +Verify recipients, showing expansion of any aliases +(@code{mh-check-whom}). +@c ------------------------- +@cindex @samp{Letter > Yank Current Message} menu item +@cindex menu item, @samp{Letter > Yank Current Message} +@kindex C-c C-y +@findex mh-yank-cur-msg +@item C-c C-y +Insert the current message into the draft buffer +(@code{mh-yank-cur-msg}). +@c ------------------------- +@kindex C-c M-d +@findex mh-insert-auto-fields +@item C-c M-d +Insert custom fields if recipient is found in +@code{mh-auto-fields-list} (@code{mh-insert-auto-fields}). +@xref{Identities}. @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-insertion +Type of @sc{mime} message tags in messages (default: @samp{MML} if +available; otherwise @samp{MH}). +@c ------------------------- +@item mh-compose-skipped-header-fields +List of header fields to skip over when navigating in draft (default: +@code{'("From"} @code{"Organization"} @code{"References"} +@code{"In-Reply-To"} @code{"X-Face"} @code{"Face"} +@code{"X-Image-URL"} @code{"X-Mailer")}. +@c ------------------------- +@item mh-compose-space-does-completion-flag +On means @key{SPC} does completion in message header (default: +@samp{off}). +@c ------------------------- +@item mh-delete-yanked-msg-window-flag +On means delete any window displaying the message (default: @samp{off}). +@c ------------------------- +@item mh-extract-from-attribution-verb +Verb to use for attribution when a message is yanked by @kbd{C-c C-y} +(default: @samp{"wrote:"}). +@c ------------------------- +@item mh-ins-buf-prefix +String to put before each line of a yanked or inserted message +(default: @samp{"> "}). +@c ------------------------- +@item mh-letter-complete-function +Function to call when completing outside of address or folder fields +(default: @code{ispell-complete-word}). +@c ------------------------- +@item mh-letter-fill-column +Fill column to use in MH-Letter mode (default: 72). +@c ------------------------- +@item mh-mml-method-default +Default method to use in security tags (default: @samp{PGP (MIME)} if +support for it is available; otherwise @samp{None}). +@c ------------------------- +@item mh-signature-file-name +Source of user's signature (default: @samp{"~/.signature"}). +@c ------------------------- +@item mh-signature-separator-flag +On means a signature separator should be inserted (default: +@samp{on}). +@c ------------------------- +@item mh-x-face-file +File containing X-Face or Face header field to insert in outgoing mail. +(default: @samp{"~/.face"}). +@c ------------------------- +@item mh-yank-behavior +Controls which part of a message is yanked by @kbd{C-c C-y} (default: +@samp{Body With Attribution}). +@end vtable + +The following hooks are available. + +@vtable @code +@item mail-citation-hook +Hook for modifying a citation just inserted in the mail buffer +(default: @code{nil}). +@c ------------------------- +@item mh-before-send-letter-hook +Hook run at the beginning of the @kbd{C-c C-c} command (default: +@samp{nil}). +@c ------------------------- +@item mh-mh-to-mime-hook +Hook run on the formatted letter by @kbd{C-c C-e} (default: +@samp{nil}). +@c ------------------------- +@item mh-insert-signature-hook +Hook run by @kbd{C-c C-s} after signature has been inserted (default: +@code{nil}). +@end vtable + +The following face is available. + +@vtable @code +@item mh-letter-header-field +Editable header field value face in draft buffers. +@end vtable + +The commands and options introduced here are explained in more +detail in the following sections. + @menu -* Editing Textual:: -* Editing MIME:: -* Sending Message:: -* Killing Draft:: +* Editing Message:: +* Inserting Letter:: +* Inserting Messages:: +* Signature:: +* Picture:: +* Adding Attachments:: +* Sending PGP:: +* Checking Recipients:: +* Sending Message:: +* Killing Draft:: @end menu -@node Editing Textual, Editing MIME, Draft Editing, Draft Editing -@subsection Editing Textual Messages - -The following sections show you how to edit a draft. -The commands described here are also applicable to messages that have -multimedia components. - -@menu -* Inserting Letter:: -* Inserting Messages:: -* Header:: -* Recipients:: -* Signature:: -@end menu - -@node Inserting Letter, Inserting Messages, Editing Textual, Editing Textual -@subsubsection Inserting letter to which you're replying +@node Editing Message, Inserting Letter, Editing Drafts, Editing Drafts +@section Editing the Message + +@cindex @samp{Bcc:} header field +@cindex @samp{Cc:} header field +@cindex @samp{Dcc:} header field +@cindex @samp{From:} header field +@cindex @samp{Mail-Followup-To:} header field +@cindex @samp{Mail-Reply-To:} header field +@cindex @samp{Reply-To:} header field +@cindex @samp{Subject:} header field +@cindex @samp{To:} header field +@cindex editing header +@cindex header field, @samp{Bcc:} +@cindex header field, @samp{Cc:} +@cindex header field, @samp{Dcc:} +@cindex header field, @samp{From:} +@cindex header field, @samp{Mail-Followup-To:} +@cindex header field, @samp{Mail-Reply-To:} +@cindex header field, @samp{Reply-To:} +@cindex header field, @samp{Subject:} +@cindex header field, @samp{To:} +@findex mh-to-field +@kindex C-c C-f C-t +@kindex C-c C-f t + +Because the header is part of the message, you can edit the header +fields as you wish. However, several convenience commands 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 +commands for moving to the @samp{Cc:}, @samp{Subject:}, @samp{From:}, +@samp{Reply-To:}, @samp{Mail-Reply-To:}, @samp{Mail-Followup-To}, +@samp{Bcc:}, and @samp{Dcc:} header fields are similar. + +@findex mh-to-fcc +@kindex C-c C-f C-f +@kindex C-c C-f f + +One command 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 command +will prompt you for the folder name in which to file a copy of the +draft. @xref{Folder Selection}. + +@findex indent-relative +@findex mh-letter-next-header-field-or-indent +@findex mh-letter-previous-header-field +@kindex S-@key{TAB} +@kindex @key{TAB} +@vindex mh-compose-skipped-header-fields +@vindex mh-letter-header-field + +Within the header of the message, the command@* @key{TAB} +(@code{mh-letter-next-header-field-or-indent}) moves between fields +that are highlighted with the face @code{mh-letter-header-field}, +skipping those fields listed in +@code{mh-compose-skipped-header-fields}. After the last field, this +command then moves point to the message body before cycling back to +the first field. If point is already past the first line of the +message body, then this command indents by calling +@code{indent-relative} with the given prefix argument. The command +@kbd{S-@key{TAB}} (@code{mh-letter-previous-header-field}) moves +backwards between the fields and cycles to the body of the message +after the first field. Unlike the command @key{TAB}, it will always +take point to the last field from anywhere in the body. + +@cindex alias completion +@cindex completion +@cindex spell check +@findex ispell-complete-word +@findex mh-letter-complete +@findex mh-letter-complete-or-space +@findex mh-letter-confirm-address +@kindex , (comma) +@kindex M-@key{TAB} +@kindex @key{SPC} +@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 command +@kbd{M-@key{TAB}} (@code{mh-letter-complete}) will provide alias +completion (@pxref{Aliases}). In the body of the message, +@kbd{M-@key{TAB}} runs @code{mh-letter-complete-function} instead, +which is set to @samp{'ispell-complete-word} by default. The command +@kbd{M-@key{TAB}} (@code{mh-letter-complete}) takes a prefix argument +that is passed to the @code{mh-letter-complete-function}. In addition, +turn on the option @code{mh-compose-space-does-completion-flag} to use +the command @key{SPC} (@code{mh-letter-complete-or-space}) to perform +completion in the header as well; use a prefix argument to specify +more than one space. Addresses are separated by a comma; when you +press the comma, the command @code{mh-letter-confirm-address} flashes +the alias expansion in the minibuffer if +@code{mh-alias-flash-on-comma} is turned on. + +@kindex C-c C-t +@findex mh-letter-toggle-header-field-display +@c XXX Document the replacement for the inaccessible 'long argument. + +Use the command @kbd{C-c C-t} +@code{mh-letter-toggle-header-field-display} to display truncated +header fields. This command is a toggle so entering it again will hide +the field. This command takes a prefix argument: if negative then the +field is hidden, if positive then the field is displayed (for example, +@kbd{C-u C-c C-t}). + +Be sure to leave a row of dashes or a blank line between the header +and the body of the message. + +@vindex mh-letter-fill-column + +The body of the message is edited as you would edit any Emacs buffer +although there are a few commands and options to assist you. You can +change the fill column in MH-Letter mode with the option +@code{mh-letter-fill-column}. By default, this option is 72 to allow +others to quote your message without line wrapping. + +@cindex filling paragraphs +@cindex paragraphs, filling +@findex fill-paragraph +@kindex M-q +@vindex mh-ins-buf-prefix + +You'll often include messages that were sent from user agents that +haven't yet realized that paragraphs consist of more than a single +line. This makes for long lines that wrap in an ugly fashion. You'll +find that @kbd{M-q} (@code{fill-paragraph}) works well even on these +quoted messages, even if they are nested, just as long as all of the +quotes match the value of @code{mh-ins-buf-prefix} (@pxref{Inserting +Letter}). For example, let's assume you have the following in your +draft: + +@example +@group +> Hopefully this gives you an idea of what I'm currently doing. I'm \ +not sure yet whether I'm completely satisfied with my setup, but \ +it's worked okay for me so far. +@end group +@end example + +Running @kbd{M-q} on this paragraph produces: + +@example +@group +> Hopefully this gives you an idea of what I'm currently doing. I'm not +> sure yet whether I'm completely satisfied with my setup, but it's +> worked okay for me so far. +@end group +@end example + +@findex mh-open-line +@findex open-line +@kindex C-c C-o +@kindex C-o + +The command @kbd{C-c C-o} (@code{mh-open-line}) is similar to the +command @kbd{C-o} (@code{open-line}) in that it inserts a newline +after point. It differs in that it also inserts the right number of +quoting characters and spaces so that the next line begins in the same +column as it was. This is useful when breaking up paragraphs in +replies. For example, if this command was used when point was after +the first period in the paragraph above, the result would be this: + +@example +@group +> Hopefully this gives you an idea of what I'm currently doing. + +> I'm not +> sure yet whether I'm completely satisfied with my setup, but it's +> worked okay for me so far. +@end group +@end example + +@node Inserting Letter, Inserting Messages, Editing Message, Editing Drafts +@section Inserting Letter to Which You're Replying @cindex inserting messages -@findex @code{mh-yank-cur-msg} +@cindex replying to messages +@cindex yanking 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{> } +someone mailed to provide some context for your reply. The command +@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by adding an +attribution, yanking a portion of text from the message to which +you're replying, and inserting @code{mh-ins-buf-prefix} (@samp{> }) before each line. -@cindex mark -@cindex Emacs, mark -@cindex point -@cindex Emacs, point -@cindex region -@cindex Emacs, 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 (see @ref{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. - -@node Inserting Messages, Header, Inserting Letter, Editing Textual -@subsubsection Inserting messages +@example +@group +Michael W Thelen <thelenm@@stop.mail-abuse.org> wrote: + +> Hopefully this gives you an idea of what I'm currently doing. I'm not +> sure yet whether I'm completely satisfied with my setup, but it's +> worked okay for me so far. +@end group +@end example + +@vindex mh-extract-from-attribution-verb + +The attribution consists of the sender's name and email address +followed by the content of the option +@code{mh-extract-from-attribution-verb}. This option can be set to +@samp{wrote:}, @samp{a écrit:}, and @samp{schrieb:}. You can also use +the @samp{Custom String} menu item to enter your own verb. + +@vindex mh-ins-buf-prefix + +The prefix @samp{"> "} is the default setting for the option +@code{mh-ins-buf-prefix}. I suggest that you not modify this option +since it is used by many mailers and news readers: messages are far +easier to read if several included messages have all been indented by +the same string. This prefix is not inserted if you use one of the +supercite flavors of @code{mh-yank-behavior} or you have added a +@code{mail-citation-hook} as described below. + +@vindex mh-delete-yanked-msg-window-flag + +You can also turn on the @code{mh-delete-yanked-msg-window-flag} +option to delete the window containing the original message after +yanking it to make more room on your screen for your reply. + +@vindex mh-yank-behavior +@cindex Emacs, packages, supercite +@cindex supercite package + +You can control how the message to which you are replying is yanked +into your reply using @code{mh-yank-behavior}. To include the entire +message, including the entire header, use @samp{Body and +Header}@footnote{If you'd rather have the header cleaned up, use +@kbd{C-u r} instead of @kbd{r} when replying +(@pxref{Replying}).}@footnote{In the past you would use this setting +and set @code{mail-citation-hook} to @samp{supercite}, but this usage +is now deprecated in favor of the @samp{Invoke supercite} setting.}. +Use @samp{Body} to yank just the body without the header. To yank only +the portion of the message following the point, set this option to +@samp{Below Point}. + +Choose @samp{Invoke supercite}@footnote{@emph{Supercite} is a +full-bodied, full-featured, citation package that comes standard with +Emacs.} to pass the entire message and header through supercite. + +If the @samp{Body With Attribution} setting is used, then the message +minus the header is yanked and a simple attribution line is added at +the top using the value of the option +@code{mh-extract-from-attribution-verb}. This is the default. + +If the @samp{Invoke supercite} or @samp{Body With Attribution} +settings are used, the @samp{-noformat} argument is passed to the +@command{repl} program to override a @samp{-filter} or @samp{-format} +argument. These settings also have @samp{Automatically} variants that +perform the action automatically when you reply so that you don't need +to use @kbd{C-c C-y} at all. Note that this automatic action is only +performed if the show buffer matches the message being replied to. +People who use the automatic variants tend to turn on the option +@code{mh-delete-yanked-msg-window-flag} as well so that the show +window is never displayed. + +If the show buffer has a region, the option @code{mh-yank-behavior} is +ignored unless its value is one of @samp{Attribution} variants in +which case the attribution is added to the yanked region. + +@findex trivial-cite +@vindex mail-citation-hook + +If this isn't enough, you can gain full control over the appearance of +the included text by setting @code{mail-citation-hook} to a function +that modifies it. This hook is ignored if the option +@code{mh-yank-behavior} is set to one of the supercite flavors. +Otherwise, this option controls how much of the message is passed to +the hook. The function can find the citation between point and mark +and it should leave point and mark around the modified citation text +for the next hook function. The standard prefix +@code{mh-ins-buf-prefix} is not added if this hook is set. + +For example, if you use the hook function +@uref{http://shasta.cs.uiuc.edu/~lrclause/tc.html, +@code{trivial-cite}} (which is NOT part of Emacs), set +@code{mh-yank-behavior} to @samp{Body and Header}. + +@node Inserting Messages, Signature, Inserting Letter, Editing Drafts +@section Inserting Messages @cindex inserting messages -@findex @code{mh-insert-letter} +@findex mh-insert-letter +@findex mh-yank-behavior +@kindex C-c C-i +@vindex mh-ins-buf-prefix +@vindex mh-invisible-header-fields-compiled 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 Header, Recipients, Inserting Messages, Editing Textual -@subsubsection Editing the header - -@cindex editing header -@findex @code{mh-to-field} - -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 @code{mh-to-fcc} - -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. - -Be sure to leave a row of dashes or a blank line between the header and -the body of the message. - -@node Recipients, Signature, Header, Editing Textual -@subsubsection Checking recipients - -@cindex checking recipients -@cindex @code{whom} -@cindex MH commands, @code{whom} -@findex @code{mh-check-whom} - -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 is created -with the output of @code{whom}. - -@node Signature, , Recipients, Editing Textual -@subsubsection Inserting your signature - -@cindex inserting signature +This command prompts you for the folder and message number, which +defaults to the current message in that folder. It then inserts the +messages, indented by @code{mh-ins-buf-prefix} (@samp{> }) unless +@code{mh-yank-behavior} is set to one of the supercite flavors in +which case supercite is used to format the message. Certain +undesirable header fields (see +@code{mh-invisible-header-fields-compiled}) 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. This command leaves the mark before the +letter and point after it. + +@node Signature, Picture, Inserting Messages, 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 +command @kbd{C-c C-s} (@code{mh-insert-signature}). + @cindex @file{.signature} @cindex files, @file{.signature} -@findex @code{mh-insert-signature} - -You can insert your signature at the current cursor location with the -@kbd{C-c C-s} (@code{mh-insert-signature}) command. The text of your -signature is taken from the file @file{~/.signature}. - -@node Editing MIME, Sending Message, Editing Textual, Draft Editing -@subsection Editing Multimedia Messages - +@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 sources 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 option @code{mh-signature-file-name} 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. Options 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-insert-signature-hook + +The hook @code{mh-insert-signature-hook} is run after the signature is +inserted. Hook 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 option +@code{mh-x-face-file} 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 +@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, +@command{compface}} command. The @uref{http://www.dairiki.org/xface/, +@cite{Online X-Face Converter}} is a useful resource for quick +conversion of images into @samp{X-Face:} header fields. + +Use the @uref{http://quimby.gnus.org/circus/face/make-face, +@command{make-face}} script 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 @command{mhbuild} +@cindex @command{mhn} +@cindex MH commands, @command{mhbuild} +@cindex MH commands, @command{mhn} @cindex MIME @cindex multimedia mail -@cindex @code{mhn} -@cindex MH commands, @code{mhn} - -mh-e has the capability to create multimedia messages. It uses the -@sc{mime} (Multipurpose Internet Mail Extensions) protocol. The + +MH-E has the capability to create multimedia messages. It uses the +@sc{mime} (Multipurpose Internet Mail Extensions) +protocol@footnote{@sc{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 @code{mhn}. Indeed, the -mh-e @sc{mime} commands merely insert @code{mhn} directives which are -later expanded by @code{mhn}. - -Each of the mh-e commands for editing multimedia messages or for -incorporating multimedia objects is prefixed with @kbd{C-c C-m} . - -@cindex content types -@cindex MIME, content types - -Several @sc{mime} objects are defined. They are called @dfn{content -types}. The table in @ref{Customizing Draft Editing} contains a list of -the content types that mh-e currently knows about. Several of the mh-e -commands fill in the content type for you, whereas others require you to -enter one. Most of the time, it should be obvious which one to use -(e.g., use @kbd{image/jpeg} to include a @sc{jpeg} image). If not, you -can refer to @sc{rfc} 1521, -@c Footnotes are very fragile. Hence the duplication. -@c The line break in the footnote was necessary since TeX wasn't creating one. -@ifclear html -@footnote{This @sc{rfc} (Request For Comments) is -available via the @sc{url} @* -@file{ftp://ds.internic.net/rfc/rfc1521.txt}.} -@end ifclear -@ifset html -@footnote{This @sc{rfc} (Request For Comments) is -available via the @sc{url} @* -@file{<A HREF="ftp://ds.internic.net/rfc/rfc1521.txt">ftp://ds.internic.net/rfc/rfc1521.txt</A>}.} -@end ifset -which defines the @sc{mime} protocol, for a list of valid content types. +your recipient reads the message! + +If you were to create a multimedia message with plain MH commands, you +would insert @command{mhbuild} or @command{mhn} directives (henceforth +called @dfn{MH-style directives} into your draft and use the +@command{mhbuild} command in nmh or @command{mhn} command in MH and +GNU mailutils to expand them. MH-E works in much the same way, +although it provides a handful of commands prefixed with @kbd{C-c C-m} +to insert the directives so you don't need to remember the syntax of +them. Remember: you can always add MH-style directives by +hand@footnote{See the section +@uref{@value{MH-BOOK-HOME}/usimim.htm#SeMIMa, Sending MIME Mail} in +the MH book.}. + +@cindex MIME Meta Language (MML) +@cindex MML +@vindex mh-compose-insertion + +In addition to MH-style directives, MH-E also supports MML (@sc{mime} +Meta Language) tags@footnote{ +@ifinfo +@c Although the third argument should default to the +@c first, makeinfo goes to the wrong Info file without it being +@c different--it seems to be getting our own Composing node. +@xref{Composing,,Composing with MML,emacs-mime}. +@end ifinfo +@ifnotinfo +See the section Composing in +@uref{http://www.gnus.org/manual/emacs-mime.html, @cite{The Emacs MIME +Manual}}. +@end ifnotinfo +}. The option @code{mh-compose-insertion} can be used to choose +between them. By default, this option is set to @samp{MML} if it is +supported since it provides a lot more functionality. This option can +also be set to @samp{MH} if MH-style directives are preferred. + +@cindex media types +@cindex MIME, media types + +The MH-E @sc{mime} commands require a @dfn{media type} for each body +part or attachment. For example, a PDF document is of type +@samp{application/pdf} and an HTML document is of type +@samp{text/html}. Some commands 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}. + +Whether the media type is chosen automatically, or you choose it from +a list, 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 +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 +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. -Remember: you can always add @code{mhn} directives by hand. - -@menu -* Forwarding MIME:: -* FTP:: -* Tar:: -* Other MIME Objects:: -* Sending MIME:: -@end menu - -@node Forwarding MIME, FTP, Editing MIME, Editing MIME -@subsubsection Forwarding multimedia messages - -@findex @code{mh-mhn-compose-forw} - -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. - -@node FTP, Tar, Forwarding MIME, Editing MIME -@subsubsection Including an ftp reference - -@cindex @code{ftp} -@cindex Unix commands, @code{ftp} -@cindex MIME, @code{ftp} -@findex @code{mh-mhn-compose-anon-ftp} - -You can even have your message initiate an @code{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 content type, and the content description. - -@node Tar, Other MIME Objects, FTP, Editing MIME -@subsubsection Including tar files - -@cindex @code{tar} -@cindex Unix commands, @code{tar} -@cindex MIME, @code{tar} -@cindex @code{ftp} -@cindex Unix commands, @code{ftp} -@cindex MIME, @code{ftp} -@findex @code{mh-mhn-compose-external-compressed-tar} - -If the remote file (@pxref{FTP}) 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. - -@node Other MIME Objects, Sending MIME, Tar, Editing MIME -@subsubsection Including other multimedia objects - +You can also create your own @sc{mime} body parts. In the following +example, I describe how you can create and edit a @samp{text/enriched} +body part to liven up your plain text messages with boldface, +underlining, and italics. I include an Emacs function which inserts +enriched text tags. + +@smalllisp +@group +(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") + ("u" . "underline") + ("s" . "smaller") ("B" . "bigger") + ("f" . "fixed") + ("c" . "center")) + "Alist of (final-character . tag) choices for add-enriched-text. +Additional types can be found in RFC 1563.") + +(defun add-enriched-text (begin end) + "Add enriched text tags around region. +The tag 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 tag 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 tag} + (goto-char (point-max)) ; @r{move to end of text} + (insert "</" type ">")))) ; @r{insert terminating tag} +@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-@key{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-m C-m} +(@code{mh-mml-to-mime})@footnote{Use @kbd{C-c C-e} +(@code{mh-mh-to-mime}) if you're using MH-style directives.} 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}. + +@subheading Including Files + +@cindex MIME, images +@cindex MIME, sound +@cindex MIME, video +@cindex attachments, inserting @cindex images -@cindex MIME, images @cindex sound -@cindex MIME, sound @cindex video -@cindex MIME, video -@findex @code{mh-mhn-compose-insertion} - -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 content type, and a -content description of the object. - -@node Sending MIME, , Other MIME Objects, Editing MIME -@subsubsection Readying multimedia messages for sending +@findex mh-compose-insertion +@kindex C-c C-m C-i +@kindex C-c C-m i + +Binaries, images, sound, and video can be inserted in your message +with the command @kbd{C-c C-m C-i} (@code{mh-compose-insertion}). You +are prompted for the filename containing the object, the media type if +it cannot be determined automatically, and a content description. If +you're using MH-style directives, you will also be prompted for +additional attributes. + +@subheading Forwarding Multimedia Messages + +@findex mh-compose-forward +@kindex C-c C-m C-f +@kindex C-c C-m f + +Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m +C-f} (@code{mh-compose-forward}). You are prompted for a content +description, the name of the folder in which the messages to forward +are located, and a range of messages, which defaults to the current +message in that folder. @xref{Ranges}. + +@subheading Including an FTP Reference + +@cindex @command{ftp} +@cindex MIME, @command{ftp} +@cindex Unix commands, @command{ftp} +@findex mh-mh-compose-anon-ftp +@kindex C-c C-m C-g +@kindex C-c C-m g + +You can have your message initiate an @command{ftp} transfer when the +recipient reads the message. To do this, use the command @kbd{C-c C-m +C-g} (@code{mh-mh-compose-anon-ftp}). You are prompted for the remote +host and filename, 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-mh-compose-external-compressed-tar +@kindex C-c C-m C-t +@kindex C-c C-m t + +If the remote file is a compressed tar file, you can use @kbd{C-c C-m +C-t} (@code{mh-mh-compose-external-compressed-tar}). Then, in addition +to retrieving the file via anonymous @emph{ftp} as per the command +@kbd{C-c C-m C-g} (@code{mh-mh-compose-anon-ftp}), the file will also +be uncompressed and untarred. You are prompted for the remote host and +filename and the content description. + +@subheading Including Other External Files + +@findex mh-mh-compose-external-type +@kindex C-c C-m C-x +@kindex C-c C-m x + +The command @kbd{C-c C-m C-x} (@code{mh-mh-compose-external-type}) is +a general utility for referencing external files. In fact, all of the +other commands that insert tags to access external files call this +command. You are prompted for the access type, remote host and +filename, and content type. If you provide a prefix argument, you are +also prompted for a content description, attributes, parameters, and a +comment. + +@subheading Previewing Multimedia Messages When you are finished editing a @sc{mime} message, it might look like this: -@example -@group @cartouche - 3 24Aug root received fax files on Wed Aug 24 11:00:13 - 4+ 24Aug To:wohler Test<<This is a test message to get the wh - - - - - ---%%-@{+inbox@} 4 msgs (1-4) (MH-Folder Show)--Bot------------------- +@smallexample +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)--All-------------------------------------- - +Here is the SETI@@Home logo: + +<#part type="image/x-xpm" filename="~/lib/images/setiathome.xpm" +disposition=inline description="SETI@@home logo"> +<#/part> +--:** @{draft@} (MH-Letter)--L8--All---------------------------------- + +@end smallexample @end cartouche -@i{mh-e @sc{mime} draft} -@end group -@end example - -@cindex @code{mhn} -@cindex MH commands, @code{mhn} -@findex @code{mh-edit-mhn} - -The lines added by the previous commands are @code{mhn} directives and -need to be converted to @sc{mime} directives before sending. This is -accomplished by the command @kbd{C-c C-e} (@code{mh-edit-mhn}), which -runs @code{mhn} on the message. 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. - -@example -@group +@i{MH-E @sc{mime} draft} + +@findex mh-mml-to-mime +@kindex C-c C-m C-m +@kindex C-c C-m m + +Typically, you send a message with attachments just like any other +message (@pxref{Sending Message}). + +However, you may take a sneak preview of the @sc{mime} encoding if you +wish by running the command @kbd{C-c C-m C-m} (@code{mh-mml-to-mime}). +The following screen shows the @sc{mime} encoding specified by the +tags. You can see why mail user agents are usually built to hide these +details from the user. + @cartouche +@smallexample To: wohler cc: Subject: Test of MIME MIME-Version: 1.0 -Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0" -Content-ID: <1623.777796162.0@@newt.com> - -------- =_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@@newt.com> -Content-Description: Nonexistent ftp test file - -------- =_aaaaaaaaaa0 -Content-Type: audio/basic -Content-ID: <1623.777796162.2@@newt.com> -Content-Description: Test sound bite +Content-Type: multipart/mixed; boundary="=-=-=" +-------- +--=-=-= + +Here is the SETI@@Home logo: + + +--=-=-= +Content-Type: image/x-xpm +Content-Disposition: inline; filename=setiathome.xpm Content-Transfer-Encoding: base64 - -Q3JlYXRpdmUgVm9pY2UgRmlsZRoaAAoBKREBQh8AgwCAgH9/f35+fn59fX5+fn5+f39/f39/f3 -f4B/f39/f39/f39/f39/f39+f39+f39/f39/f4B/f39/fn5/f39/f3+Af39/f39/gH9/f39/fn ------@{draft@} (MH-Letter)--Top-------------------------------------- - +Content-Description: SETI@@home logo + +LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2NCAy +--:-- @{draft@} (MH-Letter)--L2--Top---------------------------------- + +@end smallexample @end cartouche -@i{mh-e @sc{mime} draft ready to send} -@end group +@i{MH-E @sc{mime} draft ready to send} + +This action can be undone by running @kbd{C-_} (@code{undo}). + +@cindex @command{mhbuild} +@cindex @command{mhn} +@cindex MH commands, @command{mhbuild} +@cindex MH commands, @command{mhn} +@findex mh-mh-to-mime +@findex mh-mh-to-mime-undo +@kindex C-c C-e +@kindex C-c C-m C-u +@kindex C-c C-m u + +If you're using MH-style directives, use @kbd{C-c C-e} +(@code{mh-mh-to-mime}) instead of @kbd{C-c C-m C-m}. This runs the +command @command{mhbuild} (@command{mhn}) on the message which expands +the tags@footnote{See the section +@uref{@value{MH-BOOK-HOME}/usimim.htm#SeMIMa, Sending MIME Mail} in +the MH book.}. This action can be undone by running @kbd{C-c C-m C-u} +(@code{mh-mh-to-mime-undo}), which works 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-mh-to-mime-args + +If you wish to pass additional arguments to @command{mhbuild} +(@command{mhn}) to affect how it builds your message, use the option +@code{mh-mh-to-mime-args}. For example, you can build a consistency +check into the message by setting @code{mh-mh-to-mime-args} to +@samp{-check}. The recipient of your message can then run +@samp{mhbuild -check} on the message---@command{mhbuild} +(@command{mhn}) will complain if the message has been corrupted on the +way. The command @kbd{C-c C-e} (@code{mh-mh-to-mime}) only consults +this option when given a prefix argument (as in @kbd{C-u C-c C-e}). + +@vindex mh-mh-to-mime-hook + +The hook @code{mh-mh-to-mime-hook} is called after the message has +been formatted by @kbd{C-c C-e} (@code{mh-mh-to-mime}) + +@node Sending PGP, Checking Recipients, 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 +@findex mh-mml-secure-message-sign +@findex mh-mml-secure-message-signencrypt +@kindex C-c C-m C-e +@kindex C-c C-m C-s +@kindex C-c C-m e e +@kindex C-c C-m e s +@kindex C-c C-m s e +@kindex C-c C-m s s + +The command @kbd{C-c C-m C-s} (@code{mh-mml-secure-message-sign}) +inserts the following tag: + +@example +<#secure method=pgpmime mode=sign> +@end example + +This is used to sign your message digitally. Likewise, the command +@kbd{C-c C-m C-e} (@code{mh-mml-secure-message-encrypt}) inserts the +following tag: + +@example +<#secure method=pgpmime mode=encrypt> @end example -@findex @code{mh-revert-mhn-edit} - -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}). - -@node Sending Message, Killing Draft, Editing MIME, Draft Editing -@subsection Sending a Message +This is used to encrypt your message. Finally, the command @kbd{C-c +C-m s e} (@code{mh-mml-secure-message-signencrypt}) inserts the +following tag: + +@example +<#secure method=pgpmime mode=signencrypt> +@end example + +@findex mh-mml-unsecure-message +@kindex C-c C-m C-n +@kindex C-c C-m n + +This is used to sign and encrypt your message. In each of these cases, +a proper multipart message is created for you when you send the +message. Use the command @kbd{C-c C-m C-n} +(@code{mh-mml-unsecure-message}) to remove these tags. Use a prefix +argument (as in @kbd{C-u C-c C-m s e}) to be prompted for one of the +possible security methods (see @code{mh-mml-method-default}). + +@vindex mh-mml-method-default + +The option @code{mh-mml-method-default} is used to select between a +variety of mail security mechanisms. The default is @samp{PGP (MIME)} +if it is supported; otherwise, the default is @samp{None}. Other +mechanisms include vanilla @samp{PGP} and @samp{S/MIME}. + +@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 turn on the option @code{pgg-encrypt-for-me} 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 Checking Recipients, Sending Message, Sending PGP, 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 command @kbd{C-c C-w} (@code{mh-check-whom}) 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 Sending Message, Killing Draft, Checking Recipients, 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 +command @kbd{C-c C-c} (@code{mh-send-letter}). You can give a prefix +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 -@findex @code{mh-send-letter} - -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. - -@node Killing Draft, , Sending Message, Draft Editing -@subsection Killing the Draft +@cindex spell check +@vindex mh-before-send-letter-hook + +The hook @code{mh-before-send-letter-hook} is run at the beginning of +the command @kbd{C-c C-c}. For example, if you want to check your +spelling in your message before sending, add the function +@code{ispell-message}. + +@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 @code{mh-fully-kill-draft} - -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 Moving Mail, Searching, Draft Editing, Using mh-e -@section Moving Your Mail Around - -@cindex processing mail - -This section covers how messages and folders can be moved about or -manipulated. Messages may be incorporated into your @file{+inbox}, -deleted, and refiled. Messages containing @code{shar} or -@code{uuencode} output can be stored. Folders can be visited, sorted, -packed, or deleted. Here's a list of the available commands to do these -things: - -@c Stephen thinks that ? should be documented here, since it also shows -@c which folders a message will be refiled to. XXX +@findex kill-buffer +@findex mh-fully-kill-draft +@kindex C-c C-q +@kindex C-x k + +If for some reason you are not happy with the draft, you can use the +command @kbd{C-c C-q} (@code{mh-fully-kill-draft}) to kill the draft +buffer and delete the draft message. Use the command @kbd{C-x k} +(@code{kill-buffer}) if you don't want to delete the draft message. + +@node Aliases, Identities, Editing Drafts, Top +@chapter Aliases + +@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 @key{SPC} +@findex mh-letter-complete-or-space +@item @key{SPC} +Perform completion or insert space (@code{mh-letter-complete-or-space}). +@c ------------------------- +@kindex M-@key{TAB} +@findex mh-letter-complete +@item M-@key{TAB} +Perform completion on header field or word preceding point +(@code{mh-letter-complete}). +@c ------------------------- +@findex mh-alias-apropos +@item mh-alias-apropos +Show all aliases or addresses that match a regular expression. +@c ------------------------- +@findex mh-alias-grab-from-field +@item mh-alias-grab-from-field +Add alias for the sender of the current message +@c ------------------------- +@findex mh-alias-reload +@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 +On means don't consider case significant in MH alias completion +(default: @samp{on}). +@c ------------------------- +@item mh-alias-expand-aliases-flag +On means to expand aliases entered in the minibuffer (default: +@samp{off}). +@c ------------------------- +@item mh-alias-flash-on-comma +Specify whether to flash address or warn on translation (default: @samp{Flash +but Don't Warn If No Alias}). +@c ------------------------- +@item mh-alias-insert-file +Filename used to store a new MH-E alias (default: @samp{Use Aliasfile +Profile Component}). +@c ------------------------- +@item mh-alias-insertion-location +Specifies where new aliases are entered in alias files (default: +@samp{Alphabetical}). +@c ------------------------- +@item mh-alias-local-users +If @samp{on}, local users are added to alias completion (default: +@samp{on}). +@c ------------------------- +@item mh-alias-local-users-prefix +String prefixed to the real names of users from the password file +(default: @samp{"local."}. +@c ------------------------- +@item mh-alias-passwd-gecos-comma-separator-flag +On 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 +Hook run by @code{mh-alias-reload} after loading 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 @key{TAB} + +In order to use minibuffer prompting for recipients and the subject +line in the minibuffer, turn on the option +@code{mh-compose-prompt-flag} (@pxref{Composing}), and use the +@key{TAB} (@code{minibuffer-complete}) command to complete aliases +(and optionally local logins) when prompted for the recipients. Turn +on the option @code{mh-alias-expand-aliases-flag} 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-@key{TAB}} (@code{mh-letter-complete}) or @key{SPC} +(@code{mh-letter-complete-or-space}). + +As MH ignores case in the aliases, so too does MH-E. However, you may +turn off the option @code{mh-alias-completion-ignore-case-flag} to +make case significant which can be used to segregate completion of +your aliases. You might use uppercase for mailing lists and lowercase +for people. For example, you might 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 + +When this option is turned off, if you were to type @kbd{M} in the +@samp{To:} field and then @kbd{M-@key{TAB}}, then you'd get the list; +if you started with @kbd{m} and then entered @kbd{M-@key{TAB}}, then +you'd get Mark's address. Note that this option affects completion +only. If you were to enter @kbd{Mark.Baushke}, it would still be +identified with your @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 +(@code{mh-letter-confirm-address} 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 option +@code{mh-alias-flash-on-comma} which provides three choices: +@samp{Flash but Don't Warn If No Alias}, @samp{Flash and Warn If No +Alias}, and @samp{Don't Flash Nor Warn If No Alias}. + +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 option +@code{mh-alias-local-users-prefix}. This option can also be set to +@samp{Use Login}. + +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 option @code{mh-alias-local-users-prefix} +will produce the associated aliases: + +@table @code +@item "local." +local.peter.galbraith +@c ------------------------- +@item "" +peter.galbraith +@c ------------------------- +@item Use Login +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 off the option +@code{mh-alias-local-users}. 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 reloads aliases +automatically whenever an alias lookup occurs if an alias source has +changed. However, you can reload your aliases manually by calling the +command @kbd{M-x mh-alias-reload} directly. This command runs +@code{mh-alias-reloaded-hook} 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}). + +Earlier, the alias prefix @samp{local} was presented. You can use +other prefixes to organize your aliases or disambiguate entries. You +might use prefixes for locales, jobs, or activities. For example, I +have: + +@example +; Work +attensity.don.mitchell: Don Mitchell <dmitchell@@stop.mail-abuse.com> +isharp.don.mitchell: Don Mitchell <donaldsmitchell@@stop.mail-abuse.com> +... +; Sport +diving.ken.mayer: Ken Mayer <kmayer@@stop.mail-abuse.com> +sailing.mike.maloney: Mike Maloney <mmaloney@@stop.mail-abuse.com> +... +; Personal +ariane.kolkmann: Ariane Kolkmann <ArianeKolkmann@@stop.mail-abuse.com> +... +@end example + +Using prefixes instead of postfixes helps you explore aliases during +completion. If you forget the name of an old dive buddy, you can enter +@samp{div} and then @key{SPC} to get a listing of all your dive buddies. + +An alias for the sender of the current message is added automatically +by clicking on the @samp{Grab From alias} tool bar 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. + +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{Alphabetical} by default. If you organize your alias file in +other ways, then the settings @samp{Top} and @samp{Bottom} might be +more appropriate. + +@heading Querying Aliases + +@cindex regular expressions, @code{mh-alias-apropos} + +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 +@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/Regexps.html, +Syntax of Regular Expressions} in +@cite{The GNU Emacs Manual}). +@end ifhtml + +@node Identities, Speedbar, Aliases, Top +@chapter Identities + +@cindex identities +@cindex multiple personalities + +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. + +A couple of commands are used to insert identities in MH-Letter mode +which are also found in the @samp{Identity} menu. @table @kbd -@item i -Incorporate new mail into folder (@code{mh-inc-folder}). - -@item d -Delete message (@code{mh-delete-msg}). - -@item C-d -Delete message, don't move to next message (@code{mh-delete-msg-no-motion}). - -@item M-s -Find messages that meet search criteria (@code{mh-search-folder}). - -@item o -Output (refile) message to folder (@code{mh-refile-msg}). - -@item c -Copy message to folder (@code{mh-copy-msg}). - -@item C-o -Output (write) message to file (@code{mh-write-msg-to-file}). - -@item ! -Repeat last output command (@code{mh-refile-or-write-again}). - -@item l -Print message with @code{lpr} (@code{mh-print-msg}). - -@item | -Pipe message through shell command (@code{mh-pipe-msg}). - -@item M-n -Unpack message created with @code{uudecode} or @code{shar} -(@code{mh-store-msg}). - -@item M-l -List all folders (@code{mh-list-folders}). - -@item M-f -Visit folder (@code{mh-visit-folder}). - -@item M-r -Regenerate scan lines (@code{mh-rescan-folder}). - -@item M-x mh-sort-folder -Sort folder. - -@item M-p -Pack folder (@code{mh-pack-folder}). - -@item M-k -Remove folder (@code{mh-kill-folder}). - -@item x -Execute pending refiles and deletes (@code{mh-execute-commands}). - -@item u -Undo pending refile or delete (@code{mh-undo}). - -@item M-u -Undo all pending refiles and deletes (@code{mh-undo-folder}). - -@item q -Quit (@code{mh-quit}). +@kindex C-c C-d +@findex mh-insert-identity +@item C-c C-d +Insert fields specified by given identity (@code{mh-insert-identity}). +@c ------------------------- +@cindex @samp{Identity > Insert Auto Fields} menu item +@cindex menu item, @samp{Identity > Insert Auto Fields} +@kindex C-c M-d +@findex mh-insert-auto-fields +@item C-c M-d +Insert custom fields if recipient found in @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}). +@c ------------------------- +@item mh-auto-fields-prompt-flag +On means to prompt before sending if fields inserted (default: +@samp{on}) +@c ------------------------- +@item mh-identity-default +Default identity to use when @code{mh-letter-mode} is called (default: +@samp{None}). +@c ------------------------- +@item mh-identity-handlers +Handler functions for fields in @code{mh-identity-list}. +@c ------------------------- +@item mh-identity-list +List of identities (default: @code{nil}). +@end vtable + +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 option @code{mh-identity-list}. 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 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>}. +@c ------------------------- +@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. +@c ------------------------- +@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:}. +@c ------------------------- +@item Attribution Verb +This value overrides the setting of +@code{mh-extract-from-attribution-verb}. @xref{Inserting Letter}. +@c ------------------------- +@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}. +@c ------------------------- +@item GPG Key ID +Specify a different key to sign or encrypt messages. +@end table + +@cindex Identity menu +@cindex menu, Identity + +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. + +@cindex @samp{Identity > Save as Default} menu item +@cindex menu item, @samp{Identity > Save as Default} +@cindex @samp{Identity > Set Default for Session} menu item +@cindex menu item, @samp{Identity > Set Default for Session} +@cindex @samp{Identity > Customize Identities} menu item +@cindex menu item, @samp{Identity > Customize Identities} + +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 option +@code{mh-identity-default} in the usual fashion. If you find that you +need to add another identity, the menu item @samp{Customize +Identities} is available for your convenience. + +@cindex regular expressions, @code{mh-auto-fields-list} + +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 +@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/Regexps.html, +Syntax of Regular Expressions} in +@cite{The GNU Emacs Manual}). +@end ifhtml +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. +@c ------------------------- +@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. +@c ------------------------- +@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. +@c ------------------------- +@item Other Field +Other header fields may be added using this menu item. @end table -@menu -* Incorporating:: -* Deleting:: -* Organizing:: -* Printing:: -* Files and Pipes:: -* Finishing Up:: -@end menu - -@node Incorporating, Deleting, Moving Mail, Moving Mail -@subsection Incorporating Your Mail - -@cindex incorporating -@findex @code{mh-inc-folder} - -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 Emacs, notification of new mail -@cindex notification of new mail -@cindex new mail -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -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 @code{display-time} - -@lisp -(display-time) -@end lisp - -@node Deleting, Organizing, Incorporating, Moving Mail -@subsection Deleting Your Mail - -@cindex deleting -@findex @code{mh-delete-msg} -@findex @code{mh-delete-msg-no-motion} - -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 message is displayed. If the previous command had been -@kbd{p}, then the next message displayed is the message previous to the -message just deleted. If you specify a prefix argument, you will be -prompted for a sequence (@pxref{Sequences}) to delete (for example, -@kbd{C-u d frombob RET}). The @kbd{x} command actually carries out the -deletion (@pxref{Finishing Up}). @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. - -@node Organizing, Printing, Deleting, Moving Mail -@subsection Organizing Your Mail with Folders - -@cindex using folders -@cindex @code{folder} -@cindex MH commands, @code{folder} -@cindex @code{refile} -@cindex MH commands, @code{refile} -@findex @code{mh-refile-msg} - -mh-e has analogies for each of the MH @code{folder} and @code{refile} -commands. 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. - -@findex @code{mh-refile-or-write-again} - -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{Files and -Pipes}). Or, place the messages into a sequence (@ref{Sequences}) and -specify a prefix argument to @kbd{o}, in which case you'll be prompted -for the name of the sequence (for example, @kbd{C-u o search RET}). - -@findex @code{mh-copy-msg} - -If you wish to copy a message to another folder, you can use the @kbd{c} -(@code{mh-copy-msg}) command (see the @code{-link} argument to -@code{refile}(1)). You are prompted for a folder, and you can specify a -prefix argument if you want to copy a sequence into another folder. In -this case, you are then prompted for the sequence. Note that unlike the -@kbd{o} command, the copy takes place immediately. The original copy -remains in the current folder. - -@findex @code{mh-visit-folder} - -When you want to read the messages that you have refiled into folders, -use the @kbd{M-f} (@code{mh-visit-folder}) command to visit the folder. -You are prompted for the folder name. - -@findex @code{mh-list-folders} -@findex @code{mh-kill-folder} -@findex @code{mh-visit-folder} -@findex @code{mh-sort-folder} -@findex @code{mh-pack-folder} -@findex @code{mh-rescan-folder} - -Other commands you can perform on folders include: @kbd{M-l} -(@code{mh-list-folders}), to list all the folders in your mail -directory; @kbd{M-k} (@code{mh-kill-folder}), to remove a folder; -@kbd{M-x mh-sort-folder}, to sort the messages by date (see -@code{sortm}(1) to see how to sort by other criteria); @kbd{M-p} -(@code{mh-pack-folder}), to pack a folder, removing gaps from the -numbering sequence; and @kbd{M-r} (@code{mh-rescan-folder}), to rescan -the folder, which is useful to grab all messages in your @file{+inbox} -after processing your new mail for the first time. If you don't want to -rescan the entire folder, give @kbd{M-r} or @kbd{M-p} a prefix argument -and you'll be prompted for a range of messages to display (for instance, -@kbd{C-u M-r last:50 RET}). - -@node Printing, Files and Pipes, Organizing, Moving Mail -@subsection Printing Your Mail - -@cindex printing -@cindex @code{mhl} -@cindex MH commands, @code{mhl} -@cindex @code{lpr} -@cindex Unix commands, @code{lpr} -@findex @code{mh-print-msg} - -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 @code{mhl} -and printed with the @code{lpr} command. You can print all the messages -in a sequence by specifying a prefix argument, in which case you are -prompted for the name of the sequence (as in @kbd{C-u l frombob RET}). - -@node Files and Pipes, Finishing Up, Printing, Moving Mail -@subsection Files and Pipes - -@cindex using files -@cindex using pipes -@findex @code{mh-write-msg-to-file} - -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 RET}). -Subsequent writes to the same file can be made with the @kbd{!} -command. - -@findex @code{mh-pipe-msg} - -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 @code{shar} -@cindex Unix commands, @code{shar} -@cindex @code{uuencode} -@cindex Unix commands, @code{uuencode} -@findex @code{mh-store-msg} - -If the message is a shell archive @code{shar} or has been run through -@code{uuencode} use @kbd{M-n} (@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. - -@node Finishing Up, , Files and Pipes, Moving Mail -@subsection Finishing Up - -@cindex expunging refiles and deletes -@findex @code{mh-undo} -@findex @code{mh-undo-folder} - -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 belong to a -given sequence by specifying a prefix argument. You'll be prompted for -the name of the sequence (as in @kbd{C-u u frombob RET}). -Alternatively, you can use @kbd{M-u} (@code{mh-undo-folder}) to undo all -refiles or deletes in the current folder. - -@findex @code{mh-execute-commands} - -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{M-r} or @kbd{M-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. - -@findex @code{mh-rmail} -@findex @code{mh-quit} - -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. - -@node Searching, Sequences, Moving Mail, Using mh-e -@section Searching Through Messages +These fields can only be added after the recipient is known. Because +you can continue to add recipients as you edit the draft, MH-E waits +until the message is sent to perform the auto-insertions. This seems +strange at first, but you'll get used to it. There are two ways to +help you feel that the desired fields are added. The first is the +action when the message is sent: if any fields are added +automatically, you are given a chance to see and to confirm these +fields before the message is actually sent. You can do away with this +confirmation by turning off the option +@code{mh-auto-fields-prompt-flag}. The second method is manual: once +the header contains one or more recipients, you may run the command +@kbd{C-c M-d} (@code{mh-insert-auto-fields}) or choose the +@samp{Identity -> Insert Auto Fields} menu item to insert these fields +manually. However, if you use this command, the automatic insertion +when the message is sent is disabled. + +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. + +The option @code{mh-identity-handlers} is used to change the way that +fields, signatures, and attributions in @code{mh-identity-list} are +added. To customize @code{mh-identity-handlers}, replace the name of +an existing handler function associated with the field you want to +change with the name of a function you have written. You can also +click on an @samp{INS} button and insert a field of your choice and +the name of the function you have written to handle it. + +The @samp{Field} field can be any field that you've used in your +@code{mh-identity-list}. The special fields @samp{:attribution-verb}, +@samp{:signature}, or @samp{:pgg-default-user-id} are used for the +@code{mh-identity-list} choices @samp{Attribution Verb}, +@samp{Signature}, and @samp{GPG Key ID} respectively. + +The handler associated with the @samp{:default} field is used when no +other field matches. + +The handler functions are passed two or three arguments: the field +itself (for example, @samp{From}), or one of the special fields (for +example, @samp{:signature}), and the action @samp{'remove} or +@samp{'add}. If the action is @samp{'add}, an additional argument +containing the value for the field is given. + +@node Speedbar, Menu Bar, Identities, Top +@chapter The Speedbar + +@cindex folder navigation +@cindex speedbar + +You can also use the speedbar +@ifnothtml +(@pxref{Speedbar, , Speedbar Frames, emacs, The GNU Emacs Manual},) +@end ifnothtml +@ifhtml +(see the section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Speedbar.html, +Speedbar Frames} in @cite{The GNU Emacs Manual}) +@end ifhtml +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 @kbd{Mouse-2} to visit that folder in a similar +fashion to the command @kbd{F v} (@code{mh-visit-folder}) +(@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. + +@table @samp +@findex mh-speed-view +@item Visit Folder (@key{RET}) +Visits the selected folder just as if you had used @kbd{F v} +(@code{mh-speed-view}). +@c ------------------------- +@findex mh-speed-expand-folder +@item Expand Nested Folders (@kbd{+}) +Expands the selected folder in the speedbar, exposing the children +folders inside it (@code{mh-speed-expand-folder}). +@c ------------------------- +@findex mh-speed-contract-folder +@item Contract Nested Folders (@kbd{-}) +Contracts or collapses the selected folder in the speedbar, hiding the +children folders inside it (@code{mh-speed-contract-folder}). +@c ------------------------- +@findex mh-speed-refresh +@item Refresh Speedbar (@kbd{r}) +Regenerates the list of folders in the speedbar. Run this command if +you've added or deleted a folder, or want to update the unseen message +count before the next automatic update (@code{mh-speed-refresh}). +@end table + +You can click on @kbd{Mouse-3} to bring up a context menu that +contains these items. Dismiss the speedbar with @kbd{C-x 5 0} +(@code{delete-frame}). + +@cindex @command{flists} +@cindex MH commands, @command{flists} +@cindex @samp{mh-speedbar} customization group +@cindex customization group, @samp{mh-speedbar} + +The MH-E speedbar uses the MH command @command{flists}@footnote{See +the section @uref{@value{MH-BOOK-HOME}/morseq.htm#flist, Searching for +Sequences with flist} in the MH book.} to generate the list of +folders. The @samp{mh-speedbar} customization group contains the +following option which controls how often the speedbar calls +@command{flists}. + +@vtable @code +@item mh-speed-update-interval +Time between speedbar updates in seconds (default: 60). Set to 0 to +disable automatic update. +@end vtable + +You can modify the appearance of the folders in the speedbar by +customizing the following faces. + +@vtable @code +@item mh-speedbar-folder +Basic folder face. +@c ------------------------- +@item mh-speedbar-folder-with-unseen-messages +Folder face when folder contains unread messages. +@c ------------------------- +@item mh-speedbar-selected-folder +Selected folder face. +@c ------------------------- +@item mh-speedbar-selected-folder-with-unseen-messages +Selected folder face when folder contains unread messages. +@end vtable + +@node Menu Bar, Tool Bar, Speedbar, Top +@chapter The Menu Bar + +@cindex menu bar + +@cindex Folder menu +@cindex Identity menu +@cindex Letter menu +@cindex MH-Folder mode +@cindex MH-Letter mode +@cindex MH-Search mode +@cindex Message menu +@cindex Search menu +@cindex Sequence menu +@cindex menu, Folder +@cindex menu, Identity +@cindex menu, Letter +@cindex menu, Message +@cindex menu, Search +@cindex menu, Sequence +@cindex modes, MH-Folder +@cindex modes, MH-Letter +@cindex modes, MH-Search + +For those of you who prefer to mouse and menu instead of using the +meta-coke-bottle-bucky keys, MH-E provides menu items for most of its +functions. The MH-Folder buffer adds the @samp{Folder}, +@samp{Message}, and @samp{Sequence} menus. The MH-Letter buffer adds +the @samp{Identity} and @samp{Letter} menus. The MH-Search buffer adds +the @samp{Search} menu. There's no need to list the actual items here, +as you can more easily see them for yourself, and the functions are +already described elsewhere in this manual. + +For a description of the menu bar, please +@ifnothtml +@xref{Menu Bar, , The Menu Bar, emacs, The GNU Emacs Manual}. +@end ifnothtml +@ifhtml +see the section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Menu-Bar.html, +The Menu Bar} in @cite{The GNU Emacs Manual}. +@end ifhtml + +The Emacs manual describes how to get online help for a particular +menu item. You can also look up a menu item in the index of this +manual in two ways: all of the menu items are listed alphabetically, +and you can also browse all of the items under the index entry +@samp{menu item}. + +@node Tool Bar, Searching, Menu Bar, Top +@chapter The Tool Bar + +@cindex tool bar +@cindex @samp{mh-tool-bar} customization group +@cindex customization group, @samp{mh-tool-bar} + +Emacs also provides a graphical tool bar. For a description of the +tool bar, please +@ifnothtml +@xref{Tool Bars, , Tool Bars, emacs, The GNU Emacs Manual}. +@end ifnothtml +@ifhtml +see the section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Tool-Bars.html, +Tool Bars} in @cite{The GNU Emacs Manual}. +@end ifhtml + +MH-E adds several icons to this tool bar; you can modify the MH-E +aspects of the tool bar via the @samp{mh-tool-bar} customization group. + +@vtable @code +@item mh-tool-bar-folder-buttons +List of buttons to include in MH-Folder tool bar (default: a checklist +too long to list here). +@c ------------------------- +@item mh-tool-bar-letter-buttons +List of buttons to include in MH-Letter tool bar (default: a checklist +too long to list here). +@c ------------------------- +@item mh-tool-bar-search-function +Function called by the tool bar search button (default: +@code{mh-search}). +@c ------------------------- +@item mh-xemacs-tool-bar-position +Tool bar location (default: @samp{Same As Default Tool Bar}). +@c ------------------------- +@item mh-xemacs-use-tool-bar-flag +If on, use tool bar (default: on, if supported). +@end vtable + +In GNU Emacs, icons for some of MH-E's functions are added to the tool +bar. In XEmacs, you have the opportunity to create a separate tool bar for +the MH-E icons. + +In either case, you can select which of these functions you'd like to +see by customizing the options @code{mh-tool-bar-folder-buttons} and +@code{mh-tool-bar-letter-buttons}. As you probably guessed, the former +customizes the tool bar in MH-Folder mode and the latter in MH-Letter +mode. Both of these options present you with a list of functions; +check the functions whose icons you want to see and clear the check +boxes for those you don't. + +The function associated with the searching icon can be set via the +option @code{mh-tool-bar-search-function}. By default, this is set to +@code{mh-search}. @xref{Searching}. You can also choose @samp{Other +Function} from the @samp{Value Menu} and enter a function of your own +choosing. + +XEmacs provides a couple of extra options. The first, +@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E +icons at all. By default, this option is turned on if the window +system supports tool bars. If your system doesn't support tool bars, +then you won't be able to turn on this option. + +The second extra option is @code{mh-xemacs-tool-bar-position} which +controls the placement of the tool bar along the four edges of the +frame. You can choose from one of @samp{Same As Default Tool Bar}, +@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this +variable is set to anything other than @samp{Same As Default Tool Bar} +and the default tool bar is in a different location, then two tool +bars will be displayed: the MH-E tool bar and the default tool bar." + +@node Searching, Threading, Tool Bar, Top +@chapter Searching Through Messages @cindex searching -@findex @code{mh-search-folder} - -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{M-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: - -@example -@group + +@findex mh-search +@kindex F s + +Earlier, the command @kbd{F s} (@code{mh-search}) was introduced which +helps you find messages that lie buried in your folders +(@pxref{Folders}). This chapter covers this command in more detail. +Several commands are used to compose the search criteria and to start +searching. A couple of them can be found in the @samp{Search} menu. + +@table @kbd +@kindex C-c ? +@findex mh-help +@item C-c ? +Display cheat sheet for the MH-E commands (@code{mh-help}). +@c ------------------------- +@cindex @samp{Search > Perform Search} menu item +@cindex menu item, @samp{Search > Perform Search} +@kindex C-c C-c +@findex mh-index-do-search +@item C-c C-c +Find messages using @code{mh-search-program} +(@code{mh-index-do-search}). +@c ------------------------- +@cindex @samp{Search > Search with pick} menu item +@cindex menu item, @samp{Search > Search with pick} +@kindex C-c C-p +@findex mh-pick-do-search +@item C-c C-p +Find messages using @command{pick} (@code{mh-pick-do-search}). +@c ------------------------- +@kindex C-c ? +@findex mh-help +@item C-c ? +Display cheat sheet for the MH-E commands (@code{mh-help}). +@c ------------------------- +@kindex C-c C-f C-a +@kindex C-c C-f a +@findex mh-to-field +@item C-c C-f a +@itemx C-c C-f C-a +Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-b +@kindex C-c C-f b +@item C-c C-f b +@itemx C-c C-f C-b +Move to @samp{Bcc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-c +@kindex C-c C-f c +@item C-c C-f c +@itemx C-c C-f C-c +Move to @samp{Cc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-d +@kindex C-c C-f d +@item C-c C-f d +@itemx C-c C-f C-d +Move to @samp{Dcc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-f +@kindex C-c C-f f +@item C-c C-f f +@itemx C-c C-f C-f +Move to @samp{Fcc:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-l +@kindex C-c C-f l +@item C-c C-f l +@itemx C-c C-f C-l +Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-m +@kindex C-c C-f m +@item C-c C-f m +@itemx C-c C-f C-m +Move to @samp{From:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-r +@kindex C-c C-f r +@item C-c C-f r +@itemx C-c C-f C-r +Move to @samp{Reply-To:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-s +@kindex C-c C-f s +@item C-c C-f s +@itemx C-c C-f C-s +Move to @samp{Subject:} header field (@code{mh-to-field}). +@c ------------------------- +@kindex C-c C-f C-t +@kindex C-c C-f t +@item C-c C-f t +@itemx C-c C-f C-t +Move to @samp{To:} header field (@code{mh-to-field}). +@end table + +Another few commands are available in the MH-Folder buffer resulting +from a search. + +@table @kbd +@kindex @key{TAB} +@findex mh-index-next-folder +@item @key{TAB} +Jump to the next folder marker (@code{mh-index-next-folder}). +@c ------------------------- +@kindex S-@key{TAB} +@findex mh-index-previous-folder +@item S-@key{TAB} +Jump to the previous folder marker (@code{mh-index-previous-folder}). +@c ------------------------- +@kindex v +@findex mh-index-visit-folder +@item v +Visit original folder from where the message at point was found +(@code{mh-index-visit-folder}). +@end table + +@cindex @samp{mh-search} customization group +@cindex customization group, @samp{mh-search} + +There is one option from the @samp{mh-search} customization group used +in searching. + +@vtable @code +@item mh-search-program +Search program that MH-E shall use (default: @samp{Auto-detect}). +@end vtable + +The following hook is available. + +@vtable @code +@item mh-search-mode-hook +Hook run upon entry to @code{mh-search-mode} (default: @code{nil}). +@end vtable + +The following face is available. + +@vtable @code +@item mh-search-folder +Folder heading face in MH-Folder buffers created by searches. +@end vtable + +The command @kbd{F s} (@code{mh-search-folder}) helps you find +messages in your entire corpus of mail. You can search 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. + +Out of the box, MH-E uses @command{pick} to find messages. With a +little extra effort, you can set an indexing program which rewards you +with extremely quick results. The drawback is that sometimes the index +does not contain the words you're looking for. You can still use +@command{pick} in these situations. + +You are prompted for the folder to search. This can be @samp{all} to +search all folders. Note that the search works recursively on the +listed folder. + +@cindex MH-Search mode +@cindex modes, MH-Search + +Next, an MH-Search buffer appears where you can enter search criteria. + @cartouche +@smallexample From: # To: Cc: @@ -1754,1800 +6179,2503 @@ ---**-Emacs: pick-pattern (MH-Pick)------All-------------------------- - +--:** search-pattern (MH-Search)--L1--All----------------------------- + +@end smallexample @end cartouche -@i{Pick window} -@end group -@end example - -@cindex @code{pick} -@cindex MH commands, @code{pick} +@i{Search window} + +@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{M-s} command uses the -MH command @code{pick} to do the real work, so read @code{pick}(1) 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 @code{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{M-s} multiple times. +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. 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: - -@example +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 +Subject: -------- +horse +kosciusko +@end group +@end smallexample + +As with MH-Letter mode, MH-Search provides commands like @kbd{C-c C-f +C-t} (@code{mh-to-field}) to help you fill in the blanks. +@xref{Editing Message}. + +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-search-mode-hook}, which is called +when @kbd{F s} is run on a new pattern. + +@cindex @samp{+mhe-index} +@cindex folders, @samp{+mhe-index} +@findex mh-index-do-search +@findex mh-index-next-folder +@findex mh-index-previous-folder +@findex mh-pick-do-search +@kindex @key{TAB} +@kindex C-c C-c +@kindex F s +@kindex S-@key{TAB} +@vindex mh-search-folder + +To perform the search, type @kbd{C-c C-c} (@code{mh-index-do-search}). +Sometimes you're searching for text that is either not indexed, or +hasn't been indexed yet. In this case you can override the default +method with the pick method by running the command @kbd{C-c C-p} +(@code{mh-pick-do-search}). + +The messages that are found are put in a temporary sub-folder of +@samp{+mhe-index} and are displayed in an MH-Folder buffer. This +buffer is special because it displays messages from multiple folders; +each set of messages from a given folder has a heading with the folder +name. The appearance of the heading can be modified by customizing the +face @code{mh-search-folder}. You can jump back and forth between the +headings using the commands @kbd{@key{TAB}} +(@code{mh-index-next-folder}) and @kbd{S-@key{TAB}} +(@code{mh-index-previous-folder}). + +In addition, the command @kbd{v} (@code{mh-index-visit-folder}) can be +used to visit the folder of the message at point. Initially, only the +messages that matched the search criteria are displayed in the folder. +While the temporary buffer has its own set of message numbers, the +actual messages numbers are shown in the visited folder. Thus, the +command @kbd{v} is useful to find the actual message number of an +interesting message, or to view surrounding messages with the command +@kbd{F r} @code{mh-rescan-folder}. @xref{Folders}. + +Because this folder is temporary, you'll probably get in the habit of +killing it when you're done with @kbd{F k} (@code{mh-kill-folder}). +@xref{Folders}. + +You can regenerate the results by running @kbd{F s} with a prefix +argument. + +@cindex @command{procmail} +@cindex Unix commands, @command{procmail} +@cindex @samp{X-MHE-Checksum:} header field +@cindex header field, @samp{X-MHE-Checksum:} + +Note: This command uses an @samp{X-MHE-Checksum:} header field to +cache the MD5 checksum of a message. This means that if an incoming +message already contains an @samp{X-MHE-Checksum:} field, that message +might not be found by this command. The following @command{procmail} +recipe avoids this problem by renaming the existing header field: + +@smallexample +@group +:0 wf +| formail -R "X-MHE-Checksum" "X-Old-MHE-Checksum" +@end group +@end smallexample + +@xref{Limits}, for an alternative interface to searching. + +@section Configuring Indexed Searches + +@cindex @command{grep} +@cindex @command{mairix} +@cindex @command{namazu} +@cindex @command{pick} +@cindex @command{swish++} +@cindex @command{swish-e} +@cindex Unix commands, @command{grep} +@cindex Unix commands, @command{mairix} +@cindex Unix commands, @command{namazu} +@cindex Unix commands, @command{pick} +@cindex Unix commands, @command{swish++} +@cindex Unix commands, @command{swish-e} +@findex mh-search +@kindex F s +@vindex mh-search-program + +The command @kbd{F s} (@code{mh-search}) runs the command defined by +the option @code{mh-search-program}. The default value is +@samp{Auto-detect} which means that MH-E will automatically choose one +of @command{swish++}, @command{swish-e}, @command{mairix}, +@command{namazu}, @command{pick} and @command{grep} in that order. If, +for example, you have both @command{swish++} and @command{mairix} +installed and you want to use @command{mairix}, then you can set this +option to @samp{mairix}. + +The following sub-sections describe how to set up the various indexing +programs to use with MH-E. + +@subsection swish++ + +@cindex @command{swish++} +@cindex Unix commands, @command{swish++} + +In the examples below, replace @file{/home/user/Mail} with the path to +your MH directory. + +First create the directory @file{/home/user/Mail/.swish++}. Then +create the file @file{/home/user/Mail/.swish++/swish++.conf} with the +following contents: + +@smallexample +@group +IncludeMeta Bcc Cc Comments Content-Description From Keywords +IncludeMeta Newsgroups Resent-To Subject To +IncludeMeta Message-Id References In-Reply-To +IncludeFile Mail * +IndexFile /home/user/Mail/.swish++/swish++.index +@end group +@end smallexample + +Use the following command line to generate the swish index. Run this +daily from cron: + +@smallexample +@group +find /home/user/Mail -path /home/user/Mail/mhe-index -prune \ + -o -path /home/user/Mail/.swish++ -prune \ + -o -name "[0-9]*" -print \ + | index -c /home/user/Mail/.swish++/swish++.conf - @end group -@end example - -@findex @code{mh-to-field} - -As with MH-Letter mode, MH-Pick provides commands like -@kbd{C-c C-f C-t} to help you fill in the blanks. +@end smallexample + +This command does not index the folders that hold the results of your +searches in @samp{+mhe-index} since they tend to be ephemeral and the +original messages are indexed anyway. + +@cindex @command{index} +@cindex Unix commands, @command{index} +@cindex @command{index++} +@cindex Unix commands, @command{index++} + +On some systems (Debian GNU/Linux, for example), use @command{index++} +instead of @command{index}. + +@subsection swish + +@cindex @command{swish-e} +@cindex Unix commands, @command{swish-e} + +In the examples below, replace @file{/home/user/Mail} with the path to +your MH directory. + +First create the directory @file{/home/user/Mail/.swish}. Then create +the file @file{/home/user/Mail/.swish/config} with the following +contents: + +@smallexample +@group +DefaultContents TXT* +IndexDir /home/user/Mail +IndexFile /home/user/Mail/.swish/index +IndexName "Mail Index" +IndexDescription "Mail Index" +IndexPointer "http://nowhere" +IndexAdmin "nobody" +#MetaNames automatic +IndexReport 3 +FollowSymLinks no +UseStemming no +IgnoreTotalWordCountWhenRanking yes +WordCharacters abcdefghijklmnopqrstuvwxyz0123456789- +BeginCharacters abcdefghijklmnopqrstuvwxyz +EndCharacters abcdefghijklmnopqrstuvwxyz0123456789 +IgnoreLimit 50 1000 +IndexComments 0 +FileRules filename contains \D +FileRules pathname contains /home/user/Mail/.swish +FileRules pathname contains /home/user/Mail/mhe-index +FileRules filename is index +@end group +@end smallexample + +This configuration does not index the folders that hold the results of +your searches in @samp{+mhe-index} since they tend to be ephemeral and +the original messages are indexed anyway. + +If there are any directories you would like to ignore, append lines +like the following to @file{config}: + +@smallexample +FileRules pathname contains /home/user/Mail/scripts +@end smallexample + +@cindex @command{swish-e} +@cindex Unix commands, @command{swish-e} + +Use the following command line to generate the swish index. Run this +daily from cron: + +@smallexample + swish-e -c /home/user/Mail/.swish/config +@end smallexample + +@subsection mairix + +@cindex @command{mairix} +@cindex Unix commands, @command{mairix} + +In the examples below, replace @file{/home/user/Mail} with the path to +your MH directory. + +First create the directory @file{/home/user/Mail/.mairix}. Then create +the file @file{/home/user/Mail/.mairix/config} with the following +contents: + +@smallexample +@group +base=/home/user/Mail + +# List of folders that should be indexed. 3 dots at the end means there +# are subfolders within the folder +mh=archive...:inbox:drafts:news:sent:trash + +vfolder_format=raw +database=/home/user/Mail/mairix/database +@end group +@end smallexample + +Use the following command line to generate the mairix index. Run this daily +from cron: + +@smallexample +mairix -f /home/user/Mail/.mairix/config +@end smallexample + +@subsection namazu + +@cindex @command{namazu} +@cindex Unix commands, @command{namazu} + +In the examples below, replace @file{/home/user/Mail} with the path to +your MH directory. + +First create the directory @file{/home/user/Mail/.namazu}. Then create +the file @file{/home/user/Mail/.namazu/mknmzrc} with the following +contents: + +@smallexample +@group +package conf; # Don't remove this line! +$ADDRESS = 'user@@localhost'; +$ALLOW_FILE = "[0-9]*"; +$EXCLUDE_PATH = "^/home/user/Mail/(mhe-index|spam)"; +@end group +@end smallexample + +This configuration does not index the folders that hold the results of +your searches in @samp{+mhe-index} since they tend to be ephemeral and +the original messages are indexed anyway. + +Use the following command line to generate the namazu index. Run this +daily from cron: + +@smallexample +mknmz -f /home/user/Mail/.namazu/mknmzrc -O /home/user/Mail/.namazu \ + /home/user/Mail +@end smallexample + +@subsection pick + +@cindex @command{pick} +@cindex MH commands, @command{pick} + +This search method does not require any setup. + +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. + +@subsection grep + +@cindex @command{grep} +@cindex Unix commands, @command{grep} + +This search method does not require any setup. + +Unlike the other search methods, this method does not use the +MH-Search buffer. Instead, you simply enter a regular expression in +the minibuffer. For help in constructing regular expressions, see your +man page for @command{grep}. + +@node Threading, Limits, Searching, Top +@chapter Viewing Message Threads + +@cindex threading + +MH-E groups messages by @dfn{threads} which are messages that are part +of the same discussion and usually all have the same @samp{Subject:} +header field. Other ways to organize messages in a folder include +limiting (@pxref{Limits}) or using full-text indexed searches +(@pxref{Searching}). + +A thread begins with a single message called a @dfn{root}. All replies +to the same message are @dfn{siblings} of each other. Any message that +has replies to it is an @dfn{ancestor} of those replies. + +There are several commands that you can use to navigate and operate on +threads. @table @kbd -@item C-c C-f C-t -Move to @samp{To:} header field (@code{mh-to-field}). - -@item C-c C-f C-c -Move to @samp{cc:} header field (@code{mh-to-field}). - -@item C-c C-f C-s -Move to @samp{Subject:} header field (@code{mh-to-field}). - -@item C-c C-f C-f -Move to @samp{From:} header field (@code{mh-to-field}). - -@item C-c C-f C-b -Move to @samp{Bcc:} header field (@code{mh-to-field}). - -@item C-c C-f C-f -Move to @samp{Fcc:} header field (@code{mh-to-field}). - -@item C-c C-f C-d -Move to @samp{Dcc:} header field (@code{mh-to-field}). - -@item C-c C-c -Execute the search (@code{mh-do-pick-search}). +@kindex T ? +@findex mh-prefix-help +@item T ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@kindex T o +@findex mh-thread-refile +@item T o +Refile (output) thread into folder (@code{mh-thread-refile}). +@c ------------------------- +@kindex T d +@findex mh-thread-delete +@item T d +Delete thread (@code{mh-thread-delete}). +@c ------------------------- +@kindex T t +@findex mh-toggle-threads +@item T t +Toggle threaded view of folder (@code{mh-toggle-threads}). +@c ------------------------- +@kindex T n +@findex mh-thread-next-sibling +@item T n +Display next sibling (@code{mh-thread-next-sibling}). +@c ------------------------- +@kindex T p +@findex mh-thread-previous-sibling +@item T p +Display previous sibling (@code{mh-thread-previous-sibling}). +@c ------------------------- +@kindex T u +@findex mh-thread-ancestor +@item T u +Display ancestor of current message (@code{mh-thread-ancestor}). @end table -@findex @code{mh-do-pick-search} - -To perform the search, type @kbd{C-c C-c} (@code{mh-do-pick-search}). -The selected messages are placed in the @i{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 @i{search} sequence. If, -however, you wish to start with a clean slate, first delete the -@i{search} sequence (how to do this is discussed in @ref{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{M-r}. - -@node Sequences, Miscellaneous, Searching, Using mh-e -@section Using Sequences +The @samp{mh-thread} customization group contains one option. + +@vtable @code +@item mh-show-threads-flag +On means new folders start in threaded mode (default: @samp{off}). +@end vtable + +Threading large number of messages can be time consuming so the option +@code{mh-show-threads-flag} is turned off by default. If you turn on +this option, then threading will be done only if the number of +messages being threaded is less than @code{mh-large-folder}. In any +event, threading can be turned on (and off) with the command @kbd{T t} +(@code{mh-toggle-threads}). + +There are a few commands to help you navigate threads. If you do not +care for the way a particular thread has turned, you can move up the +chain of messages with the command @kbd{T u} +(@code{mh-thread-ancestor}. At any point you can use @kbd{T n} +(@code{mh-thread-next-sibling} or @kbd{T p} +(@code{mh-thread-previous-sibling}) to jump to the next or previous +sibling, skipping the sub-threads. The command @kbd{T u} can also take +a prefix argument to jump to the message that started everything. + +There are threaded equivalents for the commands that delete and refile +messages. For example, @kbd{T o} (@code{mh-thread-refile}) refiles the +current message and all its children. Similarly, the command @kbd{T d} +(@code{mh-thread-delete}) deletes the current message and all its +children. These commands do not refile or delete sibling messages. +@xref{Navigating}, for a description of the similar command @kbd{k} +(@code{mh-delete-subject-or-thread}). + +If you find that threading is too slow, it may be that you have +@code{mh-large-folder} set too high. Threading is one of the few +features of MH-E that really benefits from compiling. If you haven't +compiled MH-E, I encourage you to do so@footnote{If you're not sure +if MH-E has been byte-compiled, you could try running @samp{locate +mh-thread.elc} or otherwise find MH-E on your system and ensure that +@file{mh-thread.elc} exists. If you have multiple versions and you +find that one is compiled but the other is not, then go into your +@samp{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and +ensure that the byte-compiled version appears first in the +@code{load-path}. If you find that MH-E is not compiled and you +installed MH-E yourself, please refer to the installation directions +in the file @file{README} in the distribution.}. + +@node Limits, Sequences, Threading, Top +@chapter Limiting Display + +@cindex limits +@cindex filters + +Another way to organize messages in a folder besides threading +(@pxref{Threading}) 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-prefix-help +@item / ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@cindex @samp{Sequence > Narrow to Tick Sequence} menu item +@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} +@kindex / ' +@findex mh-narrow-to-tick +@item / ' +Limit to messages in the @samp{tick} sequence +(@code{mh-narrow-to-tick}). +@c ------------------------- +@kindex / c +@findex mh-narrow-to-cc +@item / c +Limit to messages with the same @samp{Cc:} field +(@code{mh-narrow-to-cc}). +@c ------------------------- +@kindex / m +@findex mh-narrow-to-from +@item / m +Limit to messages with the same @samp{From:} field +(@code{mh-narrow-to-from}). +@c ------------------------- +@kindex / g +@findex mh-narrow-to-range +@item / g +Limit to range (@code{mh-narrow-to-range}). +@c ------------------------- +@cindex @samp{Sequence > Narrow to Subject Sequence} menu item +@cindex menu item, @samp{Sequence > Narrow to Subject Sequence} +@kindex / s +@findex mh-narrow-to-subject +@item / s +Limit to messages with the same @samp{Subject:} field +(@code{mh-narrow-to-subject}). +@c ------------------------- +@kindex / t +@findex mh-narrow-to-to +@item / t +Limit to messages with the same @samp{To:} field +(@code{mh-narrow-to-to}). +@c ------------------------- +@cindex @samp{Sequence > Widen from Sequence} menu item +@cindex menu item, @samp{Sequence > Widen from Sequence} +@kindex / w +@findex mh-widen +@item / w +Remove last restriction (@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{/ m}, @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 command @kbd{/ '} (@code{mh-narrow-to-tick}). +@xref{Sequences}, for information on putting message into the +@samp{tick} sequence. Use the @kbd{/ g} (@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, Junk, Limits, Top +@chapter Using Sequences @cindex sequences -For the whole scoop on MH sequences, refer to @code{mh-sequence}(5). 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. +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. These commands are also +available in the @samp{Sequence} menu. @table @kbd -@item % -Put message in a sequence (@code{mh-put-msg-in-seq}). - -@item ? -Display sequences that message belongs to (@code{mh-msg-is-in-seq}). - -@item M-q +@cindex @samp{Sequence > Toggle Tick Mark} menu item +@cindex menu item, @samp{Sequence > Toggle Tick Mark} +@kindex ' +@findex mh-toggle-tick +@item ' +Toggle tick mark of range (@code{mh-toggle-tick}). +@c ------------------------- +@kindex S ? +@findex mh-prefix-help +@item S ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@cindex @samp{Sequence > Narrow to Tick Sequence} menu item +@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} +@kindex S ' +@findex mh-narrow-to-tick +@item S ' +Limit to ticked messages (@code{mh-narrow-to-tick}). +@c ------------------------- +@cindex @samp{Sequence > Delete Message from Sequence...} menu item +@cindex menu item, @samp{Sequence > Delete Message from Sequence...} +@kindex S d +@findex mh-delete-msg-from-seq +@item S d +Delete range from sequence (@code{mh-delete-msg-from-seq}). +@c ------------------------- +@cindex @samp{Sequence > Delete Sequence...} menu item +@cindex menu item, @samp{Sequence > Delete Sequence...} +@kindex S k +@findex mh-delete-seq +@item S k +Delete sequence (@code{mh-delete-seq}). +@c ------------------------- +@cindex @samp{Sequence > List Sequences in Folder...} menu item +@cindex menu item, @samp{Sequence > List Sequences in Folder...} +@kindex S l +@findex mh-list-sequences +@item S l List all sequences in folder (@code{mh-list-sequences}). - -@item M-% -Remove message from sequence (@code{mh-delete-msg-from-seq}). - -@item M-# -Delete sequence (@code{mh-delete-seq}). - -@item C-x n +@c ------------------------- +@cindex @samp{Sequence > Narrow to Sequence...} menu item +@cindex menu item, @samp{Sequence > Narrow to Sequence...} +@kindex S n +@findex mh-narrow-to-seq +@item S n Restrict display to messages in sequence (@code{mh-narrow-to-seq}). - -@item C-x w -Remove restriction; display all messages (@code{mh-widen}). - +@c ------------------------- +@cindex @samp{Sequence > Add Message to Sequence...} menu item +@cindex menu item, @samp{Sequence > Add Message to Sequence...} +@kindex S p +@findex mh-put-msg-in-seq +@item S p +Add range to sequence (@code{mh-put-msg-in-seq}). +@c ------------------------- +@cindex @samp{Sequence > List Sequences for Message} menu item +@cindex menu item, @samp{Sequence > List Sequences for Message} +@kindex S s +@findex mh-msg-is-in-seq +@item S s +Display the sequences in which the current message appears +(@code{mh-msg-is-in-seq}). +@c ------------------------- +@cindex @samp{Sequence > Widen from Sequence} menu item +@cindex menu item, @samp{Sequence > Widen from Sequence} +@kindex S w +@findex mh-widen +@item S w +Remove last restriction (@code{mh-widen}). +@c ------------------------- +@findex mh-update-sequences @item M-x mh-update-sequences -Push mh-e's state out to MH@. +Flush MH-E's state out to MH@. @end table -@cindex @code{pick} -@cindex MH commands, @code{pick} -@findex @code{mh-put-msg-in-seq} - -To place a message in a sequence, use @kbd{%} (@code{mh-put-msg-in-seq}) -to do it manually, or use the MH command @code{pick} or the mh-e version -of @code{pick} (@ref{Searching}) which create a sequence automatically. -Give @kbd{%} a prefix argument and you can add all the messages in one -sequence to another sequence (for example, @kbd{C-u % SourceSequence -RET}). +@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 +On means that sequences are preserved when messages are refiled +(default: @samp{on}). +@c ------------------------- +@item mh-tick-seq +The name of the MH sequence for ticked messages (default: @samp{'tick}). +@c ------------------------- +@item mh-update-sequences-after-mh-show-flag +On means flush MH sequences to disk after message is shown (default: +@samp{on}). +@end vtable + +The following hook is available. + +@vtable @code +@item mh-unseen-updated-hook +Hook run after the unseen sequence has been updated (default: @code{nil}). +@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}). 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. This sequence can be viewed later with the @kbd{F '} command +(@pxref{Folders}). + +You can customize the option @code{mh-tick-seq} if you already use the +@samp{tick} sequence for your own use. You can also disable all of the +ticking functions by choosing the @samp{Disable Ticking} item but +there isn't much advantage to that. @cindex MH-Folder mode @cindex modes, MH-Folder -@findex @code{mh-narrow-to-seq} -@findex @code{mh-widen} 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{C-x 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{C-x w} +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. To narrow the view to the messages in the @samp{tick} +sequence, use @kbd{S '} (@code{mh-narrow-to-tick}). When you want to +widen the view to all your messages again, use @kbd{S w} (@code{mh-widen}). -@findex @code{mh-msg-is-in-seq} -@findex @code{mh-list-sequences} - -You can see which sequences a message is in with the @kbd{?} -(@code{mh-msg-is-in-seq}) command. -@c Doesn't work: -@c use a prefix argument to query a -@c message other than the current one (as in @kbd{C-u ? 42 RET}). XXX -Or, you can list all sequences in a selected folder (default is current -folder) with @kbd{M-q} (@code{mh-list-sequences}). - -@findex @code{mh-delete-msg-from-seq} -@findex @code{mh-delete-seq} - -If you want to remove a message from a sequence, use @kbd{M-%} -(@code{mh-delete-msg-from-seq}), and if you want to delete an entire -sequence, use @kbd{M-#} (@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} (see @ref{Deleting} above). - -@cindex @code{mark} -@cindex MH commands, @code{mark} - -@findex @code{mh-update-sequences} - -Two sequences are maintained internally by mh-e and pushed out to MH -when you type either the @kbd{x} or @kbd{q} command. They are the -sequence specified by your @samp{Unseen-Sequence:} profile entry and -@i{cur}. However, you can also just update MH's state with the command -@kbd{M-x mh-update-sequences}. See @ref{Customizing Viewing} for an -example of how this command might be used. - -With the exceptions of @kbd{C-x n} and @kbd{C-x w}, the underlying MH -command dealing with sequences is @code{mark}. - -@node Miscellaneous, , Sequences, Using mh-e -@section Miscellaneous Commands - -@findex @code{mh-version} - -One other 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} should -always be included with any bug report you submit (@pxref{Bug Reports}). - -@node Customizing mh-e, Odds and Ends, Using mh-e, Top -@chapter 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 -@ref{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. - -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -Many string or integer variables are easy enough to modify using Emacs -Lisp. Any such modifications should be placed in a file called -@file{.emacs} in your home directory (that is, @file{~/.emacs}). For -example, to modify the variable that controls printing, you could add: - -@vindex @code{mh-lpr-command-format}, example - -@lisp -(setq mh-lpr-command-format "nenscript -G -r -2 -i'%s'") -@end lisp - -@ref{Customizing Printing} talks more about this variable. - -@cindex setting variables -@cindex Emacs, setting variables - -Variables can also hold Boolean values. In Emacs Lisp, the Boolean -values are @code{nil}, which means false, and @code{t}, which means true. -Usually, variables are turned off by setting their value to @code{nil}, as -in - -@vindex @code{mh-bury-show-buffer}, example - -@lisp -(setq mh-bury-show-buffer nil) -@end lisp - -which keeps the MH-Show buffer at the top of the buffer stack. -To turn a variable on, you use - -@lisp -(setq mh-bury-show-buffer t) -@end lisp - -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 -@emph{non-@code{nil}} value, because sometimes values other than @code{t} are -meaningful (for example, see @code{mhl-formfile}, described in -@ref{Customizing Viewing}). 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 @file{~/.emacs}. Variables can be changed in -the current Emacs session by using @kbd{M-x set-variable}. - -@c XXX Stephen says: would be easier to just call them functions, which -@c you mostly do. -In general, @dfn{commands} in this text refer to Emacs Lisp functions. -Programs outside of Emacs are specifically called MH commands, shell -commands, or Unix commands. - -@cindex Emacs, Emacs Lisp manual -@cindex Emacs, online help -@cindex online help -@cindex Emacs, info -@cindex info - -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 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@@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@@gnu.org}.} -@end ifinfo -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}) -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 RET}. If you write your own -functions, please do not prefix your symbols (variables and functions) -with @code{mh-}. This prefix is reserved for the mh-e package. To -avoid conflicts with existing mh-e symbols, use a prefix like @code{my-} -or your initials. - -@menu -* Customizing Reading:: -* Customizing Sending:: -* Customizing Draft Editing:: -* Customizing Moving Mail:: -* Customizing Searching:: -@end menu - -@node Customizing Reading, Customizing Sending, Customizing mh-e, Customizing mh-e -@section Reading Your Mail - -@cindex reading mail -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -I'll start out by including 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 chapter, simply add the following -code to @file{~/.emacs}. Don't be intimidated by the size of this -example; most customizations are only one line. - -@iftex -@filbreak -@end iftex - -@findex @code{mh-rmail}, example - -@lisp -@group -@i{Starting mh-e} - -(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} -@end group -@end lisp - -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 +inbox 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. - -Now to configure mh-e. The following table lists general mh-e variables -and variables that are used while reading mail. -@c XXX Seth wishes the descriptions to be more parallel. That is, -@c some are actions, and some are objects. Hmmm. - -@table @code -@item mh-progs -Directory containing MH programs (default: dynamic). - -@item mh-lib -Directory containing MH support files and programs (default: dynamic). - -@item mh-do-not-confirm -Don't confirm on non-reversible commands (default: @code{nil}). - -@item mh-summary-height -Number of scan lines to show (includes mode line) (default: 4). - -@item mh-folder-mode-hook -Functions to run in MH-Folder mode (default: @code{nil}). - -@item mh-clean-message-header -Remove extraneous headers (default: @code{nil}). - -@item mh-invisible-headers -Headers to hide (default: @samp{"^Received: \\| ^Message-Id: \\| -^Remailed-\\| ^Via: \\| ^Mail-from: \\| ^Return-Path: \\| ^In-Reply-To: -\\| ^Resent-"}). - -@item mh-visible-headers -Headers to display (default: @code{nil}). - -@item mhl-formfile -Format file for @code{mhl} (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}). - -@item mh-bury-show-buffer -Leave show buffer at bottom of stack (default: @code{t}). - -@item mh-show-buffer-mode-line-buffer-id -Name of show buffer in mode line (default: @samp{"@{show-%s@} %d"}). +@cindex @samp{*MH-E Sequences*} +@cindex buffers, @samp{*MH-E Sequences*} + +You can see which sequences in which a message appears with the +command @kbd{S s} (@code{mh-msg-is-in-seq}). 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 option @code{mh-refile-preserves-sequences-flag}. + +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 option @code{mh-tick-seq} which is @samp{tick} +by default. If you do not like this behavior, turn off the option +@code{mh-update-sequences-after-mh-show-flag}. You can then update the +state manually with the @kbd{x}, @kbd{q}, or @kbd{M-x +mh-update-sequences} commands. + +@vindex mh-seen-list +@vindex mh-unseen-updated-hook + +The hook @code{mh-unseen-updated-hook} is run after the unseen +sequence has been updated. The variable @code{mh-seen-list} can be +used by this hook to obtain the list of messages which were removed +from the unseen sequence. + +@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 Junk, Miscellaneous, Sequences, Top +@chapter Dealing With Junk Mail + +@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 viruses +@cindex whitelisting +@cindex worms + +We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for +any unwanted message which includes spam, @dfn{viruses}, 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 ? +@findex mh-prefix-help +@item J ? +Display cheat sheet for the commands of the current prefix in +minibuffer (@code{mh-prefix-help}). +@c ------------------------- +@kindex J b +@findex mh-junk-blacklist +@item J b +Blacklist range as spam (@code{mh-junk-blacklist}). +@c ------------------------- +@kindex J w +@findex mh-junk-whitelist +@item J w +Whitelist range as ham (@code{mh-junk-whitelist}). +@c ------------------------- +@item @code{mh-spamassassin-identify-spammers} +Identify spammers who are repeat offenders. @end table -@vindex @code{mh-progs} -@vindex @code{mh-lib} - -The two variables @code{mh-progs} and @code{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 @samp{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 (@samp{/}). See the example in @ref{Getting Started}. - -@vindex @code{mh-do-not-confirm} -@findex @code{mh-kill-folder} - -If you never make mistakes, and you do not like confirmations for your -actions, you can set @code{mh-do-not-confirm} to a non-@code{nil} value to -disable confirmation for unrecoverable commands such as @kbd{M-k} -(@code{mh-kill-folder}) and @kbd{M-u} (@code{mh-undo-folder}). Here's -how you set boolean values: - -@lisp -(setq mh-do-not-confirm t) -@end lisp - -@vindex @code{mh-summary-height} -@cindex MH-Folder mode -@cindex modes, MH-Folder - -@c Prevent page break between paragraph and example. -@need 2000 -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 @code{mh-bury-show-buffer} -@cindex MH-Folder mode -@cindex modes, MH-Folder - -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} 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 @code{mh-folder-mode-hook} -@cindex MH-Folder mode -@cindex modes, MH-Folder - -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 @code{mh-folder-mode-hook}, example - -@lisp -@group -@i{Create additional key bindings via mh-folder-mode-hook} - -(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} -@end group -@end lisp - -@menu -* Customizing Viewing:: -* Customizing Moving Around:: -@end menu - -@node Customizing Viewing, Customizing Moving Around, Customizing Reading, Customizing Reading -@subsection Viewing Your Mail - -@vindex @code{mh-clean-message-header} -@vindex @code{mh-invisible-headers} -@vindex @code{mh-visible-headers} - -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 @code{mh-clean-message-header} to a -non-@code{nil} value. The header can then be cleaned up in two ways. By -default, the header fields in @code{mh-invisible-headers} are removed. -On the other hand, you could set @code{mh-visible-headers} to the fields -that you would like to see. If this variable is set, -@code{mh-invisible-headers} is ignored. I suggest that you not set -@code{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, @code{mh-visible-headers} can be set to show a -minimum set of header fields (see (@ref{Regexps, , Syntax of Regular -Expressions, emacs, The GNU Emacs Manual}, for a description of the -special characters in this string): - -@lisp -(setq mh-visible-headers "^From: \\|^Subject: \\|^Date: ") -@end lisp - -@cindex @code{mhl} -@cindex MH commands, @code{mhl} -@vindex @code{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 @code{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 (@code{mhl}(1) tells you how to write one). When writing -your own format file, use a nonzero value for @code{overflowoffset} to -ensure the header is RFC 822 compliant and parsable by mh-e. -@code{mhl} is always used for printing and forwarding; in this case, the -value of @code{mhl-formfile} is consulted if it is a filename. - -@vindex @code{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 @code{mh-show-mode-hook}, example - -@lisp -@group -@i{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)) -@end group -@end lisp - -@vindex @code{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. For example, if -you wanted to keep mh-e in sync with MH, you could use -@code{mh-show-hook} as follows: - -@vindex @code{mh-show-hook}, example - -@lisp -(add-hook 'mh-show-hook 'mh-update-sequences) -@end lisp - -@vindex @code{mh-show-buffer-mode-line-buffer-id} -@cindex MH-Show mode -@cindex modes, MH-Show - -The function @code{mh-update-sequences} is documented in @ref{Finishing -Up}. 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 +@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 mh-junk-background +If on, spam programs are run in background (default: @samp{off}). +@c ------------------------- +@item mh-junk-disposition +Disposition of junk mail (default: @samp{Delete Spam}). +@c ------------------------- +@item 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 option @code{mh-junk-program} 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 command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam +program in use with the content of the range (@pxref{Ranges}) and then +handles the message(s) as specified by the option +@code{mh-junk-disposition}. 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 command @kbd{J w} (@code{mh-junk-whitelist}) +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. + +By default, the programs are run in the foreground, but this can be +slow when junking large numbers of messages. If you have enough memory +or don't junk that many messages at the same time, you might try +turning on the option @code{mh-junk-background}. + +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:} + +@smallexample +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 smallexample + +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 @command{gnumeric} to verify that the average plus the +standard deviation of good mail is under 5, the SpamAssassin default +for "spam". + +Using @command{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 command @kbd{J b} (@code{mh-junk-blacklist}) 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 command@kbd{J w} (@code{mh-junk-whitelist}) 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: + +@smallexample +blacklist_from *@@*amazingoffersdirect2u.com +@end smallexample + +In versions of SpamAssassin (2.50 and on) that support a Bayesian +classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program +@command{sa-learn} 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 @file{crontab}: + +@smallexample +0 * * * * sa-learn --rebuild > /dev/null 2>&1 +@end smallexample + +@heading Bogofilter + +Bogofilter is a Bayesian spam filtering program. Get it from your +local distribution or from the +@uref{http://bogofilter.sourceforge.net/, bogofilter web site}. + +Bogofilter is taught by running: + +@smallexample +bogofilter -n < good-message +@end smallexample + +on every good message, and + +@smallexample +bogofilter -s < spam-message +@end smallexample + +@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:} + +@smallexample +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 smallexample + +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: + +@smallexample +bogoutil -d wordlist.db | bogoutil -l wordlist.db.new +mv wordlist.db wordlist.db.prv +mv wordlist.db.new wordlist.db +@end smallexample + +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:} + +@smallexample +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 smallexample + +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 viruses. 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:} + +@smallexample +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 smallexample + +@node Miscellaneous, Scan Line Formats, Junk, Top +@chapter Miscellaneous Commands, Variables, and Buffers + +This chapter covers the following command and the various MH-E +buffers, + +@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 usually be included with any bug report you +submit (@pxref{Bug Reports}). + +@heading MH-E Buffers + +Besides the MH-Folder, MH-Show, and MH-Letter buffers, MH-E creates +several other buffers. They are: + +@table @samp +@cindex @samp{*MH-E Folders*} +@cindex buffers, @samp{*MH-E Folders*} +@findex mh-list-folders +@item *MH-E Folders* +@kindex F l +This buffer contains the output of @kbd{F l} (@code{mh-list-folders}). +@xref{Folders}. +@c ------------------------- +@cindex @samp{*MH-E Help*} +@cindex buffers, @samp{*MH-E Help*} +@findex mh-help +@item *MH-E Help* +@kindex ? +@kindex C-c ? +This buffer contains the output of @kbd{?} (@code{mh-help}) and +@kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}. +@c ------------------------- +@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}}. +@c ------------------------- +@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. +@c ------------------------- +@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}. +@c ------------------------- +@cindex @samp{*MH-E Recipients*} +@cindex buffers, @samp{*MH-E Recipients*} +@findex mh-check-whom +@item *MH-E Recipients* +@kindex C-c C-w +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}. +@c ------------------------- +@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}. +@c ------------------------- +@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 Scan Line Formats, Procmail, Miscellaneous, Top +@appendix Scan Line Formats + +@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-adaptive-cmd-note-flag +On means that the message number width is determined dynamically +(default: @samp{on}). +@c ------------------------- +@item mh-scan-format-file +Specifies the format file to pass to the scan program (default: +@samp{Use MH-E scan Format}). +@c ------------------------- +@item mh-scan-prog +Program used to scan messages (default: @samp{"scan"}). +@end vtable + +@findex mh-set-cmd-note +@vindex mh-adaptive-cmd-note-flag +@vindex mh-scan-format-file + +There are a couple of caveats when creating your own scan format file. +First, MH-E will not work if your scan lines do not include message +numbers. It will work poorly if you don't dedicate a column for +showing the current message and notations. You won't be able to use +the option @code{mh-adaptive-cmd-note-flag} or the threading features +(@pxref{Threading}). + +@cindex message numbers + +If you've created your own format to handle long message numbers, +you'll be pleased to know you no longer need it since MH-E adapts its +internal format based upon the largest message number if +@code{mh-adaptive-cmd-note-flag} is on (the default). If you prefer +fixed-width message numbers, turn off @code{mh-adaptive-cmd-note-flag} +and call @code{mh-set-cmd-note} with the width specified by your +format file (see @code{mh-scan-format-file}). For example, the default +width is 4, so you would use @samp{(mh-set-cmd-note 4)}. + +@vindex mh-scan-format-nmh +@vindex mh-scan-format-mh + +The default setting for @code{mh-scan-format-file} is @samp{Use MH-E +scan Format}. This means that the format string will be taken from the +either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending +on whether MH or nmh (or GNU mailutils) is in use. This setting also +enables you to turn on the option @code{mh-adaptive-cmd-note-flag}. +You can also set this option to @samp{Use Default scan Format} to get +the same output as you would get if you ran @command{scan} from the +shell. If you have a format file that you want MH-E to use but not MH, +you can set this option to @samp{Specify a scan Format File} and enter +the name of your format file. + +The scan format that MH-E uses when @code{mh-scan-format-file} is set +to its default of @samp{Use MH-E scan Format} is held in the variables +@code{mh-scan-format-nmh} and @code{mh-scan-format-mh} depending on +whether you are using nmh (or GNU mailutils) or not. Typically, you +create your own format files rather than modifying these variables. +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 + +@cindex RFC 2047, decoding +@cindex decoding RFC 2047 + +The setting for @code{mh-scan-format-mh} is similar, except that MH +doesn't have the function @code{decode} (which is used to decode RFC +2047 encodings). + +@cindex notations, scan line +@cindex scan line notations + +These strings are passed to the @command{scan} program via the +@option{-format} argument. The formats are identical to the defaults +except that additional hints for fontification have been added to the +existing notations in the fifth column (remember that in Emacs, the +columns start at 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. + +@cindex @command{scan} +@cindex MH commands, @command{scan} +@vindex mh-progs +@vindex mh-scan-prog + +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 (@pxref{Getting Started}). 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.}. + +@cindex regular expressions, scan line formats + +If you change the format of the scan lines you'll need to tell MH-E +how to parse the new format. As you will see, quite a lot of variables +are involved to do that. Use @samp{M-x apropos @key{RET} mh-scan.*regexp'} +to obtain a list of these variables. You will also have to call +@code{mh-set-cmd-note} if your notations are not in column 4 (columns +in Emacs start with 0). Note that unlike most of the user options +described in this manual, these are variables and must be set with +@code{setq} instead of in a customization buffer. For help with +regular expressions, see +@ifnothtml +@ref{Regexps, , Syntax of Regular Expressions, emacs, The +GNU Emacs Manual} +@end ifnothtml +@ifhtml +the section +@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, +Syntax of Regular Expressions} in +@cite{The GNU Emacs Manual}). +@end ifhtml + +The first variable has to do with pruning out garbage. + +@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. + +@vindex mh-folder-font-lock-keywords + +@vtable @code +@vindex mh-folder-body +@vindex mh-folder-font-lock-keywords +@item mh-scan-body-regexp +This regular expression matches the message body fragment. 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 body text as in the default of +@samp{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not +correct, the body fragment will not be highlighted with the face +@code{mh-folder-body}. +@c ------------------------- +@vindex mh-folder-cur-msg-number +@vindex mh-folder-font-lock-keywords +@vindex mh-note-cur +@item mh-scan-cur-msg-number-regexp +This regular expression matches the current message. It must match +from the beginning of the line. 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 @w{@samp{"^\\( *[0-9]+\\+\\).*"}}. This +expression includes the leading space and current message marker +@samp{+} within the parenthesis since it looks better to highlight +these items as well. The highlighting is done with the face +@code{mh-folder-cur-msg-number}. This regular expression should be +correct as it is needed by non-fontification functions. See also +@code{mh-note-cur}. +@c ------------------------- +@vindex mh-folder-date +@vindex mh-folder-font-lock-keywords +@vindex mh-scan-sent-to-me-sender-regexp +@item mh-scan-date-regexp +This regular expression matches a valid date. It must @strong{not} be +anchored to the beginning or the end of the line. 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]\\)"}. If this regular expression is +not correct, the date will not be highlighted with the face +@code{mh-folder-date}. +@c ------------------------- +@vindex mh-folder-deleted +@vindex mh-folder-font-lock-keywords +@vindex mh-note-deleted +@item mh-scan-deleted-msg-regexp +This regular expression matches deleted messages. It must match from +the beginning of the line. 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"}. This expression +includes the leading space within the parenthesis since it looks +better to highlight it as well. The highlighting is done with the face +@code{mh-folder-deleted}. This regular expression should be correct as +it is needed by non-fontification functions. See also +@code{mh-note-deleted}. +@c ------------------------- +@vindex mh-folder-font-lock-keywords +@vindex mh-folder-msg-number +@item mh-scan-good-msg-regexp +This regular expression matches ``good'' messages. It must match from +the beginning of the line. 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 @w{@samp{"^\\( *[0-9]+\\)[^D^0-9]"}}. This +expression includes the leading space within the parenthesis since it +looks better to highlight it as well. The highlighting is done with +the face @code{mh-folder-msg-number}. This regular expression should +be correct as it is needed by non-fontification functions. +@c ------------------------- +@vindex mh-scan-format-file +@item mh-scan-msg-format-regexp +This regular expression finds 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)"}. This +variable is only consulted if @code{mh-scan-format-file} is set to +@samp{Use MH-E scan Format}. +@c ------------------------- +@vindex mh-scan-format-file +@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. This variable +is only consulted if @code{mh-scan-format-file} is set to @samp{Use +MH-E scan Format} (default: @samp{"%d"}). +@c ------------------------- +@item mh-scan-msg-number-regexp +This regular expression extracts the message number. It must match +from the beginning of the line. Note that the message number must be +placed in a parenthesized expression as in the default of @w{@samp{"^ +*\\([0-9]+\\)"}}. +@c ------------------------- +@item mh-scan-msg-overflow-regexp +This regular expression matches overflowed message numbers (default: +@samp{"^[?0-9][0-9]"}). +@c ------------------------- +@item mh-scan-msg-search-regexp +This regular expression matches a particular message. It is a format +string; 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]"}. +@c ------------------------- +@vindex mh-folder-address +@vindex mh-folder-font-lock-keywords +@vindex mh-folder-to +@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:\\)\\(..............\\)"}. If this +regular expression is not correct, the @samp{To:} string will not be +highlighted with the face @code{mh-folder-to} and the recipient will not be +highlighted with the face @code{mh-folder-address}. +@c ------------------------- +@vindex mh-folder-font-lock-keywords +@vindex mh-folder-refiled +@vindex mh-note-refiled +@item mh-scan-refiled-msg-regexp +This regular expression matches refiled messages. It must match from +the beginning of the line. 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 @w{@samp{"^\\( *[0-9]+\\)\\^"}}. This expression +includes the leading space within the parenthesis since it looks +better to highlight it as well. The highlighting is done with the face +@code{mh-folder-refiled}. This regular expression should be correct as +it is needed by non-fontification functions. See also +@code{mh-note-refiled}. +@c ------------------------- +@vindex mh-folder-font-lock-keywords +@vindex mh-folder-sent-to-me-sender +@vindex mh-mh-folder-sent-to-me-hint +@vindex mh-scan-format-nmh +@item mh-scan-sent-to-me-sender-regexp +This regular expression matches messages sent to us. Note that the +default setting of @code{mh-folder-font-lock-keywords} expects this +expression to contain at least two parenthesized expressions. The +first should match the fontification hint (see +@code{mh-scan-format-nmh}) and the second should match the user name +as in the default of +@w{@samp{"^ *[0-9]+.\\([bct]\\).....[ ]*\\(..................\\)"}}. +If this regular expression is not correct, the notation hints will not +be highlighted with the face @code{mh-mh-folder-sent-to-me-hint} and +the sender will not be highlighted with the face +@code{mh-folder-sent-to-me-sender}. +@c ------------------------- +@vindex mh-folder-followup +@vindex mh-folder-font-lock-keywords +@vindex mh-folder-subject +@item mh-scan-subject-regexp +This regular expression matches the subject. It must match from the +beginning of the line. 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, and is highlighted with the face +@code{mh-folder-followup}. 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). The third is expected to +match the subject line itself which is highlighted with the face +@code{mh-folder-subject}. For example, the default is +@w{@samp{"^ *[0-9]+........[ ]*...................}}@* +@w{@samp{\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"}}. +This regular expression should be correct as it is needed by +non-fontification functions. Note that this example is broken up on +two lines for readability, but is actually a single string. +@end vtable + +Finally, there are a slew of variables that control how MH-E annotates +the scan lines. + +@vtable @code +@item mh-cmd-note +Column for notations (default: 4). This variable should be set with +the function @code{mh-set-cmd-note}. This variable may be updated +dynamically if @code{mh-adaptive-cmd-note-flag} is on. The following +variables contain the notational characters. Note that columns in +Emacs start with 0. +@c ------------------------- +@item mh-note-copied +Messages that have been copied are marked by this character (default: +@samp{?C}). +@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}. +@c ------------------------- +@item mh-note-deleted +Messages that have been deleted are marked by this character (default: +@samp{?D}). See also @code{mh-scan-deleted-msg-regexp}. +@c ------------------------- +@item mh-note-dist +Messages that have been redistributed are marked by this character +(default: @samp{?R}). +@c ------------------------- +@item mh-note-forw +Messages that have been forwarded are marked by this character +(default: @samp{?F}). +@c ------------------------- +@item mh-note-printed +Messages that have been printed are marked by this character (default: +@samp{?P}). +@c ------------------------- +@item mh-note-refiled +Messages that have been refiled are marked by this character (default: +@samp{?^}). See also @code{mh-scan-refiled-msg-regexp}. +@c ------------------------- +@item mh-note-repl +Messages that have been replied to are marked by this character +(default: @samp{?-}). +@c ------------------------- +@item mh-note-seq +Messages in a user-defined sequence are marked by this character +(default: @samp{?%}). Messages in the @samp{search} sequence are +marked by this character as well. +@end vtable + +For example, let's say I have the following in @file{scan.format} +which displays the sender, the subject, and the message number. This +format places a @samp{+} after the message number for the current +message according to MH; it also uses that column for notations. @example ------@{show-+inbox@} 4 (MH-Show)--Bot-------------------------------- -@end example - -@node Customizing Moving Around, , Customizing Viewing, Customizing Reading -@subsection Moving Around - -@cindex moving between messages -@cindex MH-Show mode -@cindex modes, MH-Show -@cindex MH-Folder mode -@cindex modes, MH-Folder -@vindex @code{mh-recenter-summary-p} - -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-p} 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-p} is rather useful, but it can -be annoying on a slow network connection. - -@node Customizing Sending, Customizing Draft Editing, Customizing Reading, Customizing mh-e -@section Sending Mail - -@cindex sending mail - -You may wish to start off by adding the following useful key bindings to -your @file{.emacs} file: - -@lisp -(global-set-key "\C-xm" 'mh-smail) -(global-set-key "\C-x4m" 'mh-smail-other-window) -@end lisp - -In addition, several variables are useful when sending mail or replying -to mail. They are summarized in the following table. - -@table @code -@item mh-comp-formfile -Format file for drafts (default: @samp{"components"}). - -@item mh-repl-formfile -Format file for replies (default: @samp{"replcomps"}). - -@item mh-letter-mode-hook -Functions to run in MH-Letter mode (default: @code{nil}). - -@item mh-compose-letter-function -Functions to run when starting a new draft (default: @code{nil}). - -@item mh-reply-default-reply-to -Whom reply goes to (default: @code{nil}). - -@item mh-forward-subject-format -Format string for forwarded message subject (default: @samp{"%s: %s"}). - -@item mh-redist-full-contents -@code{send} requires entire message (default: @code{nil}). - -@item mh-new-draft-cleaned-headers -Remove these header fields from re-edited draft. The default is: -@example -"^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\| -^Sender:\\| ^Delivery-Date:\\| ^Return-Path:". +%20(decode(friendly@{from@})) %50(decode@{subject@}) %4(msg)%<(cur)+%| %> @end example -@end table - -@cindex @code{comp} -@cindex MH commands, @code{comp} -@vindex @code{mh-comp-formfile} -@cindex @file{components} -@cindex files, @file{components} -@cindex @code{repl} -@cindex MH commands, @code{repl} -@cindex @file{replcomps} -@cindex files, @file{replcomps} -@vindex @code{mh-repl-formfile} - -Since mh-e does not use @code{comp} 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 -@code{repl}. You can change the location of the field file from the -default of @file{replcomps} by modifying @code{mh-repl-formfile}. - -@vindex @code{mh-letter-mode-hook} -@cindex @code{repl} -@cindex MH commands, @code{repl} -@cindex @file{components} -@cindex files, @file{components} - -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 @code{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 @code{mh-insert-signature}, example - -@lisp -@group -@i{Prepare draft for editing via mh-letter-mode-hook} - -(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) -@end group -@end lisp - -The function, @code{add-enriched-text} is defined in the example in -@ref{Customizing Editing MIME}. - -@vindex @code{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. - -@menu -* Customizing Replying:: -* Customizing Forwarding:: -* Customizing Redistributing:: -* Customizing Old Drafts:: -@end menu - -@node Customizing Replying, Customizing Forwarding, Customizing Sending, Customizing Sending -@subsection Replying to Mail - -@cindex replying -@vindex @code{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 Customizing Forwarding, Customizing Redistributing, Customizing Replying, Customizing Sending -@subsection Forwarding Mail - -@cindex forwarding -@vindex @code{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@@newt.com> -Subject: Re: 49er football -From: Greg DesBrisay <gd@@cellnet.com> -@end group -@end example - -and creates a subject header field of: - -@example -Subject: Greg DesBrisay: Re: 49er football -@end example - -@node Customizing Redistributing, Customizing Old Drafts, Customizing Forwarding, Customizing Sending -@subsection Redistributing Your Mail - -@cindex redistributing -@vindex @code{mh-redist-full-contents} -@cindex @code{dist} -@cindex MH commands, @code{dist} -@cindex @code{send} -@cindex MH commands, @code{send} - -The variable @code{mh-redist-full-contents} must be set to non-@code{nil} if -@code{dist} requires the whole letter for redistribution, which is the -case if @code{send} is compiled with the @sc{berk} @footnote{To see which -options your copy of MH was compiled with, use @kbd{M-x mh-version} -(@ref{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 Customizing Old Drafts, , Customizing Redistributing, Customizing Sending -@subsection Editing Old Drafts and Bounced Messages - -@cindex re-editing drafts -@vindex @code{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{M-e} -(@code{mh-extract-rejected-mail}) or @kbd{M-a} (@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 @code{mh-new-draft-cleaned-headers}, example + +@vindex mh-scan-format-file, example + +The first thing you have to do is tell MH-E to use this file. +Customize @code{mh-scan-format-file} and set its value to @samp{Use +Default scan Format}. If you didn't get already turn off +@code{mh-adaptive-cmd-note-flag}, you'll need to do that first. + +Next, tell MH-E what a valid scan line looks like so that you can at +least display the output of scan in your MH-Folder buffer. + +@vindex mh-scan-valid-regexp, example @lisp -(setq mh-new-draft-cleaned-headers - (concat mh-new-draft-cleaned-headers "\\|^Some-Field:")) +(setq mh-scan-valid-regexp "[0-9]+[+D^ ]$") @end lisp -@cindex regular expressions - -This appends the regular expression @samp{\\|^Some-Field:} to the -variable (@pxref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}). 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 Customizing Draft Editing, Customizing Moving Mail, Customizing Sending, Customizing mh-e -@section Editing a Draft - -@cindex editing 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: - -@table @code -@item mh-yank-from-start-of-msg -How to yank when region not set (default: @code{t}). - -@item mh-ins-buf-prefix -Indent for yanked messages (default: @samp{"> "}). - -@item mail-citation-hook -Functions to run on yanked messages (default: @code{nil}). - -@item mh-delete-yanked-msg-window -Delete message window on yank (default: @code{nil}). - -@c Need the @* because otherwise TeX fills it wrong and complains -@c about overfull hbox. -@item mh-mime-content-types -List of valid content types (default: @samp{'(("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"))}). - -@item mh-mhn-args -Additional arguments for @code{mhn} (default: @code{nil}). - -@item mh-signature-file-name -File containing signature (default: @samp{"~/.signature"}). - -@item mh-before-send-letter-hook -Functions to run before sending draft (default: @code{nil}). - -@item mh-send-prog -MH program used to send messages (default: @samp{"send"}). -@end table - -@menu -* Customizing Editing Textual:: -* Customizing Editing MIME:: -* Customizing Sending Message:: -@end menu - -@node Customizing Editing Textual, Customizing Editing MIME, Customizing Draft Editing, Customizing Draft Editing -@subsection 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. - -@menu -* Customizing Inserting Letter:: -* Customizing Signature:: -@end menu - -@node Customizing Inserting Letter, Customizing Signature, Customizing Editing Textual, Customizing Editing Textual -@subsubsection Inserting letter to which you're replying - -@cindex inserting messages -@vindex @code{mh-yank-from-start-of-msg} -@vindex @code{mh-ins-buf-prefix} -@vindex @code{mail-citation-hook} -@vindex @code{mh-ins-buf-prefix} -@vindex @code{mh-delete-yanked-msg-window} - -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. 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 -@cindex Emacs, packages, supercite -citation. -@c Footnotes are fragile; hence the redundancy. -@c TeX not inserting a line break; hence the @* -@ifclear html -@footnote{@emph{Supercite} is an example of a full-bodied, full-featured -citation package. It is in Emacs versions 19.15 and later, and can be -found via anonymous @code{ftp} on @samp{archive.cis.ohio-state.edu} in -@* @file{/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z}} -@end ifclear -@ifset html -@footnote{@emph{Supercite} is an example of a full-bodied, -full-featured citation package. It is in Emacs versions 19.15 and -later, and its @sc{url} is @* -@file{<A HREF="ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z">ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z</A>}} -@end ifset -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} 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 Customizing Signature, , Customizing Inserting Letter, Customizing Editing Textual -@subsubsection Inserting your signature - -@cindex inserting signature -@cindex signature -@vindex @code{mh-signature-file-name} -@cindex @file{.signature} -@cindex files, @file{.signature} - -You can change the name of the file inserted with @kbd{C-c C-s} -(@code{mh-insert-signature}) by changing @code{mh-signature-file-name} -(default: @file{"~/.signature"}). - -@node Customizing Editing MIME, Customizing Sending Message, Customizing Editing Textual, Customizing Draft Editing -@subsection Editing Multimedia Messages - -@cindex MIME -@cindex multimedia mail -@vindex @code{mh-mime-content-types} - -The variable @code{mh-mime-content-types} contains a list of the -currently valid content types. They are listed in the table in -@ref{Customizing Draft Editing}. If you encounter a new content type, -you can add it like this: - -@vindex @code{mh-mime-content-types}, example +Now, in order to get rid of the @samp{Cursor not pointing to message} +message, you need to tell MH-E how to access the message number. You +should also see why MH-E requires that you include a message number in +the first place. + +@vindex mh-scan-msg-number-regexp, example +@vindex mh-scan-msg-search-regexp, example @lisp -(setq mh-mime-content-types (append mh-mime-content-types - '(("@var{new/type}")))) +(setq mh-scan-msg-number-regexp "^.* \\([0-9]+\\)[+D^ ]$") +(setq mh-scan-msg-search-regexp " %d[+D^ ]$") @end lisp -Emacs macros can be used to insert enriched text directives like -@samp{<bold>}. The following code will make, for example, @kbd{C-c t -b} insert the @samp{<bold>} directive. - -@smallexample -@group -@i{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") - ;; @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} -@end group -@end smallexample - -To use the function @code{add-enriched-text}, first create key bindings -for it (@pxref{Customizing Sending}). Then, 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>}. You may also be -interested in investigating @code{sgml-mode}. - -@menu -* Customizing Sending MIME:: -@end menu - -@node Customizing Sending MIME, , Customizing Editing MIME, Customizing Editing MIME -@subsubsection Readying multimedia messages for sending - -@vindex @code{mh-mhn-args} - -If you wish to pass additional arguments to @code{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 @code{-check}. The recipient of your message can -then run @code{mhn -check} on the message---@code{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. - -@node Customizing Sending Message, , Customizing Editing MIME, Customizing Draft Editing -@subsection Sending a Message - -@cindex sending mail -@cindex spell check -@vindex @code{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: - -@i{Spell-check message via mh-before-send-letter-hook} - -@vindex @code{mh-before-send-letter-hook}, example +In order to get the next and previous commands working, add this. + +@vindex mh-scan-good-msg-regexp, example @lisp -(add-hook 'mh-before-send-letter-hook 'ispell-message) +(setq mh-scan-good-msg-regexp "^.* \\([0-9]+\\)[+D^ ]$") @end lisp -@cindex @code{send} -@cindex MH commands, @code{send} -@vindex @code{mh-send-prog} - -In case the MH @code{send} program is installed under a different name, -use @code{mh-send-prog} to tell mh-e the name. - -@node Customizing Moving Mail, Customizing Searching, Customizing Draft Editing, Customizing mh-e -@section Moving Your Mail Around - -@cindex processing mail - -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. - -@table @code -@item mh-inc-prog -Program to incorporate mail (default: @samp{"inc"}). - -@item mh-inc-folder-hook -Functions to run when incorporating mail (default: @code{nil}). - -@item mh-delete-msg-hook -Functions to run when deleting messages (default: @code{nil}). - -@item mh-print-background -Print in foreground or background (default: @code{nil}). - -@item mh-lpr-command-format -Command used to print (default: @samp{"lpr -J '%s'"}). - -@item mh-default-folder-for-message-function -Function to generate a default folder (default: @code{nil}). - -@item mh-auto-folder-collect -Collect folder names in background at startup (default: @code{t}). - -@item mh-recursive-folders -Collect nested folders (default: @code{nil}). - -@item mh-refile-msg-hook -Functions to run when refiling message (default: @code{nil}). - -@item mh-store-default-directory -Default directory for storing files created by @code{uuencode} or @code{shar} -(default: @code{nil}). - -@item mh-sortm-args -Additional arguments for @code{sortm} (default: @code{nil}). - -@item mh-scan-prog -Program to scan messages (default: @samp{"scan"}). - -@item mh-before-quit-hook -Functions to run before quitting (default: @code{nil}). See also -@code{mh-quit-hook}. - -@item mh-quit-hook -Functions to run after quitting (default: @code{nil}). See also -@code{mh-before-quit-hook}. -@end table - -@menu -* Customizing Incorporating:: -* Customizing Deleting:: -* Customizing Organizing:: -* Customizing Printing:: -* Customizing Files and Pipes:: -* Customizing Finishing Up:: -@end menu - -@node Customizing Incorporating, Customizing Deleting, Customizing Moving Mail, Customizing Moving Mail -@subsection Incorporating Your Mail - -@cindex incorporating -@vindex @code{mh-inc-prog} -@cindex @code{inc} -@cindex MH commands, @code{inc} -@vindex @code{mh-progs} -@vindex @code{mh-scan-prog} -@vindex @code{mh-inc-folder-hook} - -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 @code{inc} that uses a different -format (see @code{mh-profile}(5)). You'll then need to modify several -variables appropriately; see @code{mh-scan-prog} below. 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 @code{mh-execute-commands} -@findex @code{mh-rescan-folder}, example -@findex @code{mh-show}, example -@vindex @code{mh-inc-folder-hook}, example +Note that the current message isn't marked with a @samp{+} when moving +between the next and previous messages. Here is the code required to +get this working. + +@vindex set-mh-cmd-note, example +@vindex mh-scan-cur-msg-number-regexp, example + +@lisp +(set-mh-cmd-note 76) +(setq mh-scan-cur-msg-number-regexp "^.* \\([0-9]+\\)\\+$") +@end lisp + +Finally, add the following to delete and refile messages. + +@vindex mh-scan-deleted-msg-regexp, example +@vindex mh-scan-refiled-msg-regexp, example @lisp -@group -@i{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) ; @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) -@end group +(setq mh-scan-deleted-msg-regexp "^.* \\([0-9]+\\)D$") +(setq mh-scan-refiled-msg-regexp "^.* \\([0-9]+\\)\\^$") @end lisp -@node Customizing Deleting, Customizing Organizing, Customizing Incorporating, Customizing Moving Mail -@subsection Deleting Your Mail - -@cindex deleting -@vindex @code{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 Customizing Organizing, Customizing Printing, Customizing Deleting, Customizing Moving Mail -@subsection Organizing Your Mail with Folders - -@cindex using folders -@vindex @code{mh-recursive-folders} -@vindex @code{mh-auto-folder-collect} - -By default, operations on folders work only one level at a time. Set -@code{mh-recursive-folders} 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 variable -@code{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 @kbd{o} (@code{mh-refile-msg})). If you have a lot of folders and -you have @code{mh-recursive-folders} set, this could take a while, which -is why it's nice to do the folder collection in the background. - -@vindex @code{mh-default-folder-for-message-function} -@findex @code{mh-refile-msg} -@findex @code{mh-to-fcc} -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -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. The generated folder name should be a -string with a @samp{+} 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 @samp{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 @file{~/.emacs}, however. If you use this to store messages -in a subfolder of your Mail directory, you can modify the line that -starts @samp{(format +%s...} and insert your subfolder after the folder -symbol @samp{+}. -@c Note for me: if I insert a new version, don't forget to remove the -@c "a/" from the folder name. - -@iftex -@filbreak -@end iftex - -@vindex @code{mh-default-folder-for-message-function}, example -@vindex @code{mh-user-path}, example +This is just a bare minimum; it's best to adjust all of the regular +expressions to ensure that MH-E and highlighting perform well. + +@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 -@group -@i{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 -@code{nil} if the address was not found." - (require 'rfc822) ; @r{for the rfc822 functions} - (search-forward-regexp "^From: \\(.*\\)") ; @r{grab header field contents} - (save-excursion ; @r{save state} - (let ((addr (car (rfc822-addresses ; @r{get address} - (buffer-substring (match-beginning 1) - (match-end 1))))) - (buffer (get-buffer-create " *temp*")) ; @r{set local variables} - folder) - (set-buffer buffer) ; @r{jump to temporary buffer} - (unwind-protect ; @r{run kill-buffer when done} - (progn ; @r{function grouping construct} - (insert-file-contents (expand-file-name "aliases" - mh-user-path)) - (goto-char (point-min)) ; @r{grab aliases file and go to start} - (setq folder - ;; @r{Search for the given address, even commented-out} - ;; @r{addresses are found!} - ;; @r{The function search-forward-regexp sets values that} - ;; @r{are later used by match-beginning and match-end.} - (if (search-forward-regexp (format "^;*\\(.*\\):.*%s" - addr) nil t) - ;; @r{NOTE WELL: this is what the return value looks} - ;; @r{like. You can modify the format string to match} - ;; @r{your own Mail hierarchy.} - (format "+%s" (buffer-substring - (match-beginning 1) - (match-end 1)))))) - (kill-buffer buffer)) ; @r{get rid of our temporary buffer} - folder))) ; @r{function's return value} - -(setq mh-default-folder-for-message-function 'my-mh-folder-from-address) -@end group +#! /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 -@vindex @code{mh-refile-msg-hook} - -The hook @code{mh-refile-msg-hook} is called after a message is marked -to be refiled. - -@vindex @code{mh-sortm-args} -@cindex @code{sortm} -@cindex MH commands, @code{sortm} -@findex @code{mh-sort-folder} -@cindex MH profile components, @code{sortm} -@cindex @file{.mh_profile} -@cindex files, @file{.mh_profile} - -The variable @code{mh-sortm-args} holds extra arguments to pass on to -the @code{sortm} command. 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 @code{sortm:} entry in your MH profile -(@file{~/.mh_profile}). +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. +@c ------------------------- +@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. +@c ------------------------- +@item message-mail-user-agent +In order to send mail within Gnus using MH-E, set this option to +@samp{mail-user-agent} and set the @samp{mail-user-agent} option to +@samp{Emacs interface to MH}. +@c ------------------------- +@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. Turning on +this option 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 -* Customizing Scan Line Formats:: +* Bug Reports:: +* Mailing Lists:: +* MH FAQ and Support:: +* Getting MH-E:: @end menu -@node Customizing Scan Line Formats, , Customizing Organizing, Customizing Organizing -@subsubsection Scan line formatting - -@vindex @code{mh-scan-prog} -@cindex @code{scan} -@cindex MH commands, @code{scan} -@vindex @code{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 @code{scan} -(see @code{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. - -@table @code -@item mh-valid-scan-line -@vindex @code{mh-valid-scan-line} -@cindex @code{inc} -@cindex MH commands, @code{inc} -@cindex @code{scan} -@cindex MH commands, @code{scan} -This regular expression describes a valid scan line. This is used to -eliminate error messages that are occasionally produced by @code{inc} or -@code{scan} (default: @samp{"^ *[0-9]"}). -@end table - -Next, two variables control how the message numbers are parsed. - -@table @code - -@item mh-msg-number-regexp -@vindex @code{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 @w{@samp{"^ -*\\([0-9]+\\)"}}. - -@item mh-msg-search-regexp -@vindex @code{mh-msg-search-regexp} -Given a message number (which is inserted in @samp{%d}), this regular -expression will match the scan line that it represents (default: -@samp{"^[^0-9]*%d[^0-9]"}). -@end table - -Finally, there are a slew of variables that control how mh-e marks up -the scan lines. - -@table @code -@item mh-cmd-note -@vindex @code{mh-cmd-note} -Number of characters to skip over before inserting notation (default: -4). Note how it relates to the following regular expressions. - -@item mh-deleted-msg-regexp -@vindex @code{mh-deleted-msg-regexp} -This regular expression describes deleted messages (default: -@samp{"^....D"}). See also @code{mh-note-deleted}. - -@item mh-refiled-msg-regexp -@vindex @code{mh-refiled-msg-regexp} -This regular expression describes refiled messages (default: -@samp{"^....\\^"}). See also @code{mh-note-refiled}. - -@item mh-cur-scan-msg-regexp -@vindex @code{mh-cur-scan-msg-regexp} -This regular expression matches the current message (default: -@samp{"^....\\+"}). See also @code{mh-note-cur}. - -@item mh-good-msg-regexp -@vindex @code{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: @samp{"^....[^D^]"}). - -@item mh-note-deleted -@vindex @code{mh-note-deleted} -Messages that have been deleted to are marked by this string (default: -@samp{"D"}). See also @code{mh-deleted-msg-regexp}. - -@item mh-note-refiled -@vindex @code{mh-note-refiled} -Messages that have been refiled are marked by this string (default: -@samp{"^"}). See also @code{mh-refiled-msg-regexp}. - -@item mh-note-copied -@vindex @code{mh-note-copied} -Messages that have been copied are marked by this string (default: -@samp{"C"}). - -@item mh-note-cur -@vindex @code{mh-note-cur} -The current message (in MH, not in mh-e) is marked by this string -(default: @samp{"+"}). See also @code{mh-cur-scan-msg-regexp}. - -@item mh-note-repl -@vindex @code{mh-note-repl} -Messages that have been replied to are marked by this string (default: -@samp{"-"}). - -@item mh-note-forw -@vindex @code{mh-note-forw} -Messages that have been forwarded are marked by this string (default: -@samp{"F"}). - -@item mh-note-dist -@vindex @code{mh-note-dist} -Messages that have been redistributed are marked by this string -(default: @samp{"R"}). - -@item mh-note-printed -@vindex @code{mh-note-printed} -Messages that have been printed are marked by this string (default: -@samp{"P"}). - -@item mh-note-seq -@vindex @code{mh-note-seq} -Messages in a sequence are marked by this string (default: @samp{"%"}). -@end table - -@node Customizing Printing, Customizing Files and Pipes, Customizing Organizing, Customizing Moving Mail -@subsection Printing Your Mail - -@cindex printing -@vindex @code{mh-print-background} -@vindex @code{mh-lpr-command-format} -@cindex @code{lpr} -@cindex Unix commands, @code{lpr} - -Normally messages are printed in the foreground. If this is slow on -your system, you may elect to set @code{mh-print-background} 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 Customizing Files and Pipes, Customizing Finishing Up, Customizing Printing, Customizing Moving Mail -@subsection Files and Pipes - -@cindex using files -@cindex using pipes -@findex @code{mh-store-msg} -@vindex @code{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 @code{mh-store-default-directory}, example - -@lisp -(setq mh-store-default-directory (expand-file-name "~/src/")) -@end lisp - -@findex @code{mh-store-buffer} -@cindex @code{uuencode} -@cindex Unix commands, @code{uuencode} -@cindex @code{shar} -@cindex Unix commands, @code{shar} - -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 @code{uuencode} or @code{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 Customizing Finishing Up, , Customizing Files and Pipes, Customizing Moving Mail -@subsection Finishing Up - -@cindex quitting -@vindex @code{mh-before-quit-hook} -@vindex @code{mh-quit-hook} -@findex @code{mh-execute-commands} - -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. - -@node Customizing Searching, , Customizing Moving Mail, Customizing mh-e -@section Searching Through Messages - -@cindex searching -@vindex @code{mh-pick-mode-hook} -@vindex @code{mh-partial-folder-mode-line-annotation} - -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{M-s} (@code{mh-search-folder}) is run on a new pattern. - -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, this -will be displayed after running @kbd{M-s} (@code{mh-search-folder}) to -list messages based on some search criteria (see @ref{Searching}). 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 - -@node Odds and Ends, History, Customizing mh-e, 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 list. I also -point out some additional sources of information. +@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 unless you're 110% positive we won't ask for +it. + +@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 + +The article @uref{http://www.newt.com/faq/mh.html, @cite{MH Frequently +Asked Questions (FAQ) with Answers}} 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. + +@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, , 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}. + +@cindex contributed software +@cindex manual +@cindex documentation + +In addition to the mh-e package, the +@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, +SourceForge} site also contains doc and contrib packages. The former +is the latest release of this manual, and the latter contains a few +contributed packages you might find useful. + +@node History, GFDL, 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 MH-E, versions +@cindex Reid, Brian +@cindex SourceForge +@cindex Stephen Gildea +@cindex Wohler, Bill +@cindex history of MH-E +@cindex versions 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} where it +lives today. @menu -* Bug Reports:: -* Mailing List:: -* MH FAQ:: -* Getting mh-e:: -@end menu - -@node Bug Reports, Mailing List, Odds and Ends, Odds and Ends -@appendixsec Bug Reports - -@cindex bugs -@cindex Wohler, Bill -@cindex SourceForge - -The current maintainer of mh-e is Bill Wohler -<@i{wohler@@newt.com}>. Bug reports should be filed at -@uref{https://sourceforge.net/bugs/?group_id=13357, SourceForge}. -Please include the output of -@kbd{M-x mh-version} (@pxref{Miscellaneous}) in any bug report you send. - -@node Mailing List, MH FAQ, Bug Reports, Odds and Ends -@appendixsec mh-e Mailing List - -@cindex mailing list -@cindex SourceForge - -There are actually several mailing lists for mh-e. They are -@i{mh-e-users@@lists.sourceforge.net}, -@i{mh-e-announce@@lists.sourceforge.net}, and -@i{mh-e-devel@@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, Getting mh-e, Mailing List, Odds and Ends -@appendixsec MH FAQ - -@cindex MH FAQ -@cindex FAQ - -An 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 via the World Wide Web (WWW) at -@uref{http://www.faqs.org/faqs/mail/mh-faq/part1/preamble.html, faqs.org}. - -@node Getting mh-e, , MH FAQ, Odds and Ends -@appendixsec Getting mh-e - -@cindex obtaining mh-e - -The version of mh-e in the current version of Emacs should be up to -date. It is most likely to be more up to date than the copy that comes -with the MH distribution in @file{miscellany/mh-e}. - -@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. - -If you go this route, I suggest that you extract the files from -@file{mh-e-@var{m.n}.tgz} in the following fashion: - -@smallexample -@group -% @kbd{cd} # @r{Start in your home directory} -% @kbd{mkdir lib lib/emacs} # @r{Create directory for mh-e} -% @kbd{cd lib/emacs} -% @kbd{zcat @var{path/to/}mh-e-@var{m.n}.tgz | tar xvf -} # @r{Extract files} -@end group -@end smallexample - -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -To use these new files, add the following to @file{~/.emacs}: - -@lisp -(setq load-path (cons (expand-file-name "~/lib/emacs") load-path)) -@end lisp - -@cindex news -@cindex files, @samp{MH-E-NEWS} - -That's it! 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} after running any mh-e -command. The distribution comes with a file called @file{MH-E-NEWS} so -you can see what's new. - -@node History, Copying, Odds and Ends, Top -@appendix History of mh-e - -@cindex Gildea, Stephen -@cindex Larus, Jim -@cindex Reid, Brian -@cindex SourceForge -@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:: +* From Brian Reid:: +* From Jim Larus:: +* From Stephen Gildea:: +* From Bill Wohler:: @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 +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 sub-process 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.} +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 +(draft form editing was introduced in version 7.4).}. 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 +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 @code{xmh}, in mh-e history +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 @code{xmh}. A few months later, he came back and said that he -couldn't stand @code{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. +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 +@node From Stephen Gildea, From Bill Wohler, 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 +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. +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. +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, Command Index, History, Top -@appendix GNU GENERAL PUBLIC LICENSE - -@center Version 2, June 1991 +@node From Bill Wohler, , From Stephen Gildea, History +@appendixsec From Bill Wohler + +@cindex Wohler, Bill +@cindex Bill Wohler + +The preface originally included the following text which I use to +begin my story: + +@quotation +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. Next, @w{Version +5.0} was released, which fixed some bugs and incompatibilities, and +was incorporated into @w{Emacs 19.29}. +@end quotation + +After a long break, Stephen handed the reins over to me in 2000. I +moved the project to a new site called SourceForge and organized a +great team of developers. Our first release in late 2001 was version +6. It appeared in Emacs 21.2 and had menus and tool bar buttons. + +Then, indexed searches, improved MIME handling, a speedbar, multiple +identities, alias completion, an index view of unseen messages, spam +software support, Face and X-Image-URL header field support, Fcc +completion, arbitrary range handling, and draft form editing were +introduced in the version 7 series in Emacs 21.4 (2004). + +Version 8 development was mostly driven by the rewrite of the manual. +It also brought mailutils support, S/MIME support, picon support, and +an improved interface for hiding header fields. The CVS repository was +migrated from SourceForge to Savannah (only for those files that were +already part of Emacs) and the software was completely reorganized to +push back two decades of entropy. It appeared in Emacs 22.1 (2006). + +Bill Wohler, February 2006 + +@node GFDL, GPL, History, Top +@appendix GNU FREE DOCUMENTATION LICENSE +@center Version 1.2, November 2002 @display -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @end display - -@appendixsec Preamble +@sp 1 +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document ``free'' in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@sp 1 +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque.'' + + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +@sp 1 +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +@sp 1 +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +@sp 1 +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission.@* +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement.@* +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher.@* +D. Preserve all the copyright notices of the Document.@* +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices.@* +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below.@* +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice.@* +H. Include an unaltered copy of this License.@* +I. Preserve the section Entitled ``History'', Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence.@* +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission.@* +K. For any section Entitled ``Acknowledgements'' or ``Dedications'', + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein.@* +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles.@* +M. Delete any section Entitled ``Endorsements.'' Such a section + may not be included in the Modified Version.@* +N. Do not retitle any existing section to be Entitled ``Endorsements'' + or to conflict in title with any Invariant Section.@* +O. Preserve any Warranty Disclaimers.@* +@sp 1 +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +@sp 1 +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications.'' You must delete all sections +Entitled ``Endorsements.'' +@sp 1 +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +@sp 1 +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +@sp 1 +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +@sp 1 +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document 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. +@sp 1 +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation 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. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +@end enumerate + +@unnumberedsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group +Copyright (C) @var{year} @var{your name}. +Permission is granted to copy, distribute and/or modify this document +under the terms of 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. +A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group +with the Invariant Sections being @var{list their titles}, with the +Front-Cover Texts being @var{list}, and with the Back-Cover Texts being +@var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@node GPL, Key Index, GFDL, Top +@appendix GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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 @@ -3598,7 +8726,7 @@ modification follow. @iftex -@appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION @end iftex @ifinfo @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION @@ -3860,7 +8988,7 @@ @end ifinfo @page -@appendixsec How to Apply These Terms to Your New Programs +@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 @@ -3873,7 +9001,7 @@ @smallexample @var{one line to give the program's name and an idea of what it does.} -Copyright (C) 20@var{yy} @var{name of author} +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 @@ -3887,7 +9015,7 @@ 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., -51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. @end smallexample Also add information on how to contact you by electronic and paper mail. @@ -3931,28 +9059,98 @@ library. If this is what you want to do, use the GNU Library General Public License instead of this License. -@node Command Index, Variable Index, Copying, Top +@node Key Index, Command Index, GPL, Top +@unnumbered Key (Character) Index +@printindex ky + +@node Command Index, Option Index, Key Index, Top @unnumbered Command Index - @printindex fn -@node Variable Index, Concept Index, Command Index, Top -@unnumbered Variable Index - +@node Option Index, Concept Index, Command Index, Top +@unnumbered Option (Variable) Index @printindex vr -@node Concept Index, , Variable Index, Top +@node Concept Index, , Option Index, Top @unnumbered Concept Index - @printindex cp -@contents @bye -@c XXX In the sections on customizing mh-e, you can add cross-references -@c to the Emacs manual and the Emacs Lisp manual wherever they are -@c useful. @pxref{node, , section, emacs, The GNU Emacs Manual} - -@ignore - arch-tag: b778477d-1a10-4a99-84de-f877a2ea6bef -@end ignore +@c Ispell Helpers +@c +@c The following are words that ispell should ignore that would not +@c normally be in a dictionary (global or personal). Be careful not to +@c include words here that could potentially be typos of other words +@c (such as url, elisp, or MHE). +@c +@c LocalWords: CTRL ESC SPC f's +@c LocalWords: addr Aliasfile alist +@c LocalWords: Baushke Bcc BBN Beranek bogofilter bogofilter's +@c LocalWords: cmd CMU contrib cron +@c LocalWords: DesBrisay Dcc devel dir dired docstring filll forw +@c LocalWords: GECOS Gildea Gildea's Ginnean GnuCash goto gnuserv htm +@c LocalWords: ImageMagick inbox ispell keychain +@c LocalWords: Larus licensor LocalWords lookup lpr +@c LocalWords: makeinfo mairix mbox mh mhbuild mhl mhpath mlisp +@c LocalWords: MML msg multipart +@c LocalWords: Namazu NIS nenscript nnml num +@c LocalWords: packmbox passphrase pathname prev procmail prog repl +@c LocalWords: slocal sortm SpamAssassin spammers SpamProbe SpamProbe's +@c LocalWords: sublicense supercite speedbar +@c LocalWords: Tennex texi texinfo Thelen thelenm +@c LocalWords: UCI undeleted whatnow wohler xmh ypcat +@c +@c See http://www.oreilly.com/oreilly/author/stylesheet.html. +@c See http://en.wikipedia.org/. +@c +@c Note the lowercase mh which is needed to avoid hits in the +@c functions and variables. Occasionally, check for accidental +@c inclusion of mh in text by uncommenting the following and executing +@c it with C-x C-e. You want to see "Search failed" +@c (let ((case-fold-search nil)) +@c (goto-char (point-min)) +@c (search-forward-regexp "^mh\\( \\|$\\)")) +@c +@c An extremely useful setting for texinfo-mode-hook is: +@c (add-to-list +@c 'ispell-skip-region-alist +@c (list +@c (concat "\\(@\\(small\\)?\\(example\\|lisp\\)" +@c "\\(@\\([irw]\\|code\\|var\\){[^}]+}\\|" +@c "@[@{}.]\\|" +@c "[^@]\\|" +@c "@\\(end \\)?group\\|" +@c "@\\(end \\)?cartouche\\)+" +@c "@end \\(small\\)?\\(example\\|lisp\\)\\|" +@c "@\\(code\\|command\\|file\\|kbd\\|sc\\){[^}]+}\\|" +@c "^@end [a-z]+$\\|" +@c "^@\\([fv]\\|print\\)index .*$\\|" +@c "@uref{[^,]+,\\|" +@c "@[a-z]+\\|" +@c "/[a-z.]+[/}]\\)"))))) +@c +@c Cross References +@c +@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 @ftable Sorting +@c +@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 +@c Alphabetical, pull hooks into their own table. + +@c Local Variables: +@c sentence-end-double-space: nil +@c End: