(mail-specify-envelope-from): Doc change.
[emacs.git] / man / mh-e.texi
blob406506d36a0a2ebbf0fcbb1f9448afb603758169
1 \input texinfo   @c -*-texinfo-*-
2 @c $Id: mh-e.texi,v 1.13 2002/10/02 23:24:31 karl Exp $
3 @c %**start of header
4 @setfilename ../info/mh-e
5 @settitle mh-e
6 @c %**end of header
8 @c Version variables.
9 @set EDITION 1.3
10 @set VERSION 5.0.2
11 @set UPDATED 18 February 2001
12 @set UPDATE-MONTH February 2001
14 @copying
15 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
16 @cite{mh-e, The Emacs Interface to MH}, for mh-e, Version
17 @value{VERSION}.
19 Copyright 1995, 2001, 2002 Free Software Foundation, Inc.
21 @quotation
22 Permission is granted to copy, distribute and/or modify this document
23 under the terms of the GNU Free Documentation License, Version 1.1 or
24 any later version published by the Free Software Foundation; with no
25 Invariant Sections, with the Front-Cover texts being ``A GNU
26 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
27 license is included in the section entitled ``GNU Free Documentation
28 License'' in the Emacs manual.
30 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
31 this GNU Manual, like GNU software.  Copies published by the Free
32 Software Foundation raise funds for GNU development.''
34 This document is part of a collection distributed under the GNU Free
35 Documentation License.  If you want to distribute this document
36 separately from the collection, you can do so by adding a copy of the
37 license to the document, as described in section 6 of the license.
38 @end quotation
39 @end copying
41 @setchapternewpage odd
43 @dircategory Emacs
44 @direntry
45 * MH-E: (mh-e).         Emacs interface to the MH mail system.
46 @end direntry
48 @titlepage
49 @sp 10
50 @center @titlefont{mh-e}
51 @sp 2
52 @center The Emacs Interface to MH
53 @sp 2
54 @center by Bill Wohler
55 @sp 2
56 @center Edition @value{EDITION} for mh-e Version @value{VERSION}
57 @sp 2
58 @center @value{UPDATE-MONTH}
60 @page
61 @vskip 0pt plus 1filll
62 Copyright @copyright{} 1995, 2001, 2002 Free Software Foundation, Inc.
63 @insertcopying
64 @end titlepage
66 @ifnottex
67 @node Top, Preface, (dir), (dir)
68 @top MH and Emacs
69 This is Edition @value{EDITION} of @cite{mh-e, The Emacs Interface to
70 MH}, last updated @value{UPDATED} for mh-e Version @value{VERSION}.
72 @menu
73 * Preface::                     Introduction to mh-e.
74 * Tour Through mh-e::           Use mh-e quickly!
75 * Using mh-e::                  Documentation for all commands.
76 * Customizing mh-e::            Documentation for all variables.
77 * Odds and Ends::               Getting mh-e, reporting bugs, mailing
78                                 list and FAQ.
79 * History::                     The authors speak up!
80 * Copying::                     The GNU General Public License
81 * Command Index::
82 * Variable Index::
83 * Concept Index::
84 @end menu
85 @end ifnottex
87 @node Preface, Tour Through mh-e, Top, Top
88 @unnumbered Preface
90 @cindex Emacs
91 @cindex Unix commands, Emacs
93 These chapters introduce another interface to MH that is accessible
94 through the GNU Emacs editor, namely, @emph{mh-e}.  mh-e is easy to use.
95 I don't assume that you know GNU Emacs or even MH at this point, since I
96 didn't know either of them when I discovered mh-e.  However, mh-e was
97 the tip of the iceberg, and I discovered more and more niceties about
98 GNU Emacs and MH@.  Now I'm fully hooked on both of them.
100 @cindex history
102 The mh-e package is distributed with GNU Emacs, @footnote{Note that
103 mh-e is supported with MH 6 and @w{Emacs 18} through @w{Emacs 21}.
104 Reportedly, large parts of it work with @w{MH 5} and also with
105 Lucid/XEmacs and Epoch, but there are no guarantees. It is also
106 distributed with Lucid/XEmacs, as well as with MH itself.} so you
107 shouldn't have to do anything special to use it. But it's important to
108 note a brief history of mh-e. @w{Version 3} was prevalent through the
109 @w{Emacs 18} and early @w{Emacs 19} years. Then @w{Version 4} came out
110 (@w{Emacs 19.23}), which introduced several new and changed commands.
111 Finally, @w{Version 5.0} was released, which fixed some bugs and
112 incompatibilities, and was incorporated into @w{Emacs 19.29}. This is
113 the version covered by this manual. @ref{Getting Started} will help
114 you decide which version you have.
116 If you don't already use GNU Emacs but want to learn more, you can read
117 an online tutorial by starting GNU Emacs and typing @kbd{C-h t}
118 (@code{help-with-tutorial}).  (This notation is described in
119 @ref{Conventions}.)  If you want to take the plunge, consult the
120 @iftex
121 @cite{GNU Emacs Manual},
122 @end iftex
123 @ifinfo
124 @ref{top, , GNU Emacs Manual, emacs, The GNU Emacs Manual},
125 @end ifinfo
126 from the Free Software Foundation.
128 If more information is needed, you can go to the Unix manual pages of
129 the individual MH commands.  When the name is not obvious, I'll guide
130 you to a relevant MH manual page that describes the action more fully.
132 I hope you enjoy these chapters!  If you have any comments, or
133 suggestions for this document, please let me know.
135 @noindent
136 Bill Wohler <@i{wohler@@newt.com}>@*
137 8 February 1995
139 @node    Tour Through mh-e, Using mh-e, Preface, Top
140 @chapter Tour Through mh-e
142 This chapter introduces some of the terms you'll need to know and then
143 takes you on a tour of mh-e. @footnote{The keys mentioned in these
144 chapters refer to the default key bindings.  If you've changed the
145 bindings, refer to the command summaries at the beginning of each major
146 section in @ref{Using mh-e}, for a mapping between default key bindings
147 and function names.}  When you're done, you'll be able to send, read,
148 and file mail, which is all that a lot of people ever do.  But if you're
149 the curious type, you'll read @ref{Using mh-e} to be able to use all
150 the features of mh-e.  If you're the adventurous type, you'll read
151 @ref{Customizing mh-e} to make mh-e do what you want.  I suggest you
152 read this chapter first to get the big picture, and then you can read
153 the other two as you wish.
155 @menu
156 * Conventions::                 GNU Emacs Terms and Conventions
157 * Getting Started::
158 * Sending Mail Tour::
159 * Reading Mail Tour::
160 * Processing Mail Tour::
161 * Leaving mh-e::
162 * More About mh-e::
163 @end menu
165 @node Conventions, Getting Started, Tour Through mh-e, Tour Through mh-e
166 @section GNU Emacs Terms and Conventions
168 @cindex Emacs, terms and conventions
170 @cindex Emacs
171 @cindex Unix commands, Emacs
173 If you're an experienced Emacs user, you can skip the following
174 conventions and definition of terms and go directly to @ref{Getting
175 Started} below.  The conventions are as follows:
177 @table @kbd
178 @item C-x
179 Hold down the @key{CTRL} (Control) key and press the @kbd{x} key.
180 @item M-x
181 Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key.
183 Since some keyboards don't have a @key{META} key, you can generate
184 @kbd{M-x}, for example, by pressing @key{ESC} (Escape), @emph{releasing
185 it}, @footnote{This is emphasized because pressing ESC twice or holding
186 it down a second too long so that it repeats gives you an error message.}
187 and then pressing the @kbd{x} key.
188 @item RET
189 Press the @key{RETURN} or @key{ENTER} key.  This is normally used to
190 complete a command.
191 @item SPC
192 Press the space bar.
193 @item TAB
194 Press the @key{TAB} key.
195 @item DEL
196 Press the @key{DELETE} key.
197 @item BS
198 Press the @key{BACKSPACE} key. @footnote{If you are using Version 20
199 or earlier of Emacs, you will need to use the @key{DEL} key.}
200 @end table
202 @cindex Emacs, prefix argument
203 @cindex prefix argument
205 A @dfn{prefix argument} allows you to pass an argument to any Emacs
206 function.  To pass an argument, type @kbd{C-u} before the Emacs command
207 or keystroke.  Numeric arguments can be passed as well.  For example, to
208 insert five f's, use @kbd{C-u 5 f}.  There is a default of four when
209 using @kbd{C-u}, and you can use multiple prefix arguments to provide
210 arguments of powers of four.  To continue our example, you could insert
211 four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with
212 @kbd{C-u C-u C-u f}, and so on.  Numeric and valueless negative
213 arguments can also be inserted with the @key{META} key.  Examples
214 include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which
215 specifies a negative argument with no particular value.
217 @sp 2
218 @need 1000
219 @center @strong{NOTE}
221 @quotation
222 The prefix @kbd{C-u} or @kbd{M-} is not necessary in mh-e's MH-Folder
223 modes (@pxref{Reading Mail Tour}).  In these modes, simply enter the
224 numerical argument before entering the command.
225 @end quotation
227 @cindex point
228 @cindex Emacs, point
229 @cindex mark
230 @cindex Emacs, mark
231 @cindex region
232 @cindex Emacs, region
234 There are several other terms that are used in Emacs that you should
235 know.  The @dfn{point} is where the cursor currently is.  You can save
236 your current place in the file by setting a @dfn{mark}.  This operation
237 is useful in several ways.  The mark can be later used when defining a
238 @dfn{region}, which is the text between the point and mark.  Many
239 commands operate on regions, such as those for deleting text or filling
240 paragraphs.  A mark can be set with @kbd{C-@@} (or @kbd{C-SPC}).
242 @cindex minibuffer
243 @cindex Emacs, minibuffer
244 @cindex file completion
245 @cindex Emacs, file completion
247 The @dfn{minibuffer} is the bottom line of the Emacs window, where all
248 prompting and multiple-character input is directed.  If you are prompted
249 for information in the minibuffer, such as a filename, Emacs can help
250 you complete your answer if you type @key{SPC} or @key{TAB}.  A second
251 @key{SPC} or @key{TAB} will list all possibilities at that point.  The
252 minibuffer is also where you enter Emacs function names after typing
253 @kbd{M-x}.  For example, in the first paragraph, I mentioned that you
254 could obtain help with @kbd{C-h t} (@code{help-with-tutorial}).  What
255 this means is that you can get a tutorial by typing either @kbd{C-h t}
256 or @kbd{M-x help-with-tutorial}.  In the latter case, you are prompted
257 for @samp{help-with-tutorial} in the minibuffer after typing @kbd{M-x}.
259 @cindex interrupting
260 @cindex Emacs, interrupting
261 @cindex quitting
262 @cindex Emacs, quitting
264 @i{In case of trouble:} Emacs can be interrupted at any time with
265 @kbd{C-g}.  For example, if you've started a command that requests that
266 you enter something in the minibuffer, but then you change your mind,
267 type @kbd{C-g} and you'll be back where you started.  If you want to
268 exit Emacs entirely, use @kbd{C-x C-c}.
270 @node Getting Started, Sending Mail Tour, Conventions, Tour Through mh-e
271 @section Getting Started
273 Because there are many old versions of mh-e out there, it is important to
274 know which version you have.  I'll be talking about @w{Version 5} which
275 is similar to @w{Version 4} and vastly different from @w{Version 3}.
277 First, enter @kbd{M-x load-library @key{RET} mh-e
278 @key{RET}}. @footnote{You wouldn't ordinarily do this.}  The message,
279 @samp{Loading mh-e...done}, should be displayed in the minibuffer.  If
280 you get @samp{Cannot open load file: mh-e}, then your Emacs is very
281 badly configured, or mh-e is missing.  You may wish to have your system
282 administrator install a new Emacs or at least the latest mh-e files.
284 Having loaded mh-e successfully, enter @kbd{M-x mh-version @key{RET}}.
285 The version of mh-e should be displayed.  Hopefully it says that you're
286 running @w{Version @value{VERSION}} which is the latest version as of
287 this printing.  If instead Emacs beeps and says @samp{[No match]}, then
288 you're running an old version of mh-e.
290 If these tests reveal a non-existent or old version of mh-e, please
291 consider obtaining a new version.  You can have your system
292 administrator upgrade the system-wide version, or you can install your
293 own personal version.  It's really quite easy; instructions for getting
294 and installing mh-e are in @ref{Getting mh-e}.
296 @cindex @code{install-mh}
297 @cindex MH commands, @code{install-mh}
299 Also, older versions of mh-e assumed that you had already set up your MH
300 environment.  Newer versions set up a new MH environment for you by
301 running @code{install-mh} and notifying you of this fact with the
302 message in a temporary buffer:
304 @example
305 I'm going to create the standard MH path for you.
306 @end example
308 Therefore, if you've never run MH before and you're using an old version
309 of mh-e, you need to run @code{install-mh} from the shell before you
310 continue the tour.  If you don't, you'll be greeted with the error
311 message: @samp{Can't find MH profile}.
313 @cindex @file{.emacs}
314 @cindex files, @file{.emacs}
316 If, during the tour described in this chapter, you see a message like:
317 @samp{Searching for program: no such file or directory,
318 /usr/local/bin/mhpath}, it means that the MH programs and files are kept
319 in a nonstandard directory.  In this case, simply add the following to
320 @file{~/.emacs} and restart @code{emacs}.
322 @vindex @code{mh-progs}, example
323 @vindex @code{mh-lib}, example
325 @c XXX Real example for really naive user?
326 @example
327 @group
328 (setq mh-progs "@var{/path/to/MH/binary/directory/}")
329 (setq mh-lib "@var{/path/to/MH/library/directory/}")
330 @end group
331 @end example
333 @cindex ~
335 The @samp{~} notation used by @file{~/.emacs} above represents your home
336 directory.  This is used by the @code{bash} and @code{csh} shells.  If
337 your shell does not support this feature, you could use the environment
338 variable @samp{$HOME} (such as @file{$HOME/.emacs}) or the absolute path
339 (as in @file{/home/wohler/.emacs}) instead.
341 At this point, you should see something like the screen in the
342 figure in @ref{Reading Mail Tour}.  We're now ready to move on.
344 @node Sending Mail Tour, Reading Mail Tour, Getting Started, Tour Through mh-e
345 @section Sending Mail
347 @cindex sending mail
348 @findex @code{mh-smail}
350 Let's start our tour by sending ourselves a message which we can later
351 read and process.  Enter @kbd{M-x mh-smail} to invoke the mh-e program
352 to send messages.  You will be prompted in the minibuffer by @samp{To:}.
353 Enter your login name.  The next prompt is @samp{cc:}.  Hit @key{RET} to
354 indicate that no carbon copies are to be sent.  At the @samp{Subject:}
355 prompt, enter @kbd{Test} or anything else that comes to mind.
357 @cindex MH-Letter mode
358 @cindex modes, MH-Letter
359 @cindex mode
361 Once you've specified the recipients and subject, your message appears
362 in an Emacs buffer whose mode @footnote{A @dfn{mode} changes Emacs to
363 make it easier to edit a particular type of text.} is MH-Letter.
364 Enter some text in the body of the message, using normal Emacs commands.
365 You should now have something like this: @footnote{If you're running Emacs
366 under the X Window System, then you would also see a menubar.  I've left
367 out the menubar in all of the example screens.}
369 @example
370 @group
371 @cartouche
378 -----Emacs: *scratch*         (Lisp Interaction)--All-------------------
379 To: wohler
381 Subject: Test
382 --------
383   This is a test message to get the wheels churning...#
386 --**-@{draft@}      (MH-Letter)--All-------------------------------------
388 @end cartouche
389 @i{mh-e message composition window}
390 @end group
391 @end example
393 @cindex MH-Letter mode
394 @cindex modes, MH-Letter
396 Note the line of dashes that separates the header and the body of the
397 message.  It is essential that these dashes (or a blank line) are
398 present or the body of your message will be considered to be part of
399 the header.
401 There are several commands specific to MH-Letter mode, but at
402 this time we'll only use @kbd{C-c C-c} to send your message.  Type
403 @kbd{C-c C-c} now.  That's all there is to it!
405 @node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through mh-e
406 @section Receiving Mail
408 @cindex reading mail
409 @findex @code{mh-rmail}
410 @cindex @code{inc}
411 @cindex MH commands, @code{inc}
412 @cindex @code{scan}
413 @cindex MH commands, @code{scan}
414 @cindex MH-Folder mode
415 @cindex modes, MH-Folder
417 To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}.
418 This incorporates the new mail and put the output from @code{inc}
419 (called @dfn{scan lines} after the MH program @code{scan} which prints a
420 one-line summary of each message) into a buffer called @samp{+inbox}
421 whose major mode is MH-Folder.
423 @sp 2
424 @need 1000
425 @center @strong{NOTE}
427 @quotation
428 The @kbd{M-x mh-rmail} command will show you only new mail, not old
429 mail.  If you were to run this tour again, you would use @kbd{M-r} to
430 pull all your messages into mh-e.
431 @end quotation
433 You should see the scan line for your message, and perhaps others.  Use
434 @kbd{n} or @kbd{p} to move the cursor to your test message and type
435 @key{RET} to read your message.  You should see something like:
437 @example
438 @group
439 @cartouche
440   3  24Aug root      received fax files on Wed Aug 24 11:00:13 PDT 1994
441 # 4+ 24Aug To:wohler Test<<This is a test message to get the wheels chu
443 --%%-@{+inbox@} 4 msgs (1-4)      (MH-Folder Show)--Bot------------------
444 To: wohler
445 Subject: Test
446 Date: Wed, 24 Aug 1994 13:01:13 -0700
447 From: Bill Wohler <wohler@@newt.com>
449   This is a test message to get the wheels churning...
455 -----@{show-+inbox@} 4      (MH-Show)--Bot-------------------------------
457 @end cartouche
458 @i{After incorporating new messages}
459 @end group
460 @end example
462 If you typed a long message, you can view subsequent pages with @key{SPC}
463 and previous pages with @key{DEL}.
465 @node Processing Mail Tour, Leaving mh-e, Reading Mail Tour, Tour Through mh-e
466 @section Processing Mail
468 @cindex processing mail
470 The first thing we want to do is reply to the message that we sent
471 ourselves.  Ensure that the cursor is still on the same line as your
472 test message and type @kbd{r}.  You are prompted in the minibuffer with
473 @samp{Reply to whom:}.  Here mh-e is asking whether you'd like to reply
474 to the original sender only, to the sender and primary recipients, or to
475 the sender and all recipients.  If you simply hit @key{RET}, you'll
476 reply only to the sender.  Hit @key{RET} now.
478 You'll find yourself in an Emacs buffer similar to that when you were
479 sending the original message, like this:
481 @example
482 @group
483 @cartouche
484 To: wohler
485 Subject: Re: Test
486 In-reply-to: Bill Wohler's message of Wed, 24 Aug 1994 13:01:13 -0700
487              <199408242001.NAA00505@@newt.com>
488 --------
491 --**-@{draft@}      (MH-Letter)--All-------------------------------------
492 To: wohler
493 Subject: Test
494 Date: Wed, 24 Aug 1994 13:01:13 -0700
495 From: Bill Wohler <wohler@@newt.com>
497   This is a test message to get the wheels churning...
499 -----@{show-+inbox@} 4      (MH-Show)--Bot-------------------------------
500 Composing a reply...done
501 @end cartouche
502 @i{Composition window during reply}
503 @end group
504 @end example
506 By default, MH will not add you to the address list of your replies, so
507 if you find that the @samp{To:} header field is missing, don't worry.
508 In this case, type @kbd{C-c C-f C-t} to create and go to the @samp{To:}
509 field, where you can type your login name again.  You can move around
510 with the arrow keys or with @kbd{C-p} (@code{previous-line}), @kbd{C-n}
511 (@code{next-line}), @kbd{C-b} (@code{backward-char}), and @kbd{C-f}
512 (@code{forward-char}) and can delete the previous character with
513 @key{BS}.  When you're finished editing your message, send it with
514 @kbd{C-c C-c} as before.
516 @cindex folder
518 You'll often want to save messages that were sent to you in an organized
519 fashion.  This is done with @dfn{folders}.  You can use folders to keep
520 messages from your friends, or messages related to a particular topic.
521 With your cursor in the MH-Folder buffer and positioned on the message
522 you sent to yourself, type @kbd{o} to output (@code{refile} in MH
523 parlance) that message to a folder.  Enter @kbd{test} at the
524 @samp{Destination:} prompt and type @kbd{y} (or @key{SPC}) when mh-e
525 asks to create the folder @samp{+test}.  Note that a @samp{^} (caret)
526 appears next to the message number, which means that the message has
527 been marked for refiling but has not yet been refiled.  We'll talk about
528 how the refile is actually carried out in a moment.
530 @cindex MH-Folder mode
531 @cindex modes, MH-Folder
533 Your previous reply is now waiting in the system mailbox.  You
534 incorporate this mail into your MH-Folder buffer named @samp{+inbox}
535 with the @kbd{i} command.  Do this now.  After the mail is incorporated,
536 use @kbd{n} or @kbd{p} to move the cursor to the new message, and read
537 it with @key{RET}.  Let's delete this message by typing @kbd{d}.  Note
538 that a @samp{D} appears next to the message number.  This means that the
539 message is marked for deletion but is not yet deleted.  To perform the
540 deletion (and the refile we did previously), use the @kbd{x} command.
542 @findex @code{mh-smail}
544 If you want to send another message you can use @kbd{m} instead of
545 @kbd{M-x mh-smail}.  So go ahead, send some mail to your friends!
547 @node Leaving mh-e, More About mh-e, Processing Mail Tour, Tour Through mh-e
548 @section Leaving mh-e
550 @cindex Emacs, quitting
551 @cindex quitting
553 You may now wish to exit @code{emacs} entirely.  Use @kbd{C-x C-c} to
554 exit @code{emacs}.  If you exited without running @kbd{x} in the
555 @samp{+inbox} buffer, Emacs will offer to save it for you.  Type @kbd{y}
556 or @key{SPC} to save @samp{+inbox} changes, which means to perform any refiles
557 and deletes that you did there.
559 If you don't want to leave Emacs, you can type @kbd{q} to bury (hide)
560 the mh-e folder or delete them entirely with @kbd{C-x k}.  You can then
561 later recall them with @kbd{C-x b} or @kbd{M-x mh-rmail}.
563 @node More About mh-e,  , Leaving mh-e, Tour Through mh-e
564 @section More About mh-e
566 These are the basic commands to get you going, but there are plenty
567 more.  If you think that mh-e is for you, read @ref{Using mh-e} and
568 @ref{Customizing mh-e} to find out how you can:
570 @itemize @bullet
571 @item
572 Print your messages.  (@ref{Printing} and @ref{Customizing Printing}.)
573 @item
574 Edit messages and include your signature.  (@ref{Draft Editing}
575 and @ref{Customizing Draft Editing}.)
576 @item
577 Forward messages.  (@ref{Forwarding} and @ref{Customizing Forwarding}.)
578 @item
579 Read digests.  (@ref{Viewing}.)
580 @item
581 Edit bounced messages.  (@ref{Old Drafts} and @ref{Customizing Old Drafts}.)
582 @item
583 Send multimedia messages.  (@ref{Editing MIME} and @ref{Customizing Editing MIME}.)
584 @item
585 Process mail that was sent with @code{shar} or @code{uuencode}.
586 (@ref{Files and Pipes}.)
587 @item
588 Use sequences conveniently.  (@ref{Sequences}.)
589 @item
590 Show header fields in different fonts.  (@ref{Customizing Viewing}.)
591 @item
592 Find previously refiled messages.  (@ref{Searching}.)
593 @item
594 Place messages in a file.  (@ref{Files and Pipes}.)
595 @end itemize
597 Remember that you can also use MH commands when you're not running mh-e
598 (and when you are!).
600 @node    Using mh-e, Customizing mh-e, Tour Through mh-e, Top
601 @chapter Using mh-e
603 This chapter leaves the tutorial style and goes into more detail about
604 every mh-e command.  The default, or "out of the box," behavior is
605 documented.  If this is not to your liking (for instance, you print with
606 something other than @code{lpr)}, see the associated section in
607 @ref{Customizing mh-e} which is organized exactly like this chapter.
609 @cindex Emacs, functions; describe-mode
610 @cindex Emacs, online help
611 @cindex online help
613 There are many commands, but don't get intimidated.  There are command
614 summaries at the beginning of each section.  In case you have or would
615 like to rebind the keys, the command summaries also list the associated
616 Emacs Lisp function.  Furthermore, even if you're stranded on a desert
617 island with a laptop and are without your manuals, you can get a summary
618 of all these commands with GNU Emacs online help: use @kbd{C-h m}
619 (@code{describe-mode}) for a brief summary of commands or @kbd{C-h i} to
620 read this manual via Info.  The online help is quite good; try running
621 @kbd{C-h C-h C-h}.  This brings up a list of available help topics, one
622 of which displays the documentation for a given key (like @kbd{C-h k
623 C-n}).  In addition, review @ref{Conventions}, if any of the GNU Emacs
624 conventions are strange to you.
626 Let's get started!
628 @menu
629 * Reading Mail::
630 * Sending Mail::
631 * Draft Editing::
632 * Moving Mail::
633 * Searching::
634 * Sequences::
635 * Miscellaneous::
636 @end menu
638 @node Reading Mail, Sending Mail, Using mh-e, Using mh-e
639 @section Reading Your Mail
641 @cindex reading mail
642 @findex @code{mh-rmail}
643 @cindex MH-Folder mode
644 @cindex modes, MH-Folder
646 The mh-e entry point for reading mail is @kbd{M-x mh-rmail}.  This
647 command incorporates your mail and creates a buffer called @samp{+inbox}
648 in MH-Folder mode.  The @kbd{M-x mh-rmail} command shows you only new
649 mail, not old mail. @footnote{If you want to see your old mail as well,
650 use @kbd{M-r} to pull all your messages into mh-e.  Or, give a prefix
651 argument to @code{mh-rmail} so it will prompt you for folder to visit
652 like @kbd{M-f} (for example, @kbd{C-u M-x mh-rmail @key{RET} bob
653 @key{RET}}).  Both @kbd{M-r} and @kbd{M-f} are described in
654 @ref{Organizing}.}  The @samp{+inbox} buffer contains @dfn{scan lines},
655 which are one-line summaries of each incorporated message.  You can
656 perform most MH commands on these messages via one-letter commands
657 discussed in this chapter.  See @code{scan}(1) for a description of the
658 contents of the scan lines, and see the Figure in @ref{Reading Mail
659 Tour}, for an example.
661 @table @kbd
662 @item RET
663 Display a message (@code{mh-show}).
665 @item SPC
666 Go to next page in message (@code{mh-page-msg}).
668 @item BS
669 Go to previous page in message (@code{mh-previous-page}).
671 @item , (comma)
672 Display a message with all header fields (@code{mh-header-display}).
674 @item M-SPC
675 Go to next message in digest (@code{mh-page-digest}).
677 @item M-BS
678 Go to previous message in digest (@code{mh-page-digest-backwards}).
680 @item M-b
681 Break up digest into separate messages (@code{mh-burst-digest}).
683 @item n
684 Display next message (@code{mh-next-undeleted-msg}).
686 @item p
687 Display previous message (@code{mh-previous-undeleted-msg}).
689 @item g
690 Go to a message (@code{mh-goto-msg}).
692 @item M-<
693 Go to first message (@code{mh-first-msg}).
695 @item M->
696 Go to last message (@code{mh-last-msg}).
698 @item t
699 Toggle between MH-Folder and MH-Folder Show modes (@code{mh-toggle-showing}).
700 @end table
702 @menu
703 * Viewing::
704 * Moving Around::
705 @end menu
707 @node Viewing, Moving Around, Reading Mail, Reading Mail
708 @subsection Viewing Your Mail
710 @findex @code{mh-show}
711 @findex @code{mh-page-msg}
712 @findex @code{mh-previous-page}
713 @findex @code{mh-header-display}
715 The @kbd{RET} (@code{mh-show}) command displays the message that the
716 cursor is on.  If the message is already displayed, it scrolls to the
717 beginning of the message.  Use @key{SPC} (@code{mh-page-msg}) and
718 @key{BS} (@code{mh-previous-page}) to move forwards and backwards one
719 page at a time through the message.  You can give either of these
720 commands a prefix argument that specifies the number of lines to scroll
721 (such as @kbd{10 SPC}).  mh-e normally hides a lot of the
722 superfluous header fields that mailers add to a message, but if you wish
723 to see all of them, use the @kbd{,} (comma; @code{mh-header-display})
724 command.
726 @menu
727 * Reading Digests::
728 * Reading MIME::
729 @end menu
731 @node Reading Digests, Reading MIME, Viewing, Viewing
732 @subsubsection Reading Digests
734 @cindex digests
735 @findex @code{mh-page-digest}
736 @findex @code{mh-page-digest-backwards}
738 A digest is a message that contains other messages.  Special mh-e
739 commands let you read digests conveniently.  You can use @key{SPC} and
740 @key{BS} to page through the digest as if it were a normal message, but
741 if you wish to skip to the next message in the digest, use @kbd{M-SPC}
742 (@code{mh-page-digest}).  To return to a previous message, use
743 @kbd{M-BS} (@code{mh-page-digest-backwards}).
745 @cindex @code{burst}
746 @cindex MH commands, @code{burst}
747 @cindex MH-Folder Show mode
748 @cindex modes, MH-Folder Show
749 @findex @code{mh-burst-digest}
751 @c There was a page break at the colon in the following paragraph which
752 @c broke the transition to the example.
753 @need 2000
755 Another handy command is @kbd{M-b} (@code{mh-burst-digest}).  This
756 command uses the MH command @code{burst} to break out each message in
757 the digest into its own message.  Using this command, you can quickly
758 delete unwanted messages, like this: Once the digest is split up, toggle
759 out of MH-Folder Show mode with @kbd{t} (@pxref{Moving Around}) so that
760 the scan lines fill the screen and messages aren't displayed.  Then use
761 @kbd{d} (@pxref{Deleting}) to quickly delete messages that you don't
762 want to read (based on the @samp{Subject:} header field).  You can also
763 burst the digest to reply directly to the people who posted the messages
764 in the digest.  One problem you may encounter is that the @samp{From:}
765 header fields are preceded with a @samp{>} so that your reply can't
766 create the @samp{To:} field correctly.  In this case, you must correct
767 the @samp{To:} field yourself.  This is described later in @ref{Editing
768 Textual}.
770 @node Reading MIME,  , Reading Digests, Viewing
771 @subsubsection Reading Multimedia Mail
773 @cindex multimedia mail
774 @cindex MIME
775 @cindex @code{show}
776 @cindex MH commands, @code{show}
777 @cindex @code{mhshow}
778 @cindex MH commands, @code{mhshow}
780 MH has the ability to read @dfn{@sc{mime}} (Multipurpose Internet Mail
781 Extensions) messages.  Unfortunately, mh-e does not yet have this
782 ability, so you have to use the MH commands @code{show} or @code{mhshow}
783 from the shell to read @sc{mime} messages.  @footnote{You can call them
784 directly from Emacs if you're running the X Window System: type @kbd{M-!
785 xterm -e mhshow @var{message-number}}.  You can leave out the @code{xterm
786 -e} if you use @code{mhlist} or @code{mhstore}.}
788 @node Moving Around,  , Viewing, Reading Mail
789 @subsection Moving Around
791 @cindex moving between messages
792 @findex @code{mh-next-undeleted-msg}
793 @findex @code{mh-previous-undeleted-msg}
794 @findex @code{mh-goto-msg}
795 @findex @code{mh-last-msg}
796 @findex @code{mh-first-msg}
798 To move on to the next message, use the @kbd{n}
799 (@code{mh-next-undeleted-msg}) command; use the @kbd{p}
800 (@code{mh-previous-undeleted-msg}) command to read the previous message.
801 Both of these commands can be given a prefix argument to specify how
802 many messages to skip (for example, @kbd{5 n}).  You can also move to a
803 specific message with @kbd{g} (@code{mh-goto-msg}).  You can enter the
804 message number either before or after typing @kbd{g}.  In the latter
805 case, Emacs prompts you.  Finally, you can go to the first or last
806 message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->}
807 (@code{mh-last-msg}) respectively.
809 @cindex MH-Folder mode
810 @cindex modes, MH-Folder
812 You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) and
813 @kbd{C-n} (@code{next-line}) to move up and down the scan lines in the
814 MH-Folder window.  These commands can be used in conjunction with
815 @kbd{RET} to look at deleted or refiled messages.
817 @cindex MH-Folder mode
818 @cindex modes, MH-Folder
819 @cindex MH-Folder Show mode
820 @cindex modes, MH-Folder Show
821 @cindex junk mail
822 @findex @code{mh-toggle-showing}
824 The command @kbd{t} (@code{mh-toggle-showing}) switches between
825 MH-Folder mode and MH-Folder Show mode.  @footnote{For you Emacs
826 wizards, this is implemented as an Emacs minor mode.} MH-Folder mode
827 turns off the associated show buffer so that you can perform operations
828 on the messages quickly without reading them.  This is an excellent way
829 to prune out your junk mail or to refile a group of messages to another
830 folder for later examination.
832 @node Sending Mail, Draft Editing, Reading Mail, Using mh-e
833 @section Sending Mail
835 @cindex sending mail
836 @findex @code{mh-smail}
838 You can send a mail message in several ways.  You can call @kbd{M-x
839 mh-smail} directly, or from the command line like this:
841 @cindex starting from command line
843 @example
844 % @kbd{emacs -f mh-smail}
845 @end example
847 From within mh-e's MH-Folder mode, other methods of sending mail
848 are available as well:
850 @table @kbd
851 @item m
852 Compose a message (@code{mh-send}).
854 @item r
855 Reply to a message (@code{mh-reply}).
857 @item f
858 Forward message(s) (@code{mh-forward}).
860 @item M-d
861 Redistribute a message (@code{mh-redistribute}).
863 @item M-e
864 Edit a message that was bounced by mailer (@code{mh-extract-rejected-mail}).
866 @item M-a
867 Edit a message to send it again (@code{mh-edit-again}).
868 @end table
870 @cindex MH-Folder mode
871 @cindex modes, MH-Folder
872 @cindex MH-Letter mode
873 @cindex modes, MH-Letter
874 @findex @code{mh-send}
876 From within a MH-Folder buffer, you can simply use the command @kbd{m}
877 (@code{mh-send}).  However you invoke @code{mh-send}, you are prompted
878 for the @samp{To:}, @samp{cc:}, and @samp{Subject:} header fields.  Once
879 you've specified the recipients and subject, your message appears in an
880 Emacs buffer whose mode is MH-Letter (see the Figure in @ref{Sending
881 Mail} to see what the buffer looks like).  MH-Letter mode allows you to
882 edit your message, to check the validity of the recipients, to insert
883 other messages into your message, and to send the message.  We'll go
884 more into depth about editing a @dfn{draft} @footnote{I highly recommend
885 that you use a @dfn{draft folder} so that you can edit several drafts in
886 parallel.  To do so, create a folder (e.g., @file{+drafts}), and add a
887 profile component called @samp{Draft-Folder:} which contains
888 @file{+drafts} (see @code{mh-profile}(5)).} (a message you're composing)
889 in just a moment.
891 @findex @code{mh-smail}
892 @findex @code{mh-smail-other-window}
894 @code{mh-smail} always creates a two-window layout with the current
895 buffer on top and the draft on the bottom.  If you would rather preserve
896 the window layout, use @kbd{M-x mh-smail-other-window}.
898 @menu
899 * Replying::
900 * Forwarding::
901 * Redistributing::
902 * Old Drafts::
903 @end menu
905 @node Replying, Forwarding, Sending Mail, Sending Mail
906 @subsection Replying to Mail
908 @cindex replying
909 @cindex @code{mhl}
910 @cindex MH commands, @code{mhl}
911 @cindex @file{mhl.reply}
912 @cindex files, @file{mhl.reply}
913 @findex @code{mh-reply}
915 To compose a reply to a message, use the @kbd{r} (@code{mh-reply})
916 command.  If you supply a prefix argument (as in @kbd{C-u r}), the
917 message you are replying to is inserted in your reply after having first
918 been run through @code{mhl} with the format file @file{mhl.reply}.  See
919 @code{mhl}(1) to see how you can modify the default @file{mhl.reply}
920 file.
922 When you reply to a message, you are first prompted with @samp{Reply to
923 whom?}.  You have several choices here.
925 @example
926 @group
927 @b{Response}     @b{Reply Goes To}
929 @kbd{from}         @r{The person who sent the message.  This is the default,}
930              @r{so @key{RET} is sufficient.}
932 @kbd{to}           @r{Replies to the sender, plus all recipients in the}
933              @r{@samp{To:} header field.}
935 @kbd{all}
936 @kbd{cc}           @r{Forms a reply to the sender, plus all recipients.}
937 @end group
938 @end example
940 @cindex @code{repl}
941 @cindex MH commands, @code{repl}
943 Depending on your answer, @code{repl} is given a different argument to
944 form your reply.  Specifically, a choice of @kbd{from} or none at all
945 runs @code{repl -nocc all}, and a choice of @kbd{to} runs @code{repl -cc
946 to}.  Finally, either @kbd{cc} or @kbd{all} runs @code{repl -cc all
947 -nocc me}.
949 @cindex MH-Letter mode
950 @cindex modes, MH-Letter
952 Two windows are then created.  One window contains the message to which
953 you are replying.  Your draft, in MH-Letter mode (described in
954 @ref{Draft Editing}), is in the other window.
956 If you wish to customize the header or other parts of the reply draft,
957 please see @code{repl}(1) and @code{mh-format}(5).
959 @node Forwarding, Redistributing, Replying, Sending Mail
960 @subsection Forwarding Mail
962 @cindex forwarding
963 @cindex @code{forw}
964 @cindex MH commands, @code{forw}
965 @findex @code{mh-forward}
967 To forward a message, use the @kbd{f} (@code{mh-forward}) command.  You
968 are given a draft to edit that looks like it would if you had run the MH
969 command @code{forw}.  You are given a chance to add some text (see
970 @ref{Draft Editing}).
972 You can forward several messages by using a prefix argument; in this
973 case, you are prompted for the name of a @dfn{sequence}, a symbolic name
974 that represents a list or range of message numbers (for example,
975 @kbd{C-u f forbob @key{RET}}).  All of the messages in the sequence are
976 inserted into your draft.  By the way, although sequences are often
977 mentioned in this chapter, you don't have to worry about them for now;
978 the full description of sequences in mh-e is at the end in
979 @ref{Sequences}.  To learn more about sequences in general, please see
980 @code{mh-sequence}(5).
982 @node Redistributing, Old Drafts, Forwarding, Sending Mail
983 @subsection Redistributing Your Mail
985 @cindex redistributing
986 @findex @code{mh-redistribute}
988 The command @kbd{M-d} (@code{mh-redistribute}) is similar in function to
989 forwarding mail, but it does not allow you to edit the message, nor does
990 it add your name to the @samp{From:} header field.  It appears to the
991 recipient as if the message had come from the original sender.  For more
992 information on redistributing messages, see @code{dist}(1).  Also
993 investigate the @kbd{M-a} (@code{mh-edit-again}) command in @ref{Old
994 Drafts}, for another way to redistribute messages.
996 @node Old Drafts,  , Redistributing, Sending Mail
997 @subsection Editing Old Drafts and Bounced Messages
999 @cindex re-editing drafts
1000 @cindex @file{draft}
1001 @cindex files, @file{draft}
1002 @findex @code{mh-edit-again}
1004 If you don't complete a draft for one reason or another, and if the
1005 draft buffer is no longer available, you can pick your draft up again
1006 with @kbd{M-a} (@code{mh-edit-again}).  If you don't use a draft folder,
1007 your last @file{draft} file will be used.  If you use draft folders,
1008 you'll need to visit the draft folder with @kbd{M-f drafts @key{RET}},
1009 use @kbd{n} to move to the appropriate message, and then use @kbd{M-a}
1010 to prepare the message for editing.
1012 The @kbd{M-a} command can also be used to take messages that were sent
1013 to you and to send them to more people.
1015 @cindex Mailer-Daemon
1016 @findex @code{mh-extract-rejected-mail}
1018 Don't use @kbd{M-a} to re-edit a message from a @i{Mailer-Daemon} who
1019 complained that your mail wasn't posted for some reason or another.  In
1020 this case, use @kbd{M-e} (@code{mh-extract-rejected-mail}) to prepare
1021 the message for editing by removing the @i{Mailer-Daemon} envelope and
1022 unneeded header fields.  Fix whatever addressing problem you had, and
1023 send the message again with @kbd{C-c C-c}.
1025 @node Draft Editing, Moving Mail, Sending Mail, Using mh-e
1026 @section Editing a Draft
1028 @cindex editing draft
1029 @cindex MH-Letter mode
1030 @cindex modes, MH-Letter
1032 When you edit a message that you want to send (called a @dfn{draft} in
1033 this case), the mode used is MH-Letter.  This mode provides
1034 several commands in addition to the normal Emacs editing commands to
1035 help you edit your draft.
1037 @table @kbd
1038 @item C-c C-y
1039 Insert contents of message to which you're replying (@code{mh-yank-cur-msg}).
1041 @item C-c C-i
1042 Insert a message from a folder (@code{mh-insert-letter}).
1044 @item C-c C-f C-t
1045 Move to @samp{To:} header field (@code{mh-to-field}).
1047 @item C-c C-f C-c
1048 Move to @samp{cc:} header field (@code{mh-to-field}).
1050 @item C-c C-f C-s
1051 Move to @samp{Subject:} header field (@code{mh-to-field}).
1053 @item C-c C-f C-f
1054 Move to @samp{From:} header field (@code{mh-to-field}).
1056 @item C-c C-f C-b
1057 Move to @samp{Bcc:} header field (@code{mh-to-field}).
1059 @item C-c C-f C-f
1060 Move to @samp{Fcc:} header field (@code{mh-to-fcc}).
1062 @item C-c C-f C-d
1063 Move to @samp{Dcc:} header field (@code{mh-to-field}).
1065 @item C-c C-w
1066 Display expanded recipient list (@code{mh-check-whom}).
1068 @item C-c C-s
1069 Insert signature in message (@code{mh-insert-signature}).
1071 @item C-c C-m C-f
1072 Include forwarded message (@sc{mime}) (@code{mh-mhn-compose-forw}).
1074 @item C-c C-m C-e
1075 Include anonymous ftp reference (@sc{mime}) (@code{mh-mhn-compose-anon-ftp}).
1077 @item C-c C-m C-t
1078 Include anonymous ftp reference to compressed tar file (@sc{mime})
1079 (@code{mh-mhn-compose-external-compressed-tar}).
1081 @item C-c C-m C-i
1082 Include binary, image, sound, etc. (@sc{mime})
1083 (@code{mh-mhn-compose-insertion}).
1085 @item C-c C-e
1086 Run through @code{mhn} before sending (@code{mh-edit-mhn}).
1088 @item C-c C-m C-u
1089 Undo effects of @code{mhn} (@code{mh-revert-mhn-edit}).
1091 @item C-c C-c
1092 Save draft and send message (@code{mh-send-letter}).
1094 @item C-c C-q
1095 Quit editing and delete draft message (@code{mh-fully-kill-draft}).
1096 @end table
1098 @menu
1099 * Editing Textual::
1100 * Editing MIME::
1101 * Sending Message::
1102 * Killing Draft::
1103 @end menu
1105 @node Editing Textual, Editing MIME, Draft Editing, Draft Editing
1106 @subsection Editing Textual Messages
1108 The following sections show you how to edit a draft.
1109 The commands described here are also applicable to messages that have
1110 multimedia components.
1112 @menu
1113 * Inserting Letter::
1114 * Inserting Messages::
1115 * Header::
1116 * Recipients::
1117 * Signature::
1118 @end menu
1120 @node Inserting Letter, Inserting Messages, Editing Textual, Editing Textual
1121 @subsubsection Inserting letter to which you're replying
1123 @cindex inserting messages
1124 @findex @code{mh-yank-cur-msg}
1126 It is often useful to insert a snippet of text from a letter that
1127 someone mailed to provide some context for your reply.  The command
1128 @kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by yanking a portion of
1129 text from the message to which you're replying and inserting @samp{> }
1130 before each line.
1132 @cindex mark
1133 @cindex Emacs, mark
1134 @cindex point
1135 @cindex Emacs, point
1136 @cindex region
1137 @cindex Emacs, region
1139 You can control how much text is included when you run this command.  If
1140 you run this command right away, without entering the buffer containing
1141 the message to you, this command will yank the entire message, as is,
1142 into your reply. @footnote{If you'd rather have the header cleaned up,
1143 use @kbd{C-u r} instead of @kbd{r} when replying (see @ref{Replying}).}
1144 If you enter the buffer containing the message sent to you and move the
1145 cursor to a certain point and return to your reply and run @kbd{C-c
1146 C-y}, then the text yanked will range from that point to the end of the
1147 message.  Finally, the most common action you'll perform is to enter the
1148 message sent to you, move the cursor to the beginning of a paragraph or
1149 phrase, set the @dfn{mark} with @kbd{C-SPC} or @kbd{C-@@}, and move the
1150 cursor to the end of the paragraph or phrase.  The cursor position is
1151 called the @dfn{point}, and the space between the mark and point is
1152 called the @dfn{region}.  Having done that, @kbd{C-c C-y} will insert
1153 the region you selected.
1155 @node Inserting Messages, Header, Inserting Letter, Editing Textual
1156 @subsubsection Inserting messages
1158 @cindex inserting messages
1159 @findex @code{mh-insert-letter}
1161 Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}).
1162 This command prompts you for the folder and message number and inserts
1163 the message, indented by @samp{> }.  Certain undesirable header fields
1164 are removed before insertion.  If given a prefix argument (like @kbd{C-u
1165 C-c C-i}), the header is left intact, the message is not indented, and
1166 @samp{> } is not inserted before each line.
1168 @node Header, Recipients, Inserting Messages, Editing Textual
1169 @subsubsection Editing the header
1171 @cindex editing header
1172 @findex @code{mh-to-field}
1174 Because the header is part of the message, you can edit the header
1175 fields as you wish.  However, several convenience functions exist to
1176 help you create and edit them.  For example, the command @kbd{C-c C-f
1177 C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the
1178 cursor to the @samp{To:} header field, creating it if necessary.  The
1179 functions to move to the @samp{cc:}, @samp{Subject:}, @samp{From:},
1180 @samp{Bcc:}, and @samp{Dcc:} header fields are similar.
1182 @findex @code{mh-to-fcc}
1184 One function behaves differently from the others, namely, @kbd{C-c C-f
1185 C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}).  This function
1186 will prompt you for the folder name in which to file a copy of the draft.
1188 Be sure to leave a row of dashes or a blank line between the header and
1189 the body of the message.
1191 @node Recipients, Signature, Header, Editing Textual
1192 @subsubsection Checking recipients
1194 @cindex checking recipients
1195 @cindex @code{whom}
1196 @cindex MH commands, @code{whom}
1197 @findex @code{mh-check-whom}
1199 The @kbd{C-c C-w} (@code{mh-check-whom}) command expands aliases so you
1200 can check the actual address(es) in the alias.  A new buffer is created
1201 with the output of @code{whom}.
1203 @node Signature,  , Recipients, Editing Textual
1204 @subsubsection Inserting your signature
1206 @cindex inserting signature
1207 @cindex signature
1208 @cindex @file{.signature}
1209 @cindex files, @file{.signature}
1210 @findex @code{mh-insert-signature}
1212 You can insert your signature at the current cursor location with the
1213 @kbd{C-c C-s} (@code{mh-insert-signature}) command.  The text of your
1214 signature is taken from the file @file{~/.signature}.
1216 @node Editing MIME, Sending Message, Editing Textual, Draft Editing
1217 @subsection Editing Multimedia Messages
1219 @cindex MIME
1220 @cindex multimedia mail
1221 @cindex @code{mhn}
1222 @cindex MH commands, @code{mhn}
1224 mh-e has the capability to create multimedia messages.  It uses the
1225 @sc{mime} (Multipurpose Internet Mail Extensions) protocol.  The
1226 @sc{mime} protocol allows you to incorporate images, sound, video,
1227 binary files, and even commands that fetch a file with @samp{ftp} when
1228 your recipient reads the message!  If you were to create a multimedia
1229 message with plain MH commands, you would use @code{mhn}.  Indeed, the
1230 mh-e @sc{mime} commands merely insert @code{mhn} directives which are
1231 later expanded by @code{mhn}.
1233 Each of the mh-e commands for editing multimedia messages or for
1234 incorporating multimedia objects is prefixed with @kbd{C-c C-m} .
1236 @cindex content types
1237 @cindex MIME, content types
1239 Several @sc{mime} objects are defined.  They are called @dfn{content
1240 types}.  The table in @ref{Customizing Draft Editing} contains a list of
1241 the content types that mh-e currently knows about.  Several of the mh-e
1242 commands fill in the content type for you, whereas others require you to
1243 enter one.  Most of the time, it should be obvious which one to use
1244 (e.g., use @kbd{image/jpeg} to include a @sc{jpeg} image).  If not, you
1245 can refer to @sc{rfc} 1521,
1246 @c Footnotes are very fragile.  Hence the duplication.
1247 @c The line break in the footnote was necessary since TeX wasn't creating one.
1248 @ifclear html
1249 @footnote{This @sc{rfc} (Request For Comments) is
1250 available via the @sc{url} @*
1251 @file{ftp://ds.internic.net/rfc/rfc1521.txt}.}
1252 @end ifclear
1253 @ifset html
1254 @footnote{This @sc{rfc} (Request For Comments) is
1255 available via the @sc{url} @*
1256 @file{<A HREF="ftp://ds.internic.net/rfc/rfc1521.txt">ftp://ds.internic.net/rfc/rfc1521.txt</A>}.}
1257 @end ifset
1258 which defines the @sc{mime} protocol, for a list of valid content types.
1260 @cindex content description
1261 @cindex MIME, content description
1263 You are also sometimes asked for a @dfn{content description}.  This is
1264 simply an optional brief phrase, in your own words, that describes the
1265 object.  If you don't care to enter a content description, just press
1266 return and none will be included; however, a reader may skip over
1267 multimedia fields unless the content description is compelling.
1269 Remember: you can always add @code{mhn} directives by hand.
1271 @menu
1272 * Forwarding MIME::
1273 * FTP::
1274 * Tar::
1275 * Other MIME Objects::
1276 * Sending MIME::
1277 @end menu
1279 @node Forwarding MIME, FTP, Editing MIME, Editing MIME
1280 @subsubsection Forwarding multimedia messages
1282 @findex @code{mh-mhn-compose-forw}
1284 Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m C-f}
1285 (@code{mh-mhn-compose-forw}).  You are prompted for a content
1286 description, the name of the folder in which the messages to forward are
1287 located, and the messages' numbers.
1289 @node FTP, Tar, Forwarding MIME, Editing MIME
1290 @subsubsection Including an ftp reference
1292 @cindex @code{ftp}
1293 @cindex Unix commands, @code{ftp}
1294 @cindex MIME, @code{ftp}
1295 @findex @code{mh-mhn-compose-anon-ftp}
1297 You can even have your message initiate an @code{ftp} transfer when the
1298 recipient reads the message.  To do this, use the @kbd{C-c C-m C-e}
1299 (@code{mh-mhn-compose-anon-ftp}) command.  You are prompted for the
1300 remote host and pathname, the content type, and the content description.
1302 @node Tar, Other MIME Objects, FTP, Editing MIME
1303 @subsubsection Including tar files
1305 @cindex @code{tar}
1306 @cindex Unix commands, @code{tar}
1307 @cindex MIME, @code{tar}
1308 @cindex @code{ftp}
1309 @cindex Unix commands, @code{ftp}
1310 @cindex MIME, @code{ftp}
1311 @findex @code{mh-mhn-compose-external-compressed-tar}
1313 If the remote file (@pxref{FTP}) is a compressed tar file, you can use
1314 @kbd{C-c C-m C-t} (@code{mh-mhn-compose-external-compressed-tar}).
1315 Then, in addition to retrieving the file via anonymous @emph{ftp}, the
1316 file will also be uncompressed and untarred.  You are prompted for the
1317 remote host and pathname and the content description.  The pathname
1318 should contain at least one @samp{/} (slash), because the pathname is
1319 broken up into directory and name components.
1321 @node Other MIME Objects, Sending MIME, Tar, Editing MIME
1322 @subsubsection Including other multimedia objects
1324 @cindex images
1325 @cindex MIME, images
1326 @cindex sound
1327 @cindex MIME, sound
1328 @cindex video
1329 @cindex MIME, video
1330 @findex @code{mh-mhn-compose-insertion}
1332 Images, sound, and video can be inserted in your message with the
1333 @kbd{C-c C-m C-i} (@code{mh-mhn-compose-insertion}) command.  You are
1334 prompted for the filename containing the object, the content type, and a
1335 content description of the object.
1337 @node Sending MIME,  , Other MIME Objects, Editing MIME
1338 @subsubsection Readying multimedia messages for sending
1340 When you are finished editing a @sc{mime} message, it might look like this:
1342 @example
1343 @group
1344 @cartouche
1345    3  24Aug  root               received fax files on Wed Aug 24 11:00:13
1346    4+ 24Aug  To:wohler          Test<<This is a test message to get the wh
1352 --%%-@{+inbox@} 4 msgs (1-4)      (MH-Folder Show)--Bot-------------------
1353 To: wohler
1355 Subject: Test of MIME
1356 --------
1357 #@@application/octet-stream [Nonexistent ftp test file] \
1358 access-type=anon-ftp; site=berzerk.com; name=panacea.tar.gz; \
1359 directory="/pub/"
1360 #audio/basic [Test sound bite] /tmp/noise.au
1361 --**-@{draft@}      (MH-Letter)--All--------------------------------------
1363 @end cartouche
1364 @i{mh-e @sc{mime} draft}
1365 @end group
1366 @end example
1368 @cindex @code{mhn}
1369 @cindex MH commands, @code{mhn}
1370 @findex @code{mh-edit-mhn}
1372 The lines added by the previous commands are @code{mhn} directives and
1373 need to be converted to @sc{mime} directives before sending.  This is
1374 accomplished by the command @kbd{C-c C-e} (@code{mh-edit-mhn}), which
1375 runs @code{mhn} on the message.  The following screen shows what those
1376 commands look like in full @sc{mime} format.  You can see why mail user
1377 agents are usually built to hide these details from the user.
1379 @example
1380 @group
1381 @cartouche
1382 To: wohler
1384 Subject: Test of MIME
1385 MIME-Version: 1.0
1386 Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
1387 Content-ID: <1623.777796162.0@@newt.com>
1389 ------- =_aaaaaaaaaa0
1390 Content-Type: message/external-body; access-type="anon-ftp";
1391         site="berzerk.com"; name="panacea.tar.gz"; directory="/pub/"
1393 Content-Type: application/octet-stream
1394 Content-ID: <1623.777796162.1@@newt.com>
1395 Content-Description: Nonexistent ftp test file
1397 ------- =_aaaaaaaaaa0
1398 Content-Type: audio/basic
1399 Content-ID: <1623.777796162.2@@newt.com>
1400 Content-Description: Test sound bite
1401 Content-Transfer-Encoding: base64
1403 Q3JlYXRpdmUgVm9pY2UgRmlsZRoaAAoBKREBQh8AgwCAgH9/f35+fn59fX5+fn5+f39/f39/f3
1404 f4B/f39/f39/f39/f39/f39+f39+f39/f39/f4B/f39/fn5/f39/f3+Af39/f39/gH9/f39/fn
1405 -----@{draft@}      (MH-Letter)--Top--------------------------------------
1407 @end cartouche
1408 @i{mh-e @sc{mime} draft ready to send}
1409 @end group
1410 @end example
1412 @findex @code{mh-revert-mhn-edit}
1414 This action can be undone by running @kbd{C-c C-m C-u}
1415 (@code{mh-revert-mhn-edit}).  It does this by reverting to a backup
1416 file.  You are prompted to confirm this action, but you can avoid the
1417 confirmation by adding an argument (for example, @kbd{C-u C-c C-m C-u}).
1419 @node Sending Message, Killing Draft, Editing MIME, Draft Editing
1420 @subsection Sending a Message
1422 @cindex sending mail
1423 @findex @code{mh-send-letter}
1425 When you are all through editing a message, you send it with the
1426 @kbd{C-c C-c} (@code{mh-send-letter}) command.  You can give an argument
1427 (as in @kbd{C-u C-c C-c}) to monitor the first stage of the delivery.
1429 @node Killing Draft,  , Sending Message, Draft Editing
1430 @subsection Killing the Draft
1432 @cindex killing draft
1433 @findex @code{mh-fully-kill-draft}
1435 If for some reason you are not happy with the draft, you can kill it
1436 instead with @kbd{C-c C-q} (@code{mh-fully-kill-draft}).  Emacs then
1437 kills the draft buffer and deletes the draft message.
1439 @node Moving Mail, Searching, Draft Editing, Using mh-e
1440 @section Moving Your Mail Around
1442 @cindex processing mail
1444 This section covers how messages and folders can be moved about or
1445 manipulated.  Messages may be incorporated into your @file{+inbox},
1446 deleted, and refiled.  Messages containing @code{shar} or
1447 @code{uuencode} output can be stored.  Folders can be visited, sorted,
1448 packed, or deleted.  Here's a list of the available commands to do these
1449 things:
1451 @c Stephen thinks that ? should be documented here, since it also shows
1452 @c which folders a message will be refiled to. XXX
1454 @table @kbd
1455 @item i
1456 Incorporate new mail into folder (@code{mh-inc-folder}).
1458 @item d
1459 Delete message (@code{mh-delete-msg}).
1461 @item C-d
1462 Delete message, don't move to next message (@code{mh-delete-msg-no-motion}).
1464 @item M-s
1465 Find messages that meet search criteria (@code{mh-search-folder}).
1467 @item o
1468 Output (refile) message to folder (@code{mh-refile-msg}).
1470 @item c
1471 Copy message to folder (@code{mh-copy-msg}).
1473 @item C-o
1474 Output (write) message to file (@code{mh-write-msg-to-file}).
1476 @item !
1477 Repeat last output command (@code{mh-refile-or-write-again}).
1479 @item l
1480 Print message with @code{lpr} (@code{mh-print-msg}).
1482 @item |
1483 Pipe message through shell command (@code{mh-pipe-msg}).
1485 @item M-n
1486 Unpack message created with @code{uudecode} or @code{shar}
1487 (@code{mh-store-msg}).
1489 @item M-l
1490 List all folders (@code{mh-list-folders}).
1492 @item M-f
1493 Visit folder (@code{mh-visit-folder}).
1495 @item M-r
1496 Regenerate scan lines (@code{mh-rescan-folder}).
1498 @item M-x mh-sort-folder
1499 Sort folder.
1501 @item M-p
1502 Pack folder (@code{mh-pack-folder}).
1504 @item M-k
1505 Remove folder (@code{mh-kill-folder}).
1507 @item x
1508 Execute pending refiles and deletes (@code{mh-execute-commands}).
1510 @item u
1511 Undo pending refile or delete (@code{mh-undo}).
1513 @item M-u
1514 Undo all pending refiles and deletes (@code{mh-undo-folder}).
1516 @item q
1517 Quit (@code{mh-quit}).
1518 @end table
1520 @menu
1521 * Incorporating::
1522 * Deleting::
1523 * Organizing::
1524 * Printing::
1525 * Files and Pipes::
1526 * Finishing Up::
1527 @end menu
1529 @node Incorporating, Deleting, Moving Mail, Moving Mail
1530 @subsection Incorporating Your Mail
1532 @cindex incorporating
1533 @findex @code{mh-inc-folder}
1535 If at any time you receive new mail, incorporate the new mail into your
1536 @samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}).  Note that
1537 @kbd{i} will display the @samp{+inbox} buffer, even if there isn't any
1538 new mail.  You can incorporate mail from any file into the current
1539 folder by specifying a prefix argument; you'll be prompted for the name
1540 of the file to use (for example, @kbd{C-u i ~/mbox @key{RET}}).
1542 @cindex Emacs, notification of new mail
1543 @cindex notification of new mail
1544 @cindex new mail
1545 @cindex @file{.emacs}
1546 @cindex files, @file{.emacs}
1548 Emacs can notify you when you have new mail by displaying @samp{Mail} in
1549 the mode line.  To enable this behavior, and to have a clock in the mode
1550 line besides, add the following to @file{~/.emacs}:
1552 @findex @code{display-time}
1554 @lisp
1555 (display-time)
1556 @end lisp
1558 @node Deleting, Organizing, Incorporating, Moving Mail
1559 @subsection Deleting Your Mail
1561 @cindex deleting
1562 @findex @code{mh-delete-msg}
1563 @findex @code{mh-delete-msg-no-motion}
1565 To mark a message for deletion, use the @kbd{d} (@code{mh-delete-msg})
1566 command.  A @samp{D} is placed by the message in the scan window, and
1567 the next message is displayed.  If the previous command had been
1568 @kbd{p}, then the next message displayed is the message previous to the
1569 message just deleted.  If you specify a prefix argument, you will be
1570 prompted for a sequence (@pxref{Sequences}) to delete (for example,
1571 @kbd{C-u d frombob RET}).  The @kbd{x} command actually carries out the
1572 deletion (@pxref{Finishing Up}).  @kbd{C-d}
1573 (@code{mh-delete-msg-no-motion}) marks the message for deletion but
1574 leaves the cursor at the current message in case you wish to perform
1575 other operations on the message.
1577 @node Organizing, Printing, Deleting, Moving Mail
1578 @subsection Organizing Your Mail with Folders
1580 @cindex using folders
1581 @cindex @code{folder}
1582 @cindex MH commands, @code{folder}
1583 @cindex @code{refile}
1584 @cindex MH commands, @code{refile}
1585 @findex @code{mh-refile-msg}
1587 mh-e has analogies for each of the MH @code{folder} and @code{refile}
1588 commands.  To refile a message in another folder, use the @kbd{o}
1589 (@code{mh-refile-msg}) (mnemonic: ``output'') command.  You are prompted
1590 for the folder name.
1592 @findex @code{mh-refile-or-write-again}
1594 If you are refiling several messages into the same folder, you can use
1595 the @kbd{!} (@code{mh-refile-or-write-again}) command to repeat the last
1596 refile or write (see the description of @kbd{C-o} in @ref{Files and
1597 Pipes}).  Or, place the messages into a sequence (@ref{Sequences}) and
1598 specify a prefix argument to @kbd{o}, in which case you'll be prompted
1599 for the name of the sequence (for example, @kbd{C-u o search RET}).
1601 @findex @code{mh-copy-msg}
1603 If you wish to copy a message to another folder, you can use the @kbd{c}
1604 (@code{mh-copy-msg}) command (see the @code{-link} argument to
1605 @code{refile}(1)).  You are prompted for a folder, and you can specify a
1606 prefix argument if you want to copy a sequence into another folder.  In
1607 this case, you are then prompted for the sequence.  Note that unlike the
1608 @kbd{o} command, the copy takes place immediately.  The original copy
1609 remains in the current folder.
1611 @findex @code{mh-visit-folder}
1613 When you want to read the messages that you have refiled into folders,
1614 use the @kbd{M-f} (@code{mh-visit-folder}) command to visit the folder.
1615 You are prompted for the folder name.
1617 @findex @code{mh-list-folders}
1618 @findex @code{mh-kill-folder}
1619 @findex @code{mh-visit-folder}
1620 @findex @code{mh-sort-folder}
1621 @findex @code{mh-pack-folder}
1622 @findex @code{mh-rescan-folder}
1624 Other commands you can perform on folders include: @kbd{M-l}
1625 (@code{mh-list-folders}), to list all the folders in your mail
1626 directory; @kbd{M-k} (@code{mh-kill-folder}), to remove a folder;
1627 @kbd{M-x mh-sort-folder}, to sort the messages by date (see
1628 @code{sortm}(1) to see how to sort by other criteria); @kbd{M-p}
1629 (@code{mh-pack-folder}), to pack a folder, removing gaps from the
1630 numbering sequence; and @kbd{M-r} (@code{mh-rescan-folder}), to rescan
1631 the folder, which is useful to grab all messages in your @file{+inbox}
1632 after processing your new mail for the first time.  If you don't want to
1633 rescan the entire folder, give @kbd{M-r} or @kbd{M-p} a prefix argument
1634 and you'll be prompted for a range of messages to display (for instance,
1635 @kbd{C-u M-r last:50 RET}).
1637 @node Printing, Files and Pipes, Organizing, Moving Mail
1638 @subsection Printing Your Mail
1640 @cindex printing
1641 @cindex @code{mhl}
1642 @cindex MH commands, @code{mhl}
1643 @cindex @code{lpr}
1644 @cindex Unix commands, @code{lpr}
1645 @findex @code{mh-print-msg}
1647 Printing mail is simple.  Enter @kbd{l} (@code{mh-print-msg}) (for
1648 @i{l}ine printer or @i{l}pr).  The message is formatted with @code{mhl}
1649 and printed with the @code{lpr} command.  You can print all the messages
1650 in a sequence by specifying a prefix argument, in which case you are
1651 prompted for the name of the sequence (as in @kbd{C-u l frombob RET}).
1653 @node Files and Pipes, Finishing Up, Printing, Moving Mail
1654 @subsection Files and Pipes
1656 @cindex using files
1657 @cindex using pipes
1658 @findex @code{mh-write-msg-to-file}
1660 mh-e does offer a couple of commands that are not a part of MH@.  The
1661 first one, @kbd{C-o} (@code{mh-write-msg-to-file}), writes a message to
1662 a file (think of the @kbd{o} as in "output").  You are prompted for the
1663 filename.  If the file already exists, the message is appended to it.
1664 You can also write the message to the file without the header by
1665 specifying a prefix argument (such as @kbd{C-u C-o /tmp/foobar RET}).
1666 Subsequent writes to the same file can be made with the @kbd{!}
1667 command.
1669 @findex @code{mh-pipe-msg}
1671 You can also pipe the message through a Unix shell command with the
1672 @kbd{|} (@code{mh-pipe-msg}) command.  You are prompted for the
1673 Unix command through which you wish to run your message.  If you
1674 give an argument to this command, the message header is included in the
1675 text passed to the command (the contrived example @kbd{C-u | lpr}
1676 would be done with the @kbd{l} command instead).
1678 @cindex @code{shar}
1679 @cindex Unix commands, @code{shar}
1680 @cindex @code{uuencode}
1681 @cindex Unix commands, @code{uuencode}
1682 @findex @code{mh-store-msg}
1684 If the message is a shell archive @code{shar} or has been run through
1685 @code{uuencode} use @kbd{M-n} (@code{mh-store-msg}) to extract the body
1686 of the message.  The default directory for extraction is the current
1687 directory, and you have a chance to specify a different extraction
1688 directory.  The next time you use this command, the default directory is
1689 the last directory you used.
1691 @node Finishing Up,  , Files and Pipes, Moving Mail
1692 @subsection Finishing Up
1694 @cindex expunging refiles and deletes
1695 @findex @code{mh-undo}
1696 @findex @code{mh-undo-folder}
1698 If you've deleted a message or refiled it, but changed your mind, you
1699 can cancel the action before you've executed it.  Use @kbd{u}
1700 (@code{mh-undo}) to undo a refile on or deletion of a single message.
1701 You can also undo refiles and deletes for messages that belong to a
1702 given sequence by specifying a prefix argument.  You'll be prompted for
1703 the name of the sequence (as in @kbd{C-u u frombob RET}).
1704 Alternatively, you can use @kbd{M-u} (@code{mh-undo-folder}) to undo all
1705 refiles or deletes in the current folder.
1707 @findex @code{mh-execute-commands}
1709 If you've marked messages to be deleted or refiled and you want to go
1710 ahead and delete or refile the messages, use @kbd{x}
1711 (@code{mh-execute-commands}).  Many mh-e commands that may affect the
1712 numbering of the messages (such as @kbd{M-r} or @kbd{M-p}) will ask if you
1713 want to process refiles or deletes first and then either run @kbd{x} for
1714 you or undo the pending refiles and deletes, which are lost.
1716 @findex @code{mh-rmail}
1717 @findex @code{mh-quit}
1719 When you want to quit using mh-e and go back to editing, you can use the
1720 @kbd{q} (@code{mh-quit}) command.  This buries the buffers of the
1721 current mh-e folder and restores the buffers that were present when you
1722 first ran @kbd{M-x mh-rmail}.  You can later restore your mh-e session
1723 by selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail}
1724 again.
1726 @node Searching, Sequences, Moving Mail, Using mh-e
1727 @section Searching Through Messages
1729 @cindex searching
1730 @findex @code{mh-search-folder}
1732 You can search a folder for messages to or from a particular person or
1733 about a particular subject.  In fact, you can also search for messages
1734 containing selected strings in any arbitrary header field or any string
1735 found within the messages.  Use the @kbd{M-s} (@code{mh-search-folder})
1736 command.  You are first prompted for the name of the folder to search
1737 and then placed in the following buffer in MH-Pick mode:
1739 @example
1740 @group
1741 @cartouche
1742 From: #
1745 Date:
1746 Subject:
1747 --------
1757 --**-Emacs: pick-pattern    (MH-Pick)------All--------------------------
1759 @end cartouche
1760 @i{Pick window}
1761 @end group
1762 @end example
1764 @cindex @code{pick}
1765 @cindex MH commands, @code{pick}
1767 Edit this template by entering your search criteria in an appropriate
1768 header field that is already there, or create a new field yourself.  If
1769 the string you're looking for could be anywhere in a message, then place
1770 the string underneath the row of dashes.  The @kbd{M-s} command uses the
1771 MH command @code{pick} to do the real work, so read @code{pick}(1) to
1772 find out more about how to enter the criteria.
1774 There are no semantics associated with the search criteria---they are
1775 simply treated as strings.  Case is ignored when all lowercase is used,
1776 and regular expressions (a la @code{ed}) are available.  It is all right
1777 to specify several search criteria.  What happens then is that a logical
1778 @emph{and} of the various fields is performed.  If you prefer a logical
1779 @emph{or} operation, run @kbd{M-s} multiple times.
1781 As an example, let's say that we want to find messages from Ginnean
1782 about horseback riding in the Kosciusko National Park (Australia) during
1783 January, 1994.  Normally we would start with a broad search and narrow
1784 it down if necessary to produce a manageable amount of data, but we'll
1785 cut to the chase and create a fairly restrictive set of criteria as
1786 follows:
1788 @example
1789 @group
1790 From: ginnean
1793 Date: Jan 1994
1794 Subject: horse.*kosciusko
1795 --------
1796 @end group
1797 @end example
1799 @findex @code{mh-to-field}
1801 As with MH-Letter mode, MH-Pick provides commands like
1802 @kbd{C-c C-f C-t} to help you fill in the blanks.
1804 @table @kbd
1805 @item C-c C-f C-t
1806 Move to @samp{To:} header field (@code{mh-to-field}).
1808 @item C-c C-f C-c
1809 Move to @samp{cc:} header field (@code{mh-to-field}).
1811 @item C-c C-f C-s
1812 Move to @samp{Subject:} header field (@code{mh-to-field}).
1814 @item C-c C-f C-f
1815 Move to @samp{From:} header field (@code{mh-to-field}).
1817 @item C-c C-f C-b
1818 Move to @samp{Bcc:} header field (@code{mh-to-field}).
1820 @item C-c C-f C-f
1821 Move to @samp{Fcc:} header field (@code{mh-to-field}).
1823 @item C-c C-f C-d
1824 Move to @samp{Dcc:} header field (@code{mh-to-field}).
1826 @item C-c C-c
1827 Execute the search (@code{mh-do-pick-search}).
1828 @end table
1830 @findex @code{mh-do-pick-search}
1832 To perform the search, type @kbd{C-c C-c} (@code{mh-do-pick-search}).
1833 The selected messages are placed in the @i{search} sequence, which you
1834 can use later in forwarding (@pxref{Forwarding}), printing
1835 (@pxref{Printing}), or narrowing your field of view (@pxref{Sequences}).
1836 Subsequent searches are appended to the @i{search} sequence.  If,
1837 however, you wish to start with a clean slate, first delete the
1838 @i{search} sequence (how to do this is discussed in @ref{Sequences}).
1840 @cindex MH-Folder mode
1841 @cindex modes, MH-Folder
1843 If you're searching in a folder that is already displayed in a
1844 MH-Folder buffer, only those messages contained in the buffer are
1845 used for the search.  Therefore, if you want to search in all messages,
1846 first kill the folder's buffer with @kbd{C-x k} or scan the entire
1847 folder with @kbd{M-r}.
1849 @node Sequences, Miscellaneous, Searching, Using mh-e
1850 @section Using Sequences
1852 @cindex sequences
1854 For the whole scoop on MH sequences, refer to @code{mh-sequence}(5).  As
1855 you've read, several of the mh-e commands can operate on a sequence,
1856 which is a shorthand for a range or group of messages.  For example, you
1857 might want to forward several messages to a friend or colleague.  Here's
1858 how to manipulate sequences.
1860 @table @kbd
1861 @item %
1862 Put message in a sequence (@code{mh-put-msg-in-seq}).
1864 @item ?
1865 Display sequences that message belongs to (@code{mh-msg-is-in-seq}).
1867 @item M-q
1868 List all sequences in folder (@code{mh-list-sequences}).
1870 @item M-%
1871 Remove message from sequence (@code{mh-delete-msg-from-seq}).
1873 @item M-#
1874 Delete sequence (@code{mh-delete-seq}).
1876 @item C-x n
1877 Restrict display to messages in sequence (@code{mh-narrow-to-seq}).
1879 @item C-x w
1880 Remove restriction; display all messages (@code{mh-widen}).
1882 @item M-x mh-update-sequences
1883 Push mh-e's state out to MH@.
1884 @end table
1886 @cindex @code{pick}
1887 @cindex MH commands, @code{pick}
1888 @findex @code{mh-put-msg-in-seq}
1890 To place a message in a sequence, use @kbd{%} (@code{mh-put-msg-in-seq})
1891 to do it manually, or use the MH command @code{pick} or the mh-e version
1892 of @code{pick} (@ref{Searching}) which create a sequence automatically.
1893 Give @kbd{%} a prefix argument and you can add all the messages in one
1894 sequence to another sequence (for example, @kbd{C-u % SourceSequence
1895 RET}).
1897 @cindex MH-Folder mode
1898 @cindex modes, MH-Folder
1899 @findex @code{mh-narrow-to-seq}
1900 @findex @code{mh-widen}
1902 Once you've placed some messages in a sequence, you may wish to narrow
1903 the field of view to just those messages in the sequence you've created.
1904 To do this, use @kbd{C-x n} (@code{mh-narrow-to-seq}).  You are prompted
1905 for the name of the sequence.  What this does is show only those
1906 messages that are in the selected sequence in the MH-Folder buffer.  In
1907 addition, it limits further mh-e searches to just those messages.  When
1908 you want to widen the view to all your messages again, use @kbd{C-x w}
1909 (@code{mh-widen}).
1911 @findex @code{mh-msg-is-in-seq}
1912 @findex @code{mh-list-sequences}
1914 You can see which sequences a message is in with the @kbd{?}
1915 (@code{mh-msg-is-in-seq}) command.
1916 @c Doesn't work:
1917 @c use a prefix argument to query a
1918 @c message other than the current one (as in @kbd{C-u ? 42 RET}). XXX
1919 Or, you can list all sequences in a selected folder (default is current
1920 folder) with @kbd{M-q} (@code{mh-list-sequences}).
1922 @findex @code{mh-delete-msg-from-seq}
1923 @findex @code{mh-delete-seq}
1925 If you want to remove a message from a sequence, use @kbd{M-%}
1926 (@code{mh-delete-msg-from-seq}), and if you want to delete an entire
1927 sequence, use @kbd{M-#} (@code{mh-delete-seq}).  In the latter case you
1928 are prompted for the sequence to delete.  Note that this deletes only
1929 the sequence, not the messages in the sequence.  If you want to delete
1930 the messages, use @kbd{C-u d} (see @ref{Deleting} above).
1932 @cindex @code{mark}
1933 @cindex MH commands, @code{mark}
1935 @findex @code{mh-update-sequences}
1937 Two sequences are maintained internally by mh-e and pushed out to MH
1938 when you type either the @kbd{x} or @kbd{q} command.  They are the
1939 sequence specified by your @samp{Unseen-Sequence:} profile entry and
1940 @i{cur}.  However, you can also just update MH's state with the command
1941 @kbd{M-x mh-update-sequences}.  See @ref{Customizing Viewing} for an
1942 example of how this command might be used.
1944 With the exceptions of @kbd{C-x n} and @kbd{C-x w}, the underlying MH
1945 command dealing with sequences is @code{mark}.
1947 @node Miscellaneous,  , Sequences, Using mh-e
1948 @section Miscellaneous Commands
1950 @findex @code{mh-version}
1952 One other command worth noting is @kbd{M-x mh-version}. You can
1953 compare the version this command prints to the latest release
1954 (@pxref{Getting mh-e}). The output of @kbd{M-x mh-version} should
1955 always be included with any bug report you submit (@pxref{Bug Reports}).
1957 @node    Customizing mh-e, Odds and Ends, Using mh-e, Top
1958 @chapter Customizing mh-e
1960 Until now, we've talked about the mh-e commands as they work ``out of the
1961 box.''  Of course, it is also possible to reconfigure mh-e
1962 to fit the needs of even the most demanding user.
1963 The following sections describe all of the
1964 customization variables, show the defaults, and make recommendations for
1965 customization.  The outline of this chapter is identical to that of
1966 @ref{Using mh-e}, to make it easier to find the variables you'd need to
1967 modify to affect a particular command.
1969 However, when customizing your mail environment, first try to change
1970 what you want in MH, and only change mh-e if changing MH is not
1971 possible.  That way you will get the same behavior inside and outside
1972 GNU Emacs.  Note that mh-e does not provide hooks for customizations
1973 that can be done in MH; this omission is intentional.
1975 @cindex @file{.emacs}
1976 @cindex files, @file{.emacs}
1978 Many string or integer variables are easy enough to modify using Emacs
1979 Lisp.  Any such modifications should be placed in a file called
1980 @file{.emacs} in your home directory (that is, @file{~/.emacs}).  For
1981 example, to modify the variable that controls printing, you could add:
1983 @vindex @code{mh-lpr-command-format}, example
1985 @lisp
1986 (setq mh-lpr-command-format "nenscript -G -r -2 -i'%s'")
1987 @end lisp
1989 @ref{Customizing Printing} talks more about this variable.
1991 @cindex setting variables
1992 @cindex Emacs, setting variables
1994 Variables can also hold Boolean values.  In Emacs Lisp, the Boolean
1995 values are @code{nil}, which means false, and @code{t}, which means true.
1996 Usually, variables are turned off by setting their value to @code{nil}, as
1999 @vindex @code{mh-bury-show-buffer}, example
2001 @lisp
2002 (setq mh-bury-show-buffer nil)
2003 @end lisp
2005 which keeps the MH-Show buffer at the top of the buffer stack.
2006 To turn a variable on, you use
2008 @lisp
2009 (setq mh-bury-show-buffer t)
2010 @end lisp
2012 which places the MH-Show buffer at the bottom of the buffer
2013 stack.  However, the text says to turn on a variable by setting it to a
2014 @emph{non-@code{nil}} value, because sometimes values other than @code{t} are
2015 meaningful (for example, see @code{mhl-formfile}, described in
2016 @ref{Customizing Viewing}).  Other variables, such as hooks, involve a
2017 little more Emacs Lisp programming expertise.
2019 You can also ``preview'' the effects of changing variables before
2020 committing the changes to @file{~/.emacs}.  Variables can be changed in
2021 the current Emacs session by using @kbd{M-x set-variable}.
2023 @c XXX Stephen says: would be easier to just call them functions, which
2024 @c you mostly do.
2025 In general, @dfn{commands} in this text refer to Emacs Lisp functions.
2026 Programs outside of Emacs are specifically called MH commands, shell
2027 commands, or Unix commands.
2029 @cindex Emacs, Emacs Lisp manual
2030 @cindex Emacs, online help
2031 @cindex online help
2032 @cindex Emacs, info
2033 @cindex info
2035 I hope I've included enough examples here to get you well on your way.
2036 If you want to explore Emacs Lisp further, a programming manual does
2037 exist,
2038 @c Yes, some of the stuff in the following sections is redundant, but
2039 @c TeX barfs if the @ifs are inside the @footnote.
2040 @iftex
2041 @footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available
2042 online in the Info system by typing @kbd{C-h i m Emacs Lisp RET}.  If
2043 not, you can order a printed manual, which has the desirable side-effect
2044 of helping to support the Free Software Foundation which made all this
2045 great software available.  You can find an order form by running
2046 @kbd{C-h C-d}, or you can request an order form from
2047 @i{gnu@@gnu.org}.}
2048 @end iftex
2049 @ifinfo
2050 @footnote{Perhaps you can find the online version of @ref{Top, The GNU
2051 Emacs Lisp Reference Manual, , elisp, GNU Emacs Lisp Reference Manual}.
2052 If not, you can order a printed manual, which has the desirable
2053 side-effect of helping to support the Free Software Foundation which
2054 made all this great software available.  You can find an order form by
2055 running @kbd{C-h C-d}, or you can request an order form from
2056 @i{gnu@@gnu.org}.}
2057 @end ifinfo
2058 and you can look at the code itself for examples.  Look in the Emacs
2059 Lisp directory on your system (such as @file{/usr/local/lib/emacs/lisp})
2060 and find all the @file{mh-*.el} files there.  When calling mh-e and
2061 other Emacs Lisp functions directly from Emacs Lisp code, you'll need to
2062 know the correct arguments.  Use the online help for this.  For example,
2063 try @kbd{C-h f mh-execute-commands RET}.  If you write your own
2064 functions, please do not prefix your symbols (variables and functions)
2065 with @code{mh-}.  This prefix is reserved for the mh-e package.  To
2066 avoid conflicts with existing mh-e symbols, use a prefix like @code{my-}
2067 or your initials.
2069 @menu
2070 * Customizing Reading::
2071 * Customizing Sending::
2072 * Customizing Draft Editing::
2073 * Customizing Moving Mail::
2074 * Customizing Searching::
2075 @end menu
2077 @node Customizing Reading, Customizing Sending, Customizing mh-e, Customizing mh-e
2078 @section Reading Your Mail
2080 @cindex reading mail
2081 @cindex @file{.emacs}
2082 @cindex files, @file{.emacs}
2084 I'll start out by including a function that I use as a front end to
2085 mh-e.  @footnote{Stephen Gildea's favorite binding is
2086 @kbd{(global-set-key "\C-cr" 'mh-rmail)}.} It toggles between your
2087 working window configuration, which may be quite involved---windows
2088 filled with source, compilation output, man pages, and other
2089 documentation---and your mh-e window configuration.  Like the rest of
2090 the customization described in this chapter, simply add the following
2091 code to @file{~/.emacs}.  Don't be intimidated by the size of this
2092 example; most customizations are only one line.
2094 @iftex
2095 @filbreak
2096 @end iftex
2098 @findex @code{mh-rmail}, example
2100 @lisp
2101 @group
2102 @i{Starting mh-e}
2104 (defvar my-mh-screen-saved nil
2105   "Set to non-@code{nil} when mh-e window configuration shown.")
2106 (defvar my-normal-screen nil "Normal window configuration.")
2107 (defvar my-mh-screen nil "mh-e window configuration.")
2109 (defun my-mh-rmail (&optional arg)
2110   "Toggle between mh-e and normal screen configurations.
2111 With non-@code{nil} or prefix argument, @i{inc} mailbox as well
2112 when going into mail."
2113   (interactive "P")                 ; @r{user callable function, P=prefix arg}
2114   (setq my-mh-screen-saved          ; @r{save state}
2115         (cond
2116          ;; @r{Bring up mh-e screen if arg or normal window configuration.}
2117          ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.}
2118          ((or arg (null my-mh-screen-saved))
2119           (setq my-normal-screen (current-window-configuration))
2120           (if (or arg (null (get-buffer "+inbox")))
2121               (mh-rmail)
2122             (set-window-configuration my-mh-screen))
2123           t)                        ; @r{set my-mh-screen-saved to @code{t}}
2124          ;; @r{Otherwise, save mh-e screen and restore normal screen.}
2125          (t
2126           (setq my-mh-screen (current-window-configuration))
2127           (set-window-configuration my-normal-screen)
2128           nil))))                   ; @r{set my-mh-screen-saved to nil}
2130 (global-set-key "\C-x\r" 'my-mh-rmail)  ;@r{ call with C-x RET}
2131 @end group
2132 @end lisp
2134 If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved}
2135 is @code{nil} (meaning a non-mh-e window configuration), the current window
2136 configuration is saved, either +inbox is displayed or @code{mh-rmail} is
2137 run, and the mh-e window configuration is shown.  Otherwise, the mh-e
2138 window configuration is saved and the original configuration is
2139 displayed.
2141 Now to configure mh-e.  The following table lists general mh-e variables
2142 and variables that are used while reading mail.
2143 @c XXX Seth wishes the descriptions to be more parallel.  That is,
2144 @c some are actions, and some are objects. Hmmm.
2146 @table @code
2147 @item mh-progs
2148 Directory containing MH programs (default: dynamic).
2150 @item mh-lib
2151 Directory containing MH support files and programs (default: dynamic).
2153 @item mh-do-not-confirm
2154 Don't confirm on non-reversible commands (default: @code{nil}).
2156 @item mh-summary-height
2157 Number of scan lines to show (includes mode line) (default: 4).
2159 @item mh-folder-mode-hook
2160 Functions to run in MH-Folder mode (default: @code{nil}).
2162 @item mh-clean-message-header
2163 Remove extraneous headers (default: @code{nil}).
2165 @item mh-invisible-headers
2166 Headers to hide (default: @samp{"^Received: \\| ^Message-Id: \\|
2167 ^Remailed-\\| ^Via: \\| ^Mail-from: \\| ^Return-Path: \\| ^In-Reply-To:
2168 \\| ^Resent-"}).
2170 @item mh-visible-headers
2171 Headers to display (default: @code{nil}).
2173 @item mhl-formfile
2174 Format file for @code{mhl} (default: @code{nil}).
2176 @item mh-show-hook
2177 Functions to run when showing message (default: @code{nil}).
2179 @item mh-show-mode-hook
2180 Functions to run when showing message (default: @code{nil}).
2182 @item mh-bury-show-buffer
2183 Leave show buffer at bottom of stack (default: @code{t}).
2185 @item mh-show-buffer-mode-line-buffer-id
2186 Name of show buffer in mode line (default: @samp{"@{show-%s@} %d"}).
2187 @end table
2189 @vindex @code{mh-progs}
2190 @vindex @code{mh-lib}
2192 The two variables @code{mh-progs} and @code{mh-lib} are used to tell
2193 mh-e where the MH programs and supporting files are kept, respectively.
2194 mh-e does try to figure out where they are kept for itself by looking in
2195 common places and in the user's @samp{PATH} environment variable, but if
2196 it cannot find the directories, or finds the wrong ones, you should set
2197 these variables.  The name of the directory should be placed in double
2198 quotes, and there should be a
2199 trailing slash (@samp{/}).  See the example in @ref{Getting Started}.
2201 @vindex @code{mh-do-not-confirm}
2202 @findex @code{mh-kill-folder}
2204 If you never make mistakes, and you do not like confirmations for your
2205 actions, you can set @code{mh-do-not-confirm} to a non-@code{nil} value to
2206 disable confirmation for unrecoverable commands such as @kbd{M-k}
2207 (@code{mh-kill-folder}) and @kbd{M-u} (@code{mh-undo-folder}).  Here's
2208 how you set boolean values:
2210 @lisp
2211 (setq mh-do-not-confirm t)
2212 @end lisp
2214 @vindex @code{mh-summary-height}
2215 @cindex MH-Folder mode
2216 @cindex modes, MH-Folder
2218 @c Prevent page break between paragraph and example.
2219 @need 2000
2220 The variable @code{mh-summary-height} controls the number of scan lines
2221 displayed in the MH-Folder window, including the mode line.  The
2222 default value of 4 means that 3 scan lines are displayed.  Here's how
2223 you set numerical values:
2225 @lisp
2226 (setq mh-summary-height 2)              ; @r{only show the current scan line}
2227 @end lisp
2229 @vindex @code{mh-bury-show-buffer}
2230 @cindex MH-Folder mode
2231 @cindex modes, MH-Folder
2233 Normally the buffer for displaying messages is buried at the bottom at
2234 the buffer stack.  You may wish to disable this feature by setting
2235 @code{mh-bury-show-buffer} to @code{nil}.  One advantage of not burying the
2236 show buffer is that one can delete the show buffer more easily in an
2237 electric buffer list because of its proximity to its associated
2238 MH-Folder buffer.  Try running @kbd{M-x electric-buffer-list} to
2239 see what I mean.
2241 @vindex @code{mh-folder-mode-hook}
2242 @cindex MH-Folder mode
2243 @cindex modes, MH-Folder
2245 The hook @code{mh-folder-mode-hook} is called when a new folder is
2246 created with MH-Folder mode.  This could be used to set your own
2247 key bindings, for example:
2249 @vindex @code{mh-folder-mode-hook}, example
2251 @lisp
2252 @group
2253 @i{Create additional key bindings via mh-folder-mode-hook}
2255 (defvar my-mh-init-done nil "Non-@code{nil} when one-time mh-e settings made.")
2257 (defun my-mh-folder-mode-hook ()
2258   "Hook to set key bindings in MH-Folder mode."
2259   (if (not my-mh-init-done)             ; @r{only need to bind the keys once }
2260       (progn
2261         (local-set-key "/" 'search-msg)
2262         (local-set-key "b" 'mh-burst-digest)    ; @r{better use of @kbd{b}}
2263         (setq my-mh-init-done t))))
2265 ;;; @r{Emacs 19}
2266 (add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook)
2267 ;;; @r{Emacs 18}
2268 ;;;   @r{(setq mh-folder-mode-hook (cons 'my-mh-folder-mode-hook}
2269 ;;;                               @r{mh-folder-mode-hook))}
2271 (defun search-msg ()
2272   "Search for a regexp in the current message."
2273   (interactive)                         ; @r{user function}
2274   (save-window-excursion
2275     (other-window 1)                    ; @r{go to next window}
2276     (isearch-forward-regexp)))          ; @r{string search; hit return (ESC}
2277                                         ;   @r{in Emacs 18) when done}
2278 @end group
2279 @end lisp
2281 @menu
2282 * Customizing Viewing::
2283 * Customizing Moving Around::
2284 @end menu
2286 @node Customizing Viewing, Customizing Moving Around, Customizing Reading, Customizing Reading
2287 @subsection Viewing Your Mail
2289 @vindex @code{mh-clean-message-header}
2290 @vindex @code{mh-invisible-headers}
2291 @vindex @code{mh-visible-headers}
2293 Several variables control what displayed messages look like.  Normally
2294 messages are delivered with a handful of uninteresting header fields.
2295 You can make them go away by setting @code{mh-clean-message-header} to a
2296 non-@code{nil} value.  The header can then be cleaned up in two ways.  By
2297 default, the header fields in @code{mh-invisible-headers} are removed.
2298 On the other hand, you could set @code{mh-visible-headers} to the fields
2299 that you would like to see.  If this variable is set,
2300 @code{mh-invisible-headers} is ignored.  I suggest that you not set
2301 @code{mh-visible-headers} since if you use this variable, you might miss
2302 a lot of header fields that you'd rather not miss.  As an example of how
2303 to set a string variable, @code{mh-visible-headers} can be set to show a
2304 minimum set of header fields (see (@ref{Regexps, , Syntax of Regular
2305 Expressions, emacs, The GNU Emacs Manual}, for a description of the
2306 special characters in this string):
2308 @lisp
2309 (setq mh-visible-headers "^From: \\|^Subject: \\|^Date: ")
2310 @end lisp
2312 @cindex @code{mhl}
2313 @cindex MH commands, @code{mhl}
2314 @vindex @code{mhl-formfile}
2316 Normally mh-e takes care of displaying messages itself (rather than
2317 calling an MH program to do the work).  If you'd rather have @code{mhl}
2318 display the message (within mh-e), set the variable @code{mhl-formfile}
2319 to a non-@code{nil} value.  You can set this variable either to @code{t}
2320 to use the default format file or to a filename if you have your own
2321 format file (@code{mhl}(1) tells you how to write one).  When writing
2322 your own format file, use a nonzero value for @code{overflowoffset} to
2323 ensure the header is RFC 822 compliant and parsable by mh-e.
2324 @code{mhl} is always used for printing and forwarding; in this case, the
2325 value of @code{mhl-formfile} is consulted if it is a filename.
2327 @vindex @code{mh-show-mode-hook}
2329 Two hooks can be used to control how messages are displayed.  The first
2330 hook, @code{mh-show-mode-hook}, is called early on in the process of
2331 displaying of messages.  It is used to perform some actions on the
2332 contents of messages, such as highlighting the header fields.  If you're
2333 running Emacs 19 under the X Window System, the following example will
2334 highlight the @samp{From:} and @samp{Subject:} header fields.  This is a
2335 very nice feature indeed.
2337 @vindex @code{mh-show-mode-hook}, example
2339 @lisp
2340 @group
2341 @i{Emphasize header fields in different fonts via mh-show-mode-hook}
2343 (defvar my-mh-keywords
2344    '(("^From: \\(.*\\)" 1 'bold t)
2345      ("^Subject: \\(.*\\)" 1 'highlight t))
2346   "mh-e additions for font-lock-keywords.")
2348 (defun my-mh-show-mode-hook ()
2349   "Hook to turn on and customize fonts."
2350   (font-lock-add-keywords nil my-mh-keywords))
2352 (add-hook 'mh-show-mode-hook 'my-mh-show-mode-hook))
2353 @end group
2354 @end lisp
2356 @vindex @code{mh-show-hook}
2358 The second hook, @code{mh-show-hook}, is the last thing called after
2359 messages are displayed.  It's used to affect the behavior of mh-e in
2360 general or when @code{mh-show-mode-hook} is too early.  For example, if
2361 you wanted to keep mh-e in sync with MH, you could use
2362 @code{mh-show-hook} as follows:
2364 @vindex @code{mh-show-hook}, example
2366 @lisp
2367 (add-hook 'mh-show-hook 'mh-update-sequences)
2368 @end lisp
2370 @vindex @code{mh-show-buffer-mode-line-buffer-id}
2371 @cindex MH-Show mode
2372 @cindex modes, MH-Show
2374 The function @code{mh-update-sequences} is documented in @ref{Finishing
2375 Up}.  For those who like to modify their mode lines, use
2376 @code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in the
2377 MH-Show buffers.  Place the two escape strings @samp{%s} and @samp{%d},
2378 which will display the folder name and the message number, respectively,
2379 somewhere in the string in that order.  The default value of
2380 @samp{"@{show-%s@} %d"} yields a mode line of
2382 @example
2383 -----@{show-+inbox@} 4      (MH-Show)--Bot--------------------------------
2384 @end example
2386 @node Customizing Moving Around,  , Customizing Viewing, Customizing Reading
2387 @subsection Moving Around
2389 @cindex moving between messages
2390 @cindex MH-Show mode
2391 @cindex modes, MH-Show
2392 @cindex MH-Folder mode
2393 @cindex modes, MH-Folder
2394 @vindex @code{mh-recenter-summary-p}
2396 When you use @kbd{t} (@code{mh-toggle-showing}) to toggle between show
2397 mode and scan mode, the MH-Show buffer is hidden and the
2398 MH-Folder buffer is left alone.  Setting
2399 @code{mh-recenter-summary-p} to a non-@code{nil} value causes the toggle to
2400 display as many scan lines as possible, with the cursor at the middle.
2401 The effect of @code{mh-recenter-summary-p} is rather useful, but it can
2402 be annoying on a slow network connection.
2404 @node Customizing Sending, Customizing Draft Editing, Customizing Reading, Customizing mh-e
2405 @section Sending Mail
2407 @cindex sending mail
2409 You may wish to start off by adding the following useful key bindings to
2410 your @file{.emacs} file:
2412 @lisp
2413 (global-set-key "\C-xm" 'mh-smail)
2414 (global-set-key "\C-x4m" 'mh-smail-other-window)
2415 @end lisp
2417 In addition, several variables are useful when sending mail or replying
2418 to mail.  They are summarized in the following table.
2420 @table @code
2421 @item mh-comp-formfile
2422 Format file for drafts (default: @samp{"components"}).
2424 @item mh-repl-formfile
2425 Format file for replies (default: @samp{"replcomps"}).
2427 @item mh-letter-mode-hook
2428 Functions to run in MH-Letter mode (default: @code{nil}).
2430 @item mh-compose-letter-function
2431 Functions to run when starting a new draft (default: @code{nil}).
2433 @item mh-reply-default-reply-to
2434 Whom reply goes to (default: @code{nil}).
2436 @item mh-forward-subject-format
2437 Format string for forwarded message subject (default: @samp{"%s: %s"}).
2439 @item mh-redist-full-contents
2440 @code{send} requires entire message (default: @code{nil}).
2442 @item mh-new-draft-cleaned-headers
2443 Remove these header fields from re-edited draft.  The default is:
2444 @example
2445 "^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\|
2446 ^Sender:\\| ^Delivery-Date:\\| ^Return-Path:".
2447 @end example
2448 @end table
2450 @cindex @code{comp}
2451 @cindex MH commands, @code{comp}
2452 @vindex @code{mh-comp-formfile}
2453 @cindex @file{components}
2454 @cindex files, @file{components}
2455 @cindex @code{repl}
2456 @cindex MH commands, @code{repl}
2457 @cindex @file{replcomps}
2458 @cindex files, @file{replcomps}
2459 @vindex @code{mh-repl-formfile}
2461 Since mh-e does not use @code{comp} to create the initial draft, you
2462 need to set @code{mh-comp-formfile} to the name of your components file
2463 if it isn't @file{components}.  This is the name of the file that
2464 contains the form for composing messages.  If it does not contain an
2465 absolute pathname, mh-e searches for the file first in your MH directory
2466 and then in the system MH library directory (such as
2467 @file{/usr/local/lib/mh}).  Replies, on the other hand, are built using
2468 @code{repl}.  You can change the location of the field file from the
2469 default of @file{replcomps} by modifying @code{mh-repl-formfile}.
2471 @vindex @code{mh-letter-mode-hook}
2472 @cindex @code{repl}
2473 @cindex MH commands, @code{repl}
2474 @cindex @file{components}
2475 @cindex files, @file{components}
2477 Two hooks are provided to run commands on your freshly created draft.
2478 The first hook, @code{mh-letter-mode-hook}, allows you to do some
2479 processing before editing a letter.  For example, you may wish to modify
2480 the header after @code{repl} has done its work, or you may have a
2481 complicated @file{components} file and need to tell mh-e where the
2482 cursor should go.  Here's an example of how you would use this hook---all
2483 of the other hooks are set in this fashion as well.
2485 @findex @code{mh-insert-signature}, example
2487 @lisp
2488 @group
2489 @i{Prepare draft for editing via mh-letter-mode-hook}
2491 (defvar letter-mode-init-done nil
2492   "Non-@code{nil} when one-time mh-e settings have made.")
2494 (defun my-mh-letter-mode-hook ()
2495   "Hook to prepare letter for editing."
2496   (if (not letter-mode-init-done)    ; @r{only need to bind the keys once}
2497       (progn
2498         (local-set-key "\C-ctb" 'add-enriched-text)
2499         (local-set-key "\C-cti" 'add-enriched-text)
2500         (local-set-key "\C-ctf" 'add-enriched-text)
2501         (local-set-key "\C-cts" 'add-enriched-text)
2502         (local-set-key "\C-ctB" 'add-enriched-text)
2503         (local-set-key "\C-ctu" 'add-enriched-text)
2504         (local-set-key "\C-ctc" 'add-enriched-text)
2505         (setq letter-mode-init-done t)))
2506   (setq fill-prefix "  ")            ; @r{I find indented text easier to read}
2507   (save-excursion
2508     (goto-char (point-max))          ; @r{go to end of message to}
2509     (mh-insert-signature)))          ;   @r{insert signature}
2511 (add-hook 'mh-letter-mode-hook 'my-mh-letter-mode-hook)
2512 @end group
2513 @end lisp
2515 The function, @code{add-enriched-text} is defined in the example in
2516 @ref{Customizing Editing MIME}.
2518 @vindex @code{mh-compose-letter-function}
2520 The second hook, a function really, is
2521 @code{mh-compose-letter-function}.  Like @code{mh-letter-mode-hook}, it
2522 is called just before editing a new message; however, it is the last
2523 function called before you edit your message.  The consequence of this
2524 is that you can write a function to write and send the message for you.
2525 This function is passed three arguments: the contents of the @samp{To:},
2526 @samp{Subject:}, and @samp{cc:} header fields.
2528 @menu
2529 * Customizing Replying::
2530 * Customizing Forwarding::
2531 * Customizing Redistributing::
2532 * Customizing Old Drafts::
2533 @end menu
2535 @node Customizing Replying, Customizing Forwarding, Customizing Sending, Customizing Sending
2536 @subsection Replying to Mail
2538 @cindex replying
2539 @vindex @code{mh-reply-default-reply-to}
2541 If you find that most of the time that you specify @kbd{cc} when you
2542 reply to a message, set @code{mh-reply-default-reply-to} to @samp{cc}.
2543 This variable is normally set to @code{nil} so that you are prompted for
2544 the recipient of a reply.  It can be set to one of @samp{from},
2545 @samp{to}, or @samp{cc}; you are then no longer prompted for the
2546 recipient(s) of your reply.
2548 @node Customizing Forwarding, Customizing Redistributing, Customizing Replying, Customizing Sending
2549 @subsection Forwarding Mail
2551 @cindex forwarding
2552 @vindex @code{mh-forward-subject-format}
2554 When forwarding a message, the format of the @samp{Subject:} header
2555 field can be modified by the variable @code{mh-forward-subject-format}.
2556 This variable is a string which includes two escapes (@samp{%s}).  The
2557 first @samp{%s} is replaced with the sender of the original message, and
2558 the second one is replaced with the original @samp{Subject:}.  The
2559 default value of @samp{"%s: %s"} takes a message with the header:
2561 @example
2562 @group
2563 To: Bill Wohler <wohler@@newt.com>
2564 Subject: Re: 49er football
2565 From: Greg DesBrisay <gd@@cellnet.com>
2566 @end group
2567 @end example
2569 and creates a subject header field of:
2571 @example
2572 Subject: Greg DesBrisay: Re: 49er football
2573 @end example
2575 @node Customizing Redistributing, Customizing Old Drafts, Customizing Forwarding, Customizing Sending
2576 @subsection Redistributing Your Mail
2578 @cindex redistributing
2579 @vindex @code{mh-redist-full-contents}
2580 @cindex @code{dist}
2581 @cindex MH commands, @code{dist}
2582 @cindex @code{send}
2583 @cindex MH commands, @code{send}
2585 The variable @code{mh-redist-full-contents} must be set to non-@code{nil} if
2586 @code{dist} requires the whole letter for redistribution, which is the
2587 case if @code{send} is compiled with the @sc{berk} @footnote{To see which
2588 options your copy of MH was compiled with, use @kbd{M-x mh-version}
2589 (@ref{Miscellaneous}).}  option (which many people abhor).  If you find
2590 that MH will not allow you to redistribute a message that has been
2591 redistributed before, this variable should be set to @code{nil}.
2593 @node Customizing Old Drafts,  , Customizing Redistributing, Customizing Sending
2594 @subsection Editing Old Drafts and Bounced Messages
2596 @cindex re-editing drafts
2597 @vindex @code{mh-new-draft-cleaned-headers}
2599 The header fields specified by @code{mh-new-draft-cleaned-headers} are
2600 removed from an old draft that has been recreated with @kbd{M-e}
2601 (@code{mh-extract-rejected-mail}) or @kbd{M-a} (@code{mh-edit-again}).
2602 If when you edit an old draft with these commands you find that there
2603 are header fields that you don't want included, you can append them to
2604 this variable.  For example,
2606 @vindex @code{mh-new-draft-cleaned-headers}, example
2608 @lisp
2609 (setq mh-new-draft-cleaned-headers
2610       (concat mh-new-draft-cleaned-headers "\\|^Some-Field:"))
2611 @end lisp
2613 @cindex regular expressions
2615 This appends the regular expression @samp{\\|^Some-Field:} to the
2616 variable (@pxref{Regexps, , Syntax of Regular Expressions, emacs, The
2617 GNU Emacs Manual}).  The @samp{\\|} means @emph{or}, and the @samp{^}
2618 (caret) matches the beginning of the line.  This is done to be very
2619 specific about which fields match.  The literal @samp{:} is appended for
2620 the same reason.
2622 @node Customizing Draft Editing, Customizing Moving Mail, Customizing Sending, Customizing mh-e
2623 @section Editing a Draft
2625 @cindex editing draft
2627 There are several variables used during the draft editing phase.
2628 Examples include changing the name of the file that holds your signature
2629 or telling mh-e about new multimedia types.  They are:
2631 @table @code
2632 @item mh-yank-from-start-of-msg
2633 How to yank when region not set (default: @code{t}).
2635 @item mh-ins-buf-prefix
2636 Indent for yanked messages (default: @samp{"> "}).
2638 @item mail-citation-hook
2639 Functions to run on yanked messages (default: @code{nil}).
2641 @item mh-delete-yanked-msg-window
2642 Delete message window on yank (default: @code{nil}).
2644 @c Need the @* because otherwise TeX fills it wrong and complains
2645 @c about overfull hbox.
2646 @item mh-mime-content-types
2647 List of valid content types (default: @samp{'(("text/plain")@*
2648 ("text/richtext") ("multipart/mixed") ("multipart/alternative")@*
2649 ("multipart/digest") ("multipart/parallel") ("message/rfc822")@*
2650 ("message/partial") ("message/external-body")@*
2651 ("application/octet-stream") ("application/postscript")@*
2652 ("image/jpeg") ("image/gif") ("audio/basic") ("video/mpeg"))}).
2654 @item mh-mhn-args
2655 Additional arguments for @code{mhn} (default: @code{nil}).
2657 @item mh-signature-file-name
2658 File containing signature (default: @samp{"~/.signature"}).
2660 @item mh-before-send-letter-hook
2661 Functions to run before sending draft (default: @code{nil}).
2663 @item mh-send-prog
2664 MH program used to send messages (default: @samp{"send"}).
2665 @end table
2667 @menu
2668 * Customizing Editing Textual::
2669 * Customizing Editing MIME::
2670 * Customizing Sending Message::
2671 @end menu
2673 @node Customizing Editing Textual, Customizing Editing MIME, Customizing Draft Editing, Customizing Draft Editing
2674 @subsection Editing Textual Messages
2676 The following two sections include variables that customize the way you
2677 edit a draft.  The discussion here applies to editing multimedia
2678 messages as well.
2680 @menu
2681 * Customizing Inserting Letter::
2682 * Customizing Signature::
2683 @end menu
2685 @node Customizing Inserting Letter, Customizing Signature, Customizing Editing Textual, Customizing Editing Textual
2686 @subsubsection Inserting letter to which you're replying
2688 @cindex inserting messages
2689 @vindex @code{mh-yank-from-start-of-msg}
2690 @vindex @code{mh-ins-buf-prefix}
2691 @vindex @code{mail-citation-hook}
2692 @vindex @code{mh-ins-buf-prefix}
2693 @vindex @code{mh-delete-yanked-msg-window}
2695 To control how much of the message to which you are replying is yanked
2696 by @kbd{C-c C-y} (@code{mh-yank-cur-msg}) into your reply, modify
2697 @code{mh-yank-from-start-of-msg}.  The default value of @code{t} means
2698 that the entire message is copied.  If it is set to @code{'body} (don't
2699 forget the apostrophe), then only the message body is copied.  If it is
2700 set to @code{nil}, only the part of the message following point (the
2701 current cursor position in the message's buffer) is copied.  In any
2702 case, this variable is ignored if a region is set in the message you are
2703 replying to.  The string contained in @code{mh-ins-buf-prefix} is
2704 inserted before each line of a message that is inserted into a draft
2705 with @kbd{C-c C-y} (@code{mh-yank-cur-msg}).  I suggest that you not
2706 modify this variable.  The default value of @samp{"> "} is the default
2707 string for many mailers and news readers: messages are far easier to
2708 read if several included messages have all been indented by the same
2709 string.  The variable @code{mail-citation-hook} is @code{nil} by
2710 default, which means that when a message is inserted into the letter,
2711 each line is prefixed by @code{mh-ins-buf-prefix}.  Otherwise, it can be
2712 set to a function that modifies an included
2713 @cindex Emacs, packages, supercite
2714 citation.
2715 @c Footnotes are fragile; hence the redundancy.
2716 @c TeX not inserting a line break; hence the @*
2717 @ifclear html
2718 @footnote{@emph{Supercite} is an example of a full-bodied, full-featured
2719 citation package.  It is in Emacs versions 19.15 and later, and can be
2720 found via anonymous @code{ftp} on @samp{archive.cis.ohio-state.edu} in
2721 @* @file{/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z}}
2722 @end ifclear
2723 @ifset html
2724 @footnote{@emph{Supercite} is an example of a full-bodied,
2725 full-featured citation package.  It is in Emacs versions 19.15 and
2726 later, and its @sc{url} is @*
2727 @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>}}
2728 @end ifset
2729 If you like to yank all the text from the message you're replying to in
2730 one go, set @code{mh-delete-yanked-msg-window} to non-@code{nil} to delete
2731 the window containing the original message after yanking it to make more
2732 room on your screen for your reply.
2734 @node Customizing Signature,  , Customizing Inserting Letter, Customizing Editing Textual
2735 @subsubsection Inserting your signature
2737 @cindex inserting signature
2738 @cindex signature
2739 @vindex @code{mh-signature-file-name}
2740 @cindex @file{.signature}
2741 @cindex files, @file{.signature}
2743 You can change the name of the file inserted with @kbd{C-c C-s}
2744 (@code{mh-insert-signature}) by changing @code{mh-signature-file-name}
2745 (default: @file{"~/.signature"}).
2747 @node Customizing Editing MIME, Customizing Sending Message, Customizing Editing Textual, Customizing Draft Editing
2748 @subsection Editing Multimedia Messages
2750 @cindex MIME
2751 @cindex multimedia mail
2752 @vindex @code{mh-mime-content-types}
2754 The variable @code{mh-mime-content-types} contains a list of the
2755 currently valid content types.  They are listed in the table in
2756 @ref{Customizing Draft Editing}.  If you encounter a new content type,
2757 you can add it like this:
2759 @vindex @code{mh-mime-content-types}, example
2761 @lisp
2762 (setq mh-mime-content-types (append mh-mime-content-types
2763                                     '(("@var{new/type}"))))
2764 @end lisp
2766 Emacs macros can be used to insert enriched text directives like
2767 @samp{<bold>}.  The following code will make, for example, @kbd{C-c t
2768 b} insert the @samp{<bold>} directive.
2770 @smallexample
2771 @group
2772 @i{Emacs macros for entering enriched text}
2774 (defvar enriched-text-types '(("b" . "bold") ("i" . "italic")
2775                               ("f" . "fixed") ("s" . "smaller")
2776                               ("B" . "bigger") ("u" . "underline")
2777                               ("c" . "center"))
2778   "Alist of (final-character . directive) choices for add-enriched-text.
2779 Additional types can be found in RFC 1563.")
2781 (defun add-enriched-text (begin end)
2782   "Add enriched text directives around region.
2783 The directive used comes from the list enriched-text-types and is
2784 specified by the last keystroke of the command.  When called from Lisp,
2785 arguments are BEGIN and END@."
2786   (interactive "r")
2787   ;; @r{Set type to the directive indicated by the last keystroke.}
2788   (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`}))
2789                           enriched-text-types))))
2790     (save-restriction              ; @r{restores state from narrow-to-region}
2791       (narrow-to-region begin end) ; @r{narrow view to region}
2792       (goto-char (point-min))      ; @r{move to beginning of text}
2793       (insert "<" type ">")        ; @r{insert beginning directive}
2794       (goto-char (point-max))      ; @r{move to end of text}
2795       (insert "</" type ">"))))    ; @r{insert terminating directive}
2796 @end group
2797 @end smallexample
2799 To use the function @code{add-enriched-text}, first create key bindings
2800 for it (@pxref{Customizing Sending}).  Then, set the mark with
2801 @kbd{C-@@} or @kbd{C-SPC}, type in the text to be highlighted, and type
2802 @kbd{C-c t b}.  This adds @samp{<bold>} where you set the mark and
2803 adds @samp{</bold>} at the location of your cursor, giving you something
2804 like: @samp{You should be <bold>very</bold>}.  You may also be
2805 interested in investigating @code{sgml-mode}.
2807 @menu
2808 * Customizing Sending MIME::
2809 @end menu
2811 @node Customizing Sending MIME,  , Customizing Editing MIME, Customizing Editing MIME
2812 @subsubsection Readying multimedia messages for sending
2814 @vindex @code{mh-mhn-args}
2816 If you wish to pass additional arguments to @code{mhn} to affect how it
2817 builds your message, use the variable @code{mh-mhn-args}.  For example,
2818 you can build a consistency check into the message by setting
2819 @code{mh-mhn-args} to @code{-check}.  The recipient of your message can
2820 then run @code{mhn -check} on the message---@code{mhn} will complain if
2821 the message has been corrupted on the way.  The @kbd{C-c C-e}
2822 (@code{mh-mhn-edit}) command only consults this variable when given a
2823 prefix argument.
2825 @node Customizing Sending Message,  , Customizing Editing MIME, Customizing Draft Editing
2826 @subsection Sending a Message
2828 @cindex sending mail
2829 @cindex spell check
2830 @vindex @code{mh-before-send-letter-hook}
2832 If you want to check your spelling in your message before sending, use
2833 @code{mh-before-send-letter-hook} like this:
2835 @i{Spell-check message via mh-before-send-letter-hook}
2837 @vindex @code{mh-before-send-letter-hook}, example
2839 @lisp
2840 (add-hook 'mh-before-send-letter-hook 'ispell-message)
2841 @end lisp
2843 @cindex @code{send}
2844 @cindex MH commands, @code{send}
2845 @vindex @code{mh-send-prog}
2847 In case the MH @code{send} program is installed under a different name,
2848 use @code{mh-send-prog} to tell mh-e the name.
2850 @node Customizing Moving Mail, Customizing Searching, Customizing Draft Editing, Customizing mh-e
2851 @section Moving Your Mail Around
2853 @cindex processing mail
2855 If you change the name of some of the MH programs or have your own
2856 printing programs, the following variables can help you.
2857 They are described in detail in the subsequent sections.
2859 @table @code
2860 @item mh-inc-prog
2861 Program to incorporate mail (default: @samp{"inc"}).
2863 @item mh-inc-folder-hook
2864 Functions to run when incorporating mail (default: @code{nil}).
2866 @item mh-delete-msg-hook
2867 Functions to run when deleting messages (default: @code{nil}).
2869 @item mh-print-background
2870 Print in foreground or background (default: @code{nil}).
2872 @item mh-lpr-command-format
2873 Command used to print (default: @samp{"lpr -J '%s'"}).
2875 @item mh-default-folder-for-message-function
2876 Function to generate a default folder (default: @code{nil}).
2878 @item mh-auto-folder-collect
2879 Collect folder names in background at startup (default: @code{t}).
2881 @item mh-recursive-folders
2882 Collect nested folders (default: @code{nil}).
2884 @item mh-refile-msg-hook
2885 Functions to run when refiling message (default: @code{nil}).
2887 @item mh-store-default-directory
2888 Default directory for storing files created by @code{uuencode} or @code{shar}
2889 (default: @code{nil}).
2891 @item mh-sortm-args
2892 Additional arguments for @code{sortm} (default: @code{nil}).
2894 @item mh-scan-prog
2895 Program to scan messages (default: @samp{"scan"}).
2897 @item mh-before-quit-hook
2898 Functions to run before quitting (default: @code{nil}).  See also
2899 @code{mh-quit-hook}.
2901 @item mh-quit-hook
2902 Functions to run after quitting (default: @code{nil}). See also
2903 @code{mh-before-quit-hook}.
2904 @end table
2906 @menu
2907 * Customizing Incorporating::
2908 * Customizing Deleting::
2909 * Customizing Organizing::
2910 * Customizing Printing::
2911 * Customizing Files and Pipes::
2912 * Customizing Finishing Up::
2913 @end menu
2915 @node Customizing Incorporating, Customizing Deleting, Customizing Moving Mail, Customizing Moving Mail
2916 @subsection Incorporating Your Mail
2918 @cindex incorporating
2919 @vindex @code{mh-inc-prog}
2920 @cindex @code{inc}
2921 @cindex MH commands, @code{inc}
2922 @vindex @code{mh-progs}
2923 @vindex @code{mh-scan-prog}
2924 @vindex @code{mh-inc-folder-hook}
2926 The name of the program that incorporates new mail is stored in
2927 @code{mh-inc-prog}; it is @samp{"inc"} by default.  This program
2928 generates a one-line summary for each of the new messages.  Unless it is
2929 an absolute pathname, the file is assumed to be in the @code{mh-progs}
2930 directory.  You may also link a file to @code{inc} that uses a different
2931 format (see @code{mh-profile}(5)).  You'll then need to modify several
2932 variables appropriately; see @code{mh-scan-prog} below.  You can set the
2933 hook @code{mh-inc-folder-hook}, which is called after new mail is
2934 incorporated by the @kbd{i} (@code{mh-inc-folder}) command.  A good use
2935 of this hook is to rescan the whole folder either after running @kbd{M-x
2936 mh-rmail} the first time or when you've changed the message numbers from
2937 outside of mh-e.
2939 @findex @code{mh-execute-commands}
2940 @findex @code{mh-rescan-folder}, example
2941 @findex @code{mh-show}, example
2942 @vindex @code{mh-inc-folder-hook}, example
2944 @lisp
2945 @group
2946 @i{Rescan folder after incorporating new mail via mh-inc-folder-hook}
2948 (defun my-mh-inc-folder-hook ()
2949   "Hook to rescan folder after incorporating mail."
2950   (if (buffer-modified-p)            ; @r{if outstanding refiles and deletes,}
2951       (mh-execute-commands))         ;   @r{carry them out}
2952   (mh-rescan-folder)                 ; @r{synchronize with +inbox}
2953   (mh-show))                         ; @r{show the current message}
2955 (add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook)
2956 @end group
2957 @end lisp
2959 @node Customizing Deleting, Customizing Organizing, Customizing Incorporating, Customizing Moving Mail
2960 @subsection Deleting Your Mail
2962 @cindex deleting
2963 @vindex @code{mh-delete-msg-hook}
2965 The hook @code{mh-delete-msg-hook} is called after you mark a message
2966 for deletion.  For example, the current maintainer of mh-e used this
2967 once when he kept statistics on his mail usage.
2969 @node Customizing Organizing, Customizing Printing, Customizing Deleting, Customizing Moving Mail
2970 @subsection Organizing Your Mail with Folders
2972 @cindex using folders
2973 @vindex @code{mh-recursive-folders}
2974 @vindex @code{mh-auto-folder-collect}
2976 By default, operations on folders work only one level at a time.  Set
2977 @code{mh-recursive-folders} to non-@code{nil} to operate on all folders.
2978 This mostly means that you'll be able to see all your folders when you
2979 press @key{TAB} when prompted for a folder name.  The variable
2980 @code{mh-auto-folder-collect} is normally turned on to generate a list
2981 of folder names in the background as soon as mh-e is loaded.  Otherwise,
2982 the list is generated when you need a folder name the first time (as
2983 with @kbd{o} (@code{mh-refile-msg})).  If you have a lot of folders and
2984 you have @code{mh-recursive-folders} set, this could take a while, which
2985 is why it's nice to do the folder collection in the background.
2987 @vindex @code{mh-default-folder-for-message-function}
2988 @findex @code{mh-refile-msg}
2989 @findex @code{mh-to-fcc}
2990 @cindex @file{.emacs}
2991 @cindex files, @file{.emacs}
2993 The function @code{mh-default-folder-for-message-function} is used by
2994 @kbd{o} (@code{mh-refile-msg}) and @kbd{C-c C-f C-f} (@code{mh-to-fcc})
2995 to generate a default folder.  The generated folder name should be a
2996 string with a @samp{+} before it.  For each of my correspondents, I use the
2997 same name for both an alias and a folder.  So, I wrote a function that
2998 takes the address in the @samp{From:} header field, finds it in my alias
2999 file, and returns the alias, which is used as a default folder name.
3000 This is the most complicated example given here, and it demonstrates
3001 several features of Emacs Lisp programming.  You should be able to drop
3002 this into @file{~/.emacs}, however.  If you use this to store messages
3003 in a subfolder of your Mail directory, you can modify the line that
3004 starts @samp{(format +%s...}  and insert your subfolder after the folder
3005 symbol @samp{+}.
3006 @c Note for me: if I insert a new version, don't forget to remove the
3007 @c "a/" from the folder name.
3009 @iftex
3010 @filbreak
3011 @end iftex
3013 @vindex @code{mh-default-folder-for-message-function}, example
3014 @vindex @code{mh-user-path}, example
3016 @smallexample
3017 @group
3018 @i{Creating useful default folder for refiling via mh-default-folder-for-message-function}
3020 (defun my-mh-folder-from-address ()
3021   "Determine folder name from address.
3022 Takes the address in the From: header field, and returns its
3023 corresponding alias from the user's personal aliases file. Returns
3024 @code{nil} if the address was not found."
3025   (require 'rfc822)                         ; @r{for the rfc822 functions}
3026   (search-forward-regexp "^From: \\(.*\\)") ; @r{grab header field contents}
3027   (save-excursion                     ; @r{save state}
3028     (let ((addr (car (rfc822-addresses  ; @r{get address}
3029                       (buffer-substring (match-beginning 1)
3030                                         (match-end 1)))))
3031           (buffer (get-buffer-create " *temp*")) ; @r{set local variables}
3032           folder)
3033       (set-buffer buffer)             ; @r{jump to temporary buffer}
3034       (unwind-protect                 ; @r{run kill-buffer when done}
3035           (progn                      ; @r{function grouping construct}
3036             (insert-file-contents (expand-file-name "aliases"
3037                                                     mh-user-path))
3038             (goto-char (point-min))   ; @r{grab aliases file and go to start}
3039             (setq folder
3040                   ;; @r{Search for the given address, even commented-out}
3041                   ;; @r{addresses are found!}
3042                   ;; @r{The function search-forward-regexp sets values that}
3043                   ;; @r{are later used by match-beginning and match-end.}
3044                   (if (search-forward-regexp (format "^;*\\(.*\\):.*%s"
3045                                                      addr) nil t)
3046                       ;; @r{NOTE WELL: this is what the return value looks}
3047                       ;; @r{like. You can modify the format string to match}
3048                       ;; @r{your own Mail hierarchy.}
3049                       (format "+%s" (buffer-substring
3050                                       (match-beginning 1)
3051                                       (match-end 1))))))
3052         (kill-buffer buffer))          ; @r{get rid of our temporary buffer}
3053       folder)))                        ; @r{function's return value}
3055 (setq mh-default-folder-for-message-function 'my-mh-folder-from-address)
3056 @end group
3057 @end smallexample
3059 @vindex @code{mh-refile-msg-hook}
3061 The hook @code{mh-refile-msg-hook} is called after a message is marked
3062 to be refiled.
3064 @vindex @code{mh-sortm-args}
3065 @cindex @code{sortm}
3066 @cindex MH commands, @code{sortm}
3067 @findex @code{mh-sort-folder}
3068 @cindex MH profile components, @code{sortm}
3069 @cindex @file{.mh_profile}
3070 @cindex files, @file{.mh_profile}
3072 The variable @code{mh-sortm-args} holds extra arguments to pass on to
3073 the @code{sortm} command.  Note: this variable is only consulted when a
3074 prefix argument is given to @kbd{M-x mh-sort-folder}.  It is used to
3075 override any arguments given in a @code{sortm:} entry in your MH profile
3076 (@file{~/.mh_profile}).
3078 @menu
3079 * Customizing Scan Line Formats::
3080 @end menu
3082 @node Customizing Scan Line Formats,  , Customizing Organizing, Customizing Organizing
3083 @subsubsection Scan line formatting
3085 @vindex @code{mh-scan-prog}
3086 @cindex @code{scan}
3087 @cindex MH commands, @code{scan}
3088 @vindex @code{mh-progs}
3090 The name of the program that generates a listing of one line per message
3091 is held in @code{mh-scan-prog} (default: @samp{"scan"}).  Unless this
3092 variable contains an absolute pathname, it is assumed to be in the
3093 @code{mh-progs} directory.  You may link another program to @code{scan}
3094 (see @code{mh-profile}(5)) to produce a different type of listing.
3096 If you change the format of the scan lines you'll need to tell mh-e how
3097 to parse the new format.  As you see, quite a lot of variables are
3098 involved to do that.  The first variable has to do with pruning out
3099 garbage.
3101 @table @code
3102 @item mh-valid-scan-line
3103 @vindex @code{mh-valid-scan-line}
3104 @cindex @code{inc}
3105 @cindex MH commands, @code{inc}
3106 @cindex @code{scan}
3107 @cindex MH commands, @code{scan}
3108 This regular expression describes a valid scan line.  This is used to
3109 eliminate error messages that are occasionally produced by @code{inc} or
3110 @code{scan} (default: @samp{"^ *[0-9]"}).
3111 @end table
3113 Next, two variables control how the message numbers are parsed.
3115 @table @code
3117 @item mh-msg-number-regexp
3118 @vindex @code{mh-msg-number-regexp}
3119 This regular expression is used to extract the message number from a
3120 scan line.  Note that the message number must be placed in quoted
3121 parentheses, (\\(...\\)), as in the default of @w{@samp{"^
3122 *\\([0-9]+\\)"}}.
3124 @item mh-msg-search-regexp
3125 @vindex @code{mh-msg-search-regexp}
3126 Given a message number (which is inserted in @samp{%d}), this regular
3127 expression will match the scan line that it represents (default:
3128 @samp{"^[^0-9]*%d[^0-9]"}).
3129 @end table
3131 Finally, there are a slew of variables that control how mh-e marks up
3132 the scan lines.
3134 @table @code
3135 @item mh-cmd-note
3136 @vindex @code{mh-cmd-note}
3137 Number of characters to skip over before inserting notation (default:
3138 4).  Note how it relates to the following regular expressions.
3140 @item mh-deleted-msg-regexp
3141 @vindex @code{mh-deleted-msg-regexp}
3142 This regular expression describes deleted messages (default:
3143 @samp{"^....D"}).  See also @code{mh-note-deleted}.
3145 @item mh-refiled-msg-regexp
3146 @vindex @code{mh-refiled-msg-regexp}
3147 This regular expression describes refiled messages (default:
3148 @samp{"^....\\^"}).  See also @code{mh-note-refiled}.
3150 @item mh-cur-scan-msg-regexp
3151 @vindex @code{mh-cur-scan-msg-regexp}
3152 This regular expression matches the current message (default:
3153 @samp{"^....\\+"}).  See also @code{mh-note-cur}.
3155 @item mh-good-msg-regexp
3156 @vindex @code{mh-good-msg-regexp}
3157 This regular expression describes which messages should be shown when
3158 mh-e goes to the next or previous message.  Normally, deleted or refiled
3159 messages are skipped over (default: @samp{"^....[^D^]"}).
3161 @item mh-note-deleted
3162 @vindex @code{mh-note-deleted}
3163 Messages that have been deleted to are marked by this string (default:
3164 @samp{"D"}).  See also @code{mh-deleted-msg-regexp}.
3166 @item mh-note-refiled
3167 @vindex @code{mh-note-refiled}
3168 Messages that have been refiled are marked by this string (default:
3169 @samp{"^"}).  See also @code{mh-refiled-msg-regexp}.
3171 @item mh-note-copied
3172 @vindex @code{mh-note-copied}
3173 Messages that have been copied are marked by this string (default:
3174 @samp{"C"}).
3176 @item mh-note-cur
3177 @vindex @code{mh-note-cur}
3178 The current message (in MH, not in mh-e) is marked by this string
3179 (default: @samp{"+"}).  See also @code{mh-cur-scan-msg-regexp}.
3181 @item mh-note-repl
3182 @vindex @code{mh-note-repl}
3183 Messages that have been replied to are marked by this string (default:
3184 @samp{"-"}).
3186 @item mh-note-forw
3187 @vindex @code{mh-note-forw}
3188 Messages that have been forwarded are marked by this string (default:
3189 @samp{"F"}).
3191 @item mh-note-dist
3192 @vindex @code{mh-note-dist}
3193 Messages that have been redistributed are marked by this string
3194 (default: @samp{"R"}).
3196 @item mh-note-printed
3197 @vindex @code{mh-note-printed}
3198 Messages that have been printed are marked by this string (default:
3199 @samp{"P"}).
3201 @item mh-note-seq
3202 @vindex @code{mh-note-seq}
3203 Messages in a sequence are marked by this string (default: @samp{"%"}).
3204 @end table
3206 @node Customizing Printing, Customizing Files and Pipes, Customizing Organizing, Customizing Moving Mail
3207 @subsection Printing Your Mail
3209 @cindex printing
3210 @vindex @code{mh-print-background}
3211 @vindex @code{mh-lpr-command-format}
3212 @cindex @code{lpr}
3213 @cindex Unix commands, @code{lpr}
3215 Normally messages are printed in the foreground.  If this is slow on
3216 your system, you may elect to set @code{mh-print-background} to
3217 non-@code{nil} to print in the background.  If you do this, do not delete
3218 the message until it is printed or else the output may be truncated.
3219 The variable @code{mh-lpr-command-format} controls how the printing is
3220 actually done.  The string can contain one escape, @samp{%s}, which is
3221 filled with the name of the folder and the message number and is useful
3222 for print job names.  As an example, the default is @samp{"lpr -J
3223 '%s'"}.
3225 @node Customizing Files and Pipes, Customizing Finishing Up, Customizing Printing, Customizing Moving Mail
3226 @subsection Files and Pipes
3228 @cindex using files
3229 @cindex using pipes
3230 @findex @code{mh-store-msg}
3231 @vindex @code{mh-store-default-directory}
3233 The initial directory for the @code{mh-store-msg} command is held in
3234 @code{mh-store-default-directory}.  Since I almost always run
3235 @code{mh-store-msg} on sources, I set it to my personal source directory
3236 like this:
3238 @vindex @code{mh-store-default-directory}, example
3240 @lisp
3241 (setq mh-store-default-directory (expand-file-name "~/src/"))
3242 @end lisp
3244 @findex @code{mh-store-buffer}
3245 @cindex @code{uuencode}
3246 @cindex Unix commands, @code{uuencode}
3247 @cindex @code{shar}
3248 @cindex Unix commands, @code{shar}
3250 Subsequent incarnations of @code{mh-store-msg} offer the last directory
3251 used as the default.  By the way, @code{mh-store-msg} calls the Emacs
3252 Lisp function @code{mh-store-buffer}.  I mention this because you can use
3253 it directly if you're editing a buffer that contains a file that has
3254 been run through @code{uuencode} or @code{shar}.  For example, you can
3255 extract the contents of the current buffer in your home directory by
3256 typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}.
3258 @node Customizing Finishing Up,  , Customizing Files and Pipes, Customizing Moving Mail
3259 @subsection Finishing Up
3261 @cindex quitting
3262 @vindex @code{mh-before-quit-hook}
3263 @vindex @code{mh-quit-hook}
3264 @findex @code{mh-execute-commands}
3266 The two variables @code{mh-before-quit-hook} and @code{mh-quit-hook} are
3267 called by @kbd{q} (@code{mh-quit}).  The former one is called before the
3268 quit occurs, so you might use it to perform any mh-e operations; you
3269 could perform some query and abort the quit or call
3270 @code{mh-execute-commands}, for example.  The latter is not run in an
3271 mh-e context, so you might use it to modify the window setup.
3273 @node Customizing Searching,  , Customizing Moving Mail, Customizing mh-e
3274 @section Searching Through Messages
3276 @cindex searching
3277 @vindex @code{mh-pick-mode-hook}
3278 @vindex @code{mh-partial-folder-mode-line-annotation}
3280 If you find that you do the same thing over and over when editing the
3281 search template, you may wish to bind some shortcuts to keys.  This can
3282 be done with the variable @code{mh-pick-mode-hook}, which is called when
3283 @kbd{M-s} (@code{mh-search-folder}) is run on a new pattern.
3285 The string
3286 @code{mh-partial-folder-mode-line-annotation} is used to annotate the
3287 mode line when only a portion of the folder is shown.  For example, this
3288 will be displayed after running @kbd{M-s} (@code{mh-search-folder}) to
3289 list messages based on some search criteria (see @ref{Searching}).  The
3290 default annotation of @samp{"select"} yields a mode line that looks
3291 like:
3293 @example
3294 --%%-@{+inbox/select@} 2 msgs (2-3)      (MH-Folder)--All-----------------
3295 @end example
3297 @node Odds and Ends, History, Customizing mh-e, Top
3298 @appendix Odds and Ends
3300 This appendix covers a few topics that don't fit elsewhere.  Here I tell
3301 you how to report bugs and how to get on the mh-e mailing list.  I also
3302 point out some additional sources of information.
3304 @menu
3305 * Bug Reports::
3306 * Mailing List::
3307 * MH FAQ::
3308 * Getting mh-e::
3309 @end menu
3311 @node Bug Reports, Mailing List, Odds and Ends, Odds and Ends
3312 @appendixsec Bug Reports
3314 @cindex bugs
3315 @cindex Wohler, Bill
3316 @cindex SourceForge
3318 The current maintainer of mh-e is Bill Wohler
3319 <@i{wohler@@newt.com}>. Bug reports should be filed at
3320 @uref{https://sourceforge.net/bugs/?group_id=13357, SourceForge}.
3321 Please include the output of
3322 @kbd{M-x mh-version} (@pxref{Miscellaneous}) in any bug report you send.
3324 @node Mailing List, MH FAQ, Bug Reports, Odds and Ends
3325 @appendixsec mh-e Mailing List
3327 @cindex mailing list
3328 @cindex SourceForge
3330 There are actually several mailing lists for mh-e. They are
3331 @i{mh-e-users@@lists.sourceforge.net},
3332 @i{mh-e-announce@@lists.sourceforge.net}, and
3333 @i{mh-e-devel@@lists.sourceforge.net}. You can subscribe or view the
3334 archives at @uref{https://sourceforge.net/mail/?group_id=13357,
3335 SourceForge}. Do not report bugs on these lists; please submit them
3336 via SourceForge (@pxref{Bug Reports}).
3338 @node MH FAQ, Getting mh-e, Mailing List, Odds and Ends
3339 @appendixsec MH FAQ
3341 @cindex MH FAQ
3342 @cindex FAQ
3344 An FAQ appears monthly in the newsgroup @samp{comp.mail.mh}.  While very
3345 little is there that deals with mh-e specifically, there is an
3346 incredible wealth of material about MH itself which you will find
3347 useful.  The subject of the FAQ is @cite{MH Frequently Asked Questions
3348 (FAQ) with Answers}.
3350 The FAQ is available via the World Wide Web (WWW) at
3351 @uref{http://www.faqs.org/faqs/mail/mh-faq/part1/preamble.html, faqs.org}.
3353 @node Getting mh-e,  , MH FAQ, Odds and Ends
3354 @appendixsec Getting mh-e
3356 @cindex obtaining mh-e
3358 The version of mh-e in the current version of Emacs should be up to
3359 date. It is most likely to be more up to date than the copy that comes
3360 with the MH distribution in @file{miscellany/mh-e}.
3362 @c intentionally wordy to avoid overfull hbox
3363 New mh-e releases are always available for downloading at
3364 @uref{https://sourceforge.net/project/showfiles.php?group_id=13357,
3365 SourceForge} before they appear in an Emacs release. You can read the
3366 release notes on that page to determine if the given release of mh-e
3367 is already installed in your version of Emacs.
3369 If you go this route, I suggest that you extract the files from
3370 @file{mh-e-@var{m.n}.tgz} in the following fashion:
3372 @smallexample
3373 @group
3374 % @kbd{cd}                                  # @r{Start in your home directory}
3375 % @kbd{mkdir lib lib/emacs}                 # @r{Create directory for mh-e}
3376 % @kbd{cd lib/emacs}
3377 % @kbd{zcat @var{path/to/}mh-e-@var{m.n}.tgz | tar xvf -}    # @r{Extract files}
3378 @end group
3379 @end smallexample
3381 @cindex @file{.emacs}
3382 @cindex files, @file{.emacs}
3384 To use these new files, add the following to @file{~/.emacs}:
3386 @lisp
3387 (setq load-path (cons (expand-file-name "~/lib/emacs") load-path))
3388 @end lisp
3390 @cindex news
3391 @cindex files, @samp{MH-E-NEWS}
3393 That's it!  If you're already running Emacs, please quit that session
3394 and start again to load in the new mh-e.  Check that you're running the
3395 new version with the command @kbd{M-x mh-version} after running any mh-e
3396 command.  The distribution comes with a file called @file{MH-E-NEWS} so
3397 you can see what's new.
3399 @node    History, Copying, Odds and Ends, Top
3400 @appendix History of mh-e
3402 @cindex Gildea, Stephen
3403 @cindex Larus, Jim
3404 @cindex Reid, Brian
3405 @cindex SourceForge
3406 @cindex history of mh-e
3408 mh-e was originally written by Brian Reid in 1983 and has changed
3409 hands several times since then. Jim Larus wanted to do something
3410 similar for GNU Emacs, and ended up completely rewriting it that same
3411 year. In 1989, Stephen Gildea picked it up and added many improvements.
3412 Bill Wohler then took over in 2000 and moved its development to
3413 @uref{http://sourceforge.net/, SourceForge}.
3415 @menu
3416 * From Brian Reid::
3417 * From Jim Larus::
3418 * From Stephen Gildea::
3419 @end menu
3421 @node From Brian Reid, From Jim Larus, History, History
3422 @appendixsec From Brian Reid
3424 @cindex Reid, Brian
3426 One day in 1983 I got the flu and had to stay home from work for three
3427 days with nothing to do.  I used that time to write MHE@.  The
3428 fundamental idea behind MHE was that it was a ``puppeteer'' driving the MH
3429 programs underneath it.  MH had a model that the editor was supposed to
3430 run as a subprocess of the mailer, which seemed to me at the time to be
3431 the tail wagging the dog.  So I turned it around and made the editor
3432 drive the MH programs.  I made sure that the UCI people (who were
3433 maintaining MH at the time) took in my changes and made them stick.
3435 Today, I still use my own version of MHE because I don't at all like the
3436 way that GNU mh-e works and I've never gotten to be good enough at
3437 hacking Emacs Lisp to make GNU mh-e do what I want.  The Gosling-emacs
3438 version of MHE and the GNU Emacs version of mh-e have almost nothing in
3439 common except similar names.  They work differently, have different
3440 conceptual models, and have different key bindings.  @footnote{After
3441 reading this article, I questioned Brian about his version of MHE, and
3442 received some great ideas for improving mh-e such as a dired-like method
3443 of selecting folders; and removing the prompting when sending mail,
3444 filling in the blanks in the draft buffer instead.  I passed them on to
3445 Stephen Gildea, the current maintainer, and he was excited about the
3446 ideas as well.  Perhaps one day, mh-e will again resemble MHE, although
3447 none of these ideas are manifest in Version 5.0.}
3449 Brian Reid, June 1994
3451 @node From Jim Larus, From Stephen Gildea, From Brian Reid, History
3452 @appendixsec From Jim Larus
3454 @cindex Larus, Jim
3456 Brian Reid, while at CMU or shortly after going to Stanford wrote a mail
3457 reading program called MHE for Gosling Emacs.  It had much the same
3458 structure as mh-e (i.e., invoked MH programs), though it was simpler and
3459 the commands were slightly different.  Unfortunately, I no longer have a
3460 copy so the differences are lost in the mists of time.
3462 In '82-83, I was working at BBN and wrote a lot of mlisp code in Gosling
3463 Emacs to make it look more like Tennex Emacs.  One of the packages that
3464 I picked up and improved was Reid's mail system.  In '83, I went back to
3465 Berkeley.  About that time, Stallman's first version of GNU Emacs came
3466 out and people started to move to it from Gosling Emacs (as I recall,
3467 the transition took a year or two).  I decided to port Reid's MHE and
3468 used the mlisp to Emacs Lisp translator that came with GNU Emacs.  It
3469 did a lousy job and the resulting code didn't work, so I bit the bullet
3470 and rewrote the code by hand (it was a lot smaller and simpler then, so
3471 it took only a day or two).
3473 Soon after that, mh-e became part of the standard Emacs distribution and
3474 suggestions kept dribbling in for improvements.  mh-e soon reached
3475 sufficient functionality to keep me happy, but I kept on improving it
3476 because I was a graduate student with plenty of time on my hands and it
3477 was more fun than my dissertation.  In retrospect, the one thing that I
3478 regret is not writing any documentation, which seriously limited the use
3479 and appeal of the package.
3481 @cindex @code{xmh}, in mh-e history
3483 In '89, I came to Wisconsin as a professor and decided not to work on
3484 mh-e.  It was stable, except for minor bugs, and had enough
3485 functionality, so I let it be for a few years.  Stephen Gildea of BBN
3486 began to pester me about the bugs, but I ignored them.  In 1990, he went
3487 off to the X Consortium, said good bye, and said that he would now be
3488 using @code{xmh}.  A few months later, he came back and said that he
3489 couldn't stand @code{xmh} and could I put a few more bug fixes into
3490 mh-e.  At that point, I had no interest in fixing mh-e, so I gave the
3491 responsibility of maintenance to him and he has done a fine job since
3492 then.
3494 Jim Larus, June 1994
3496 @node From Stephen Gildea,  , From Jim Larus, History
3497 @appendixsec From Stephen Gildea
3499 @cindex Gildea, Stephen
3501 In 1987 I went to work for Bolt Beranek and Newman, as Jim had before
3502 me.  In my previous job, I had been using RMAIL, but as my folders tend
3503 to run large, I was frustrated with the speed of RMAIL@.  However, I
3504 stuck with it because I wanted the GNU Emacs interface.  I am very
3505 familiar and comfortable with the Emacs interface (with just a few
3506 modifications of my own) and dislike having to use applications with
3507 embedded editors; they never live up to Emacs.
3509 MH is the mail reader of choice at BBN, so I converted to it.  Since I
3510 didn't want to give up using an Emacs interface, I started using mh-e.
3511 As is my wont, I started hacking on it almost immediately.  I first used
3512 version 3.4m.  One of the first features I added was to treat the folder
3513 buffer as a file-visiting buffer: you could lock it, save it, and be
3514 warned of unsaved changes when killing it.  I also worked to bring its
3515 functionality a little closer to RMAIL@.  Jim Larus was very cooperative
3516 about merging in my changes, and my efforts first appeared in version
3517 3.6, distributed with Emacs 18.52 in 1988.  Next I decided mh-e was too
3518 slow and optimized it a lot.  Version, 3.7, distributed with Emacs 18.56
3519 in 1990, was noticeably faster.
3521 When I moved to the X Consortium I became the first person there to not
3522 use xmh.  (There is now one other engineer there using mh-e.)  About
3523 this point I took over maintenance of mh-e from Jim and was finally able
3524 to add some features Jim hadn't accepted, such as the backward searching
3525 undo.  My first release was 3.8 (Emacs 18.58) in 1992.
3527 Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0.
3528 Version 4.0 added many new features, including background folder
3529 collection and support for composing @sc{mime} messages.  (Reading
3530 @sc{mime} messages remains to be done, alas.)  While writing this book,
3531 Bill Wohler gave mh-e its closest examination ever, uncovering bugs and
3532 inconsistencies that required a new major version to fix, and so version
3533 5 was released.
3535 Stephen Gildea, June 1994
3537 @node Copying, Command Index, History, Top
3538 @appendix GNU GENERAL PUBLIC LICENSE
3540 @center Version 2, June 1991
3542 @display
3543 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
3544 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
3546 Everyone is permitted to copy and distribute verbatim copies
3547 of this license document, but changing it is not allowed.
3548 @end display
3550 @appendixsec Preamble
3552   The licenses for most software are designed to take away your
3553 freedom to share and change it.  By contrast, the GNU General Public
3554 License is intended to guarantee your freedom to share and change free
3555 software---to make sure the software is free for all its users.  This
3556 General Public License applies to most of the Free Software
3557 Foundation's software and to any other program whose authors commit to
3558 using it.  (Some other Free Software Foundation software is covered by
3559 the GNU Library General Public License instead.)  You can apply it to
3560 your programs, too.
3562   When we speak of free software, we are referring to freedom, not
3563 price.  Our General Public Licenses are designed to make sure that you
3564 have the freedom to distribute copies of free software (and charge for
3565 this service if you wish), that you receive source code or can get it
3566 if you want it, that you can change the software or use pieces of it
3567 in new free programs; and that you know you can do these things.
3569   To protect your rights, we need to make restrictions that forbid
3570 anyone to deny you these rights or to ask you to surrender the rights.
3571 These restrictions translate to certain responsibilities for you if you
3572 distribute copies of the software, or if you modify it.
3574   For example, if you distribute copies of such a program, whether
3575 gratis or for a fee, you must give the recipients all the rights that
3576 you have.  You must make sure that they, too, receive or can get the
3577 source code.  And you must show them these terms so they know their
3578 rights.
3580   We protect your rights with two steps: (1) copyright the software, and
3581 (2) offer you this license which gives you legal permission to copy,
3582 distribute and/or modify the software.
3584   Also, for each author's protection and ours, we want to make certain
3585 that everyone understands that there is no warranty for this free
3586 software.  If the software is modified by someone else and passed on, we
3587 want its recipients to know that what they have is not the original, so
3588 that any problems introduced by others will not reflect on the original
3589 authors' reputations.
3591   Finally, any free program is threatened constantly by software
3592 patents.  We wish to avoid the danger that redistributors of a free
3593 program will individually obtain patent licenses, in effect making the
3594 program proprietary.  To prevent this, we have made it clear that any
3595 patent must be licensed for everyone's free use or not licensed at all.
3597   The precise terms and conditions for copying, distribution and
3598 modification follow.
3600 @iftex
3601 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3602 @end iftex
3603 @ifinfo
3604 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3605 @end ifinfo
3607 @enumerate 0
3608 @item
3609 This License applies to any program or other work which contains
3610 a notice placed by the copyright holder saying it may be distributed
3611 under the terms of this General Public License.  The ``Program,'' below,
3612 refers to any such program or work, and a ``work based on the Program''
3613 means either the Program or any derivative work under copyright law:
3614 that is to say, a work containing the Program or a portion of it,
3615 either verbatim or with modifications and/or translated into another
3616 language.  (Hereinafter, translation is included without limitation in
3617 the term ``modification.'')  Each licensee is addressed as ``you.''
3619 Activities other than copying, distribution and modification are not
3620 covered by this License; they are outside its scope.  The act of
3621 running the Program is not restricted, and the output from the Program
3622 is covered only if its contents constitute a work based on the
3623 Program (independent of having been made by running the Program).
3624 Whether that is true depends on what the Program does.
3626 @item
3627 You may copy and distribute verbatim copies of the Program's
3628 source code as you receive it, in any medium, provided that you
3629 conspicuously and appropriately publish on each copy an appropriate
3630 copyright notice and disclaimer of warranty; keep intact all the
3631 notices that refer to this License and to the absence of any warranty;
3632 and give any other recipients of the Program a copy of this License
3633 along with the Program.
3635 You may charge a fee for the physical act of transferring a copy, and
3636 you may at your option offer warranty protection in exchange for a fee.
3638 @item
3639 You may modify your copy or copies of the Program or any portion
3640 of it, thus forming a work based on the Program, and copy and
3641 distribute such modifications or work under the terms of Section 1
3642 above, provided that you also meet all of these conditions:
3644 @enumerate a
3645 @item
3646 You must cause the modified files to carry prominent notices
3647 stating that you changed the files and the date of any change.
3649 @item
3650 You must cause any work that you distribute or publish, that in
3651 whole or in part contains or is derived from the Program or any
3652 part thereof, to be licensed as a whole at no charge to all third
3653 parties under the terms of this License.
3655 @item
3656 If the modified program normally reads commands interactively
3657 when run, you must cause it, when started running for such
3658 interactive use in the most ordinary way, to print or display an
3659 announcement including an appropriate copyright notice and a
3660 notice that there is no warranty (or else, saying that you provide
3661 a warranty) and that users may redistribute the program under
3662 these conditions, and telling the user how to view a copy of this
3663 License.  (Exception: if the Program itself is interactive but
3664 does not normally print such an announcement, your work based on
3665 the Program is not required to print an announcement.)
3666 @end enumerate
3668 These requirements apply to the modified work as a whole.  If
3669 identifiable sections of that work are not derived from the Program,
3670 and can be reasonably considered independent and separate works in
3671 themselves, then this License, and its terms, do not apply to those
3672 sections when you distribute them as separate works.  But when you
3673 distribute the same sections as part of a whole which is a work based
3674 on the Program, the distribution of the whole must be on the terms of
3675 this License, whose permissions for other licensees extend to the
3676 entire whole, and thus to each and every part regardless of who wrote it.
3678 Thus, it is not the intent of this section to claim rights or contest
3679 your rights to work written entirely by you; rather, the intent is to
3680 exercise the right to control the distribution of derivative or
3681 collective works based on the Program.
3683 In addition, mere aggregation of another work not based on the Program
3684 with the Program (or with a work based on the Program) on a volume of
3685 a storage or distribution medium does not bring the other work under
3686 the scope of this License.
3688 @item
3689 You may copy and distribute the Program (or a work based on it,
3690 under Section 2) in object code or executable form under the terms of
3691 Sections 1 and 2 above provided that you also do one of the following:
3693 @enumerate a
3694 @item
3695 Accompany it with the complete corresponding machine-readable
3696 source code, which must be distributed under the terms of Sections
3697 1 and 2 above on a medium customarily used for software interchange; or,
3699 @item
3700 Accompany it with a written offer, valid for at least three
3701 years, to give any third party, for a charge no more than your
3702 cost of physically performing source distribution, a complete
3703 machine-readable copy of the corresponding source code, to be
3704 distributed under the terms of Sections 1 and 2 above on a medium
3705 customarily used for software interchange; or,
3707 @item
3708 Accompany it with the information you received as to the offer
3709 to distribute corresponding source code.  (This alternative is
3710 allowed only for noncommercial distribution and only if you
3711 received the program in object code or executable form with such
3712 an offer, in accord with Subsection b above.)
3713 @end enumerate
3715 The source code for a work means the preferred form of the work for
3716 making modifications to it.  For an executable work, complete source
3717 code means all the source code for all modules it contains, plus any
3718 associated interface definition files, plus the scripts used to
3719 control compilation and installation of the executable.  However, as a
3720 special exception, the source code distributed need not include
3721 anything that is normally distributed (in either source or binary
3722 form) with the major components (compiler, kernel, and so on) of the
3723 operating system on which the executable runs, unless that component
3724 itself accompanies the executable.
3726 If distribution of executable or object code is made by offering
3727 access to copy from a designated place, then offering equivalent
3728 access to copy the source code from the same place counts as
3729 distribution of the source code, even though third parties are not
3730 compelled to copy the source along with the object code.
3732 @item
3733 You may not copy, modify, sublicense, or distribute the Program
3734 except as expressly provided under this License.  Any attempt
3735 otherwise to copy, modify, sublicense or distribute the Program is
3736 void, and will automatically terminate your rights under this License.
3737 However, parties who have received copies, or rights, from you under
3738 this License will not have their licenses terminated so long as such
3739 parties remain in full compliance.
3741 @item
3742 You are not required to accept this License, since you have not
3743 signed it.  However, nothing else grants you permission to modify or
3744 distribute the Program or its derivative works.  These actions are
3745 prohibited by law if you do not accept this License.  Therefore, by
3746 modifying or distributing the Program (or any work based on the
3747 Program), you indicate your acceptance of this License to do so, and
3748 all its terms and conditions for copying, distributing or modifying
3749 the Program or works based on it.
3751 @item
3752 Each time you redistribute the Program (or any work based on the
3753 Program), the recipient automatically receives a license from the
3754 original licensor to copy, distribute or modify the Program subject to
3755 these terms and conditions.  You may not impose any further
3756 restrictions on the recipients' exercise of the rights granted herein.
3757 You are not responsible for enforcing compliance by third parties to
3758 this License.
3760 @item
3761 If, as a consequence of a court judgment or allegation of patent
3762 infringement or for any other reason (not limited to patent issues),
3763 conditions are imposed on you (whether by court order, agreement or
3764 otherwise) that contradict the conditions of this License, they do not
3765 excuse you from the conditions of this License.  If you cannot
3766 distribute so as to satisfy simultaneously your obligations under this
3767 License and any other pertinent obligations, then as a consequence you
3768 may not distribute the Program at all.  For example, if a patent
3769 license would not permit royalty-free redistribution of the Program by
3770 all those who receive copies directly or indirectly through you, then
3771 the only way you could satisfy both it and this License would be to
3772 refrain entirely from distribution of the Program.
3774 If any portion of this section is held invalid or unenforceable under
3775 any particular circumstance, the balance of the section is intended to
3776 apply and the section as a whole is intended to apply in other
3777 circumstances.
3779 It is not the purpose of this section to induce you to infringe any
3780 patents or other property right claims or to contest validity of any
3781 such claims; this section has the sole purpose of protecting the
3782 integrity of the free software distribution system, which is
3783 implemented by public license practices.  Many people have made
3784 generous contributions to the wide range of software distributed
3785 through that system in reliance on consistent application of that
3786 system; it is up to the author/donor to decide if he or she is willing
3787 to distribute software through any other system and a licensee cannot
3788 impose that choice.
3790 This section is intended to make thoroughly clear what is believed to
3791 be a consequence of the rest of this License.
3793 @item
3794 If the distribution and/or use of the Program is restricted in
3795 certain countries either by patents or by copyrighted interfaces, the
3796 original copyright holder who places the Program under this License
3797 may add an explicit geographical distribution limitation excluding
3798 those countries, so that distribution is permitted only in or among
3799 countries not thus excluded.  In such case, this License incorporates
3800 the limitation as if written in the body of this License.
3802 @item
3803 The Free Software Foundation may publish revised and/or new versions
3804 of the General Public License from time to time.  Such new versions will
3805 be similar in spirit to the present version, but may differ in detail to
3806 address new problems or concerns.
3808 Each version is given a distinguishing version number.  If the Program
3809 specifies a version number of this License which applies to it and ``any
3810 later version,'' you have the option of following the terms and conditions
3811 either of that version or of any later version published by the Free
3812 Software Foundation.  If the Program does not specify a version number of
3813 this License, you may choose any version ever published by the Free Software
3814 Foundation.
3816 @item
3817 If you wish to incorporate parts of the Program into other free
3818 programs whose distribution conditions are different, write to the author
3819 to ask for permission.  For software which is copyrighted by the Free
3820 Software Foundation, write to the Free Software Foundation; we sometimes
3821 make exceptions for this.  Our decision will be guided by the two goals
3822 of preserving the free status of all derivatives of our free software and
3823 of promoting the sharing and reuse of software generally.
3825 @iftex
3826 @heading NO WARRANTY
3827 @end iftex
3828 @ifinfo
3829 @center NO WARRANTY
3830 @end ifinfo
3832 @item
3833 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
3834 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
3835 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
3836 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
3837 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
3838 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
3839 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
3840 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
3841 REPAIR OR CORRECTION.
3843 @item
3844 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
3845 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
3846 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
3847 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
3848 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
3849 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
3850 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
3851 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
3852 POSSIBILITY OF SUCH DAMAGES.
3853 @end enumerate
3855 @iftex
3856 @heading END OF TERMS AND CONDITIONS
3857 @end iftex
3858 @ifinfo
3859 @center END OF TERMS AND CONDITIONS
3860 @end ifinfo
3862 @page
3863 @appendixsec How to Apply These Terms to Your New Programs
3865   If you develop a new program, and you want it to be of the greatest
3866 possible use to the public, the best way to achieve this is to make it
3867 free software which everyone can redistribute and change under these terms.
3869   To do so, attach the following notices to the program.  It is safest
3870 to attach them to the start of each source file to most effectively
3871 convey the exclusion of warranty; and each file should have at least
3872 the ``copyright'' line and a pointer to where the full notice is found.
3874 @smallexample
3875 @var{one line to give the program's name and an idea of what it does.}
3876 Copyright (C) 20@var{yy}  @var{name of author}
3878 This program is free software; you can redistribute it and/or
3879 modify it under the terms of the GNU General Public License
3880 as published by the Free Software Foundation; either version 2
3881 of the License, or (at your option) any later version.
3883 This program is distributed in the hope that it will be useful,
3884 but WITHOUT ANY WARRANTY; without even the implied warranty of
3885 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
3886 GNU General Public License for more details.
3888 You should have received a copy of the GNU General Public License along
3889 with this program; if not, write to the Free Software Foundation, Inc.,
3890 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
3891 @end smallexample
3893 Also add information on how to contact you by electronic and paper mail.
3895 If the program is interactive, make it output a short notice like this
3896 when it starts in an interactive mode:
3898 @smallexample
3899 Gnomovision version 69, Copyright (C) 20@var{yy} @var{name of author}
3900 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
3901 type `show w'.  This is free software, and you are welcome
3902 to redistribute it under certain conditions; type `show c'
3903 for details.
3904 @end smallexample
3906 The hypothetical commands @samp{show w} and @samp{show c} should show
3907 the appropriate parts of the General Public License.  Of course, the
3908 commands you use may be called something other than @samp{show w} and
3909 @samp{show c}; they could even be mouse-clicks or menu items---whatever
3910 suits your program.
3912 You should also get your employer (if you work as a programmer) or your
3913 school, if any, to sign a ``copyright disclaimer'' for the program, if
3914 necessary.  Here is a sample; alter the names:
3916 @smallexample
3917 @group
3918 Yoyodyne, Inc., hereby disclaims all copyright
3919 interest in the program `Gnomovision'
3920 (which makes passes at compilers) written
3921 by James Hacker.
3923 @var{signature of Ty Coon}, 1 April 1989
3924 Ty Coon, President of Vice
3925 @end group
3926 @end smallexample
3928 This General Public License does not permit incorporating your program into
3929 proprietary programs.  If your program is a subroutine library, you may
3930 consider it more useful to permit linking proprietary applications with the
3931 library.  If this is what you want to do, use the GNU Library General
3932 Public License instead of this License.
3934 @node    Command Index, Variable Index, Copying, Top
3935 @unnumbered Command Index
3937 @printindex fn
3939 @node    Variable Index, Concept Index, Command Index, Top
3940 @unnumbered Variable Index
3942 @printindex vr
3944 @node    Concept Index,  , Variable Index, Top
3945 @unnumbered Concept Index
3947 @printindex cp
3949 @contents
3950 @bye
3952 @c XXX In the sections on customizing mh-e, you can add cross-references
3953 @c to the Emacs manual and the Emacs Lisp manual wherever they are
3954 @c useful. @pxref{node, , section, emacs, The GNU Emacs Manual}