(filter-buffer-substring): Fix typo in docstring.
[emacs.git] / man / mh-e.texi
blobc998debb16bfee33ddefff94722ee4386af1f6fc
1 \input texinfo   @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../info/mh-e
4 @settitle mh-e
5 @c %**end of header
7 @c Version variables.
8 @set EDITION 1.3
9 @set VERSION 5.0.2
10 @set UPDATED 18 February 2001
11 @set UPDATE-MONTH February 2001
13 @copying
14 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
15 @cite{mh-e, The Emacs Interface to MH}, for mh-e, Version
16 @value{VERSION}.
18 Copyright 1995, 2001, 2002, 2004 Free Software Foundation, Inc.
20 @quotation
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.1 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU
25 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
26 license is included in the section entitled ``GNU Free Documentation
27 License'' in the Emacs manual.
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
30 this GNU Manual, like GNU software.  Copies published by the Free
31 Software Foundation raise funds for GNU development.''
33 This document is part of a collection distributed under the GNU Free
34 Documentation License.  If you want to distribute this document
35 separately from the collection, you can do so by adding a copy of the
36 license to the document, as described in section 6 of the license.
37 @end quotation
38 @end copying
40 @setchapternewpage odd
42 @dircategory Emacs
43 @direntry
44 * MH-E: (mh-e).         Emacs interface to the MH mail system.
45 @end direntry
47 @titlepage
48 @sp 10
49 @center @titlefont{mh-e}
50 @sp 2
51 @center The Emacs Interface to MH
52 @sp 2
53 @center by Bill Wohler
54 @sp 2
55 @center Edition @value{EDITION} for mh-e Version @value{VERSION}
56 @sp 2
57 @center @value{UPDATE-MONTH}
59 @page
60 @vskip 0pt plus 1filll
61 Copyright @copyright{} 1995, 2001, 2002 Free Software Foundation, Inc.
62 @insertcopying
63 @end titlepage
65 @ifnottex
66 @node Top, Preface, (dir), (dir)
67 @top MH and Emacs
68 This is Edition @value{EDITION} of @cite{mh-e, The Emacs Interface to
69 MH}, last updated @value{UPDATED} for mh-e Version @value{VERSION}.
71 @menu
72 * Preface::                     Introduction to mh-e.
73 * Tour Through mh-e::           Use mh-e quickly!
74 * Using mh-e::                  Documentation for all commands.
75 * Customizing mh-e::            Documentation for all variables.
76 * Odds and Ends::               Getting mh-e, reporting bugs, mailing
77                                 list and FAQ.
78 * History::                     The authors speak up!
79 * Copying::                     The GNU General Public License
80 * Command Index::
81 * Variable Index::
82 * Concept Index::
83 @end menu
84 @end ifnottex
86 @node Preface, Tour Through mh-e, Top, Top
87 @unnumbered Preface
89 @cindex Emacs
90 @cindex Unix commands, Emacs
92 These chapters introduce another interface to MH that is accessible
93 through the GNU Emacs editor, namely, @emph{mh-e}.  mh-e is easy to use.
94 I don't assume that you know GNU Emacs or even MH at this point, since I
95 didn't know either of them when I discovered mh-e.  However, mh-e was
96 the tip of the iceberg, and I discovered more and more niceties about
97 GNU Emacs and MH@.  Now I'm fully hooked on both of them.
99 @cindex history
101 The mh-e package is distributed with GNU Emacs, @footnote{Note that
102 mh-e is supported with MH 6 and @w{Emacs 18} and up.
103 Reportedly, large parts of it work with @w{MH 5} and also with
104 Lucid/XEmacs and Epoch, but there are no guarantees. It is also
105 distributed with Lucid/XEmacs, as well as with MH itself.} so you
106 shouldn't have to do anything special to use it. But it's important to
107 note a brief history of mh-e. @w{Version 3} was prevalent through the
108 @w{Emacs 18} and early @w{Emacs 19} years. Then @w{Version 4} came out
109 (@w{Emacs 19.23}), which introduced several new and changed commands.
110 Finally, @w{Version 5.0} was released, which fixed some bugs and
111 incompatibilities, and was incorporated into @w{Emacs 19.29}. This is
112 the version covered by this manual. @ref{Getting Started} will help
113 you decide which version you have.
115 If you don't already use GNU Emacs but want to learn more, you can read
116 an online tutorial by starting GNU Emacs and typing @kbd{C-h t}
117 (@code{help-with-tutorial}).  (This notation is described in
118 @ref{Conventions}.)  If you want to take the plunge, consult the
119 @iftex
120 @cite{GNU Emacs Manual},
121 @end iftex
122 @ifinfo
123 @ref{top, , GNU Emacs Manual, emacs, The GNU Emacs Manual},
124 @end ifinfo
125 from the Free Software Foundation.
127 If more information is needed, you can go to the Unix manual pages of
128 the individual MH commands.  When the name is not obvious, I'll guide
129 you to a relevant MH manual page that describes the action more fully.
131 I hope you enjoy these chapters!  If you have any comments, or
132 suggestions for this document, please let me know.
134 @noindent
135 Bill Wohler <@i{wohler@@newt.com}>@*
136 8 February 1995
138 @node    Tour Through mh-e, Using mh-e, Preface, Top
139 @chapter Tour Through mh-e
141 This chapter introduces some of the terms you'll need to know and then
142 takes you on a tour of mh-e. @footnote{The keys mentioned in these
143 chapters refer to the default key bindings.  If you've changed the
144 bindings, refer to the command summaries at the beginning of each major
145 section in @ref{Using mh-e}, for a mapping between default key bindings
146 and function names.}  When you're done, you'll be able to send, read,
147 and file mail, which is all that a lot of people ever do.  But if you're
148 the curious type, you'll read @ref{Using mh-e} to be able to use all
149 the features of mh-e.  If you're the adventurous type, you'll read
150 @ref{Customizing mh-e} to make mh-e do what you want.  I suggest you
151 read this chapter first to get the big picture, and then you can read
152 the other two as you wish.
154 @menu
155 * Conventions::                 GNU Emacs Terms and Conventions
156 * Getting Started::
157 * Sending Mail Tour::
158 * Reading Mail Tour::
159 * Processing Mail Tour::
160 * Leaving mh-e::
161 * More About mh-e::
162 @end menu
164 @node Conventions, Getting Started, Tour Through mh-e, Tour Through mh-e
165 @section GNU Emacs Terms and Conventions
167 @cindex Emacs, terms and conventions
169 @cindex Emacs
170 @cindex Unix commands, Emacs
172 If you're an experienced Emacs user, you can skip the following
173 conventions and definition of terms and go directly to @ref{Getting
174 Started} below.  The conventions are as follows:
176 @table @kbd
177 @item C-x
178 Hold down the @key{CTRL} (Control) key and press the @kbd{x} key.
179 @item M-x
180 Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key.
182 Since some keyboards don't have a @key{META} key, you can generate
183 @kbd{M-x}, for example, by pressing @key{ESC} (Escape), @emph{releasing
184 it}, @footnote{This is emphasized because pressing ESC twice or holding
185 it down a second too long so that it repeats gives you an error message.}
186 and then pressing the @kbd{x} key.
187 @item RET
188 Press the @key{RETURN} or @key{ENTER} key.  This is normally used to
189 complete a command.
190 @item SPC
191 Press the space bar.
192 @item TAB
193 Press the @key{TAB} key.
194 @item DEL
195 Press the @key{DELETE} key.
196 @item BS
197 Press the @key{BACKSPACE} key. @footnote{If you are using Version 20
198 or earlier of Emacs, you will need to use the @key{DEL} key.}
199 @end table
201 @cindex Emacs, prefix argument
202 @cindex prefix argument
204 A @dfn{prefix argument} allows you to pass an argument to any Emacs
205 function.  To pass an argument, type @kbd{C-u} before the Emacs command
206 or keystroke.  Numeric arguments can be passed as well.  For example, to
207 insert five f's, use @kbd{C-u 5 f}.  There is a default of four when
208 using @kbd{C-u}, and you can use multiple prefix arguments to provide
209 arguments of powers of four.  To continue our example, you could insert
210 four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with
211 @kbd{C-u C-u C-u f}, and so on.  Numeric and valueless negative
212 arguments can also be inserted with the @key{META} key.  Examples
213 include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which
214 specifies a negative argument with no particular value.
216 @sp 2
217 @need 1000
218 @center @strong{NOTE}
220 @quotation
221 The prefix @kbd{C-u} or @kbd{M-} is not necessary in mh-e's MH-Folder
222 modes (@pxref{Reading Mail Tour}).  In these modes, simply enter the
223 numerical argument before entering the command.
224 @end quotation
226 @cindex point
227 @cindex Emacs, point
228 @cindex mark
229 @cindex Emacs, mark
230 @cindex region
231 @cindex Emacs, region
233 There are several other terms that are used in Emacs that you should
234 know.  The @dfn{point} is where the cursor currently is.  You can save
235 your current place in the file by setting a @dfn{mark}.  This operation
236 is useful in several ways.  The mark can be later used when defining a
237 @dfn{region}, which is the text between the point and mark.  Many
238 commands operate on regions, such as those for deleting text or filling
239 paragraphs.  A mark can be set with @kbd{C-@@} (or @kbd{C-SPC}).
241 @cindex minibuffer
242 @cindex Emacs, minibuffer
243 @cindex file completion
244 @cindex Emacs, file completion
246 The @dfn{minibuffer} is the bottom line of the Emacs window, where all
247 prompting and multiple-character input is directed.  If you are prompted
248 for information in the minibuffer, such as a filename, Emacs can help
249 you complete your answer if you type @key{SPC} or @key{TAB}.  A second
250 @key{SPC} or @key{TAB} will list all possibilities at that point.  The
251 minibuffer is also where you enter Emacs function names after typing
252 @kbd{M-x}.  For example, in the first paragraph, I mentioned that you
253 could obtain help with @kbd{C-h t} (@code{help-with-tutorial}).  What
254 this means is that you can get a tutorial by typing either @kbd{C-h t}
255 or @kbd{M-x help-with-tutorial}.  In the latter case, you are prompted
256 for @samp{help-with-tutorial} in the minibuffer after typing @kbd{M-x}.
258 @cindex interrupting
259 @cindex Emacs, interrupting
260 @cindex quitting
261 @cindex Emacs, quitting
263 @i{In case of trouble:} Emacs can be interrupted at any time with
264 @kbd{C-g}.  For example, if you've started a command that requests that
265 you enter something in the minibuffer, but then you change your mind,
266 type @kbd{C-g} and you'll be back where you started.  If you want to
267 exit Emacs entirely, use @kbd{C-x C-c}.
269 @node Getting Started, Sending Mail Tour, Conventions, Tour Through mh-e
270 @section Getting Started
272 Because there are many old versions of mh-e out there, it is important to
273 know which version you have.  I'll be talking about @w{Version 5} which
274 is similar to @w{Version 4} and vastly different from @w{Version 3}.
276 First, enter @kbd{M-x load-library @key{RET} mh-e
277 @key{RET}}. @footnote{You wouldn't ordinarily do this.}  The message,
278 @samp{Loading mh-e...done}, should be displayed in the minibuffer.  If
279 you get @samp{Cannot open load file: mh-e}, then your Emacs is very
280 badly configured, or mh-e is missing.  You may wish to have your system
281 administrator install a new Emacs or at least the latest mh-e files.
283 Having loaded mh-e successfully, enter @kbd{M-x mh-version @key{RET}}.
284 The version of mh-e should be displayed.  Hopefully it says that you're
285 running @w{Version @value{VERSION}} which is the latest version as of
286 this printing.  If instead Emacs beeps and says @samp{[No match]}, then
287 you're running an old version of mh-e.
289 If these tests reveal a non-existent or old version of mh-e, please
290 consider obtaining a new version.  You can have your system
291 administrator upgrade the system-wide version, or you can install your
292 own personal version.  It's really quite easy; instructions for getting
293 and installing mh-e are in @ref{Getting mh-e}.
295 @cindex @code{install-mh}
296 @cindex MH commands, @code{install-mh}
298 Also, older versions of mh-e assumed that you had already set up your MH
299 environment.  Newer versions set up a new MH environment for you by
300 running @code{install-mh} and notifying you of this fact with the
301 message in a temporary buffer:
303 @example
304 I'm going to create the standard MH path for you.
305 @end example
307 Therefore, if you've never run MH before and you're using an old version
308 of mh-e, you need to run @code{install-mh} from the shell before you
309 continue the tour.  If you don't, you'll be greeted with the error
310 message: @samp{Can't find MH profile}.
312 @cindex @file{.emacs}
313 @cindex files, @file{.emacs}
315 If, during the tour described in this chapter, you see a message like:
316 @samp{Searching for program: no such file or directory,
317 /usr/local/bin/mhpath}, it means that the MH programs and files are kept
318 in a nonstandard directory.  In this case, simply add the following to
319 @file{~/.emacs} and restart @code{emacs}.
321 @vindex @code{mh-progs}, example
322 @vindex @code{mh-lib}, example
324 @c XXX Real example for really naive user?
325 @example
326 @group
327 (setq mh-progs "@var{/path/to/MH/binary/directory/}")
328 (setq mh-lib "@var{/path/to/MH/library/directory/}")
329 @end group
330 @end example
332 @cindex ~
334 The @samp{~} notation used by @file{~/.emacs} above represents your home
335 directory.  This is used by the @code{bash} and @code{csh} shells.  If
336 your shell does not support this feature, you could use the environment
337 variable @samp{$HOME} (such as @file{$HOME/.emacs}) or the absolute path
338 (as in @file{/home/wohler/.emacs}) instead.
340 At this point, you should see something like the screen in the
341 figure in @ref{Reading Mail Tour}.  We're now ready to move on.
343 @node Sending Mail Tour, Reading Mail Tour, Getting Started, Tour Through mh-e
344 @section Sending Mail
346 @cindex sending mail
347 @findex @code{mh-smail}
349 Let's start our tour by sending ourselves a message which we can later
350 read and process.  Enter @kbd{M-x mh-smail} to invoke the mh-e program
351 to send messages.  You will be prompted in the minibuffer by @samp{To:}.
352 Enter your login name.  The next prompt is @samp{cc:}.  Hit @key{RET} to
353 indicate that no carbon copies are to be sent.  At the @samp{Subject:}
354 prompt, enter @kbd{Test} or anything else that comes to mind.
356 @cindex MH-Letter mode
357 @cindex modes, MH-Letter
358 @cindex mode
360 Once you've specified the recipients and subject, your message appears
361 in an Emacs buffer whose mode @footnote{A @dfn{mode} changes Emacs to
362 make it easier to edit a particular type of text.} is MH-Letter.
363 Enter some text in the body of the message, using normal Emacs commands.
364 You should now have something like this: @footnote{If you're running Emacs
365 under the X Window System, then you would also see a menubar.  I've left
366 out the menubar in all of the example screens.}
368 @example
369 @group
370 @cartouche
377 -----Emacs: *scratch*         (Lisp Interaction)--All-------------------
378 To: wohler
380 Subject: Test
381 --------
382   This is a test message to get the wheels churning...#
385 --**-@{draft@}      (MH-Letter)--All-------------------------------------
387 @end cartouche
388 @i{mh-e message composition window}
389 @end group
390 @end example
392 @cindex MH-Letter mode
393 @cindex modes, MH-Letter
395 Note the line of dashes that separates the header and the body of the
396 message.  It is essential that these dashes (or a blank line) are
397 present or the body of your message will be considered to be part of
398 the header.
400 There are several commands specific to MH-Letter mode, but at
401 this time we'll only use @kbd{C-c C-c} to send your message.  Type
402 @kbd{C-c C-c} now.  That's all there is to it!
404 @node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through mh-e
405 @section Receiving Mail
407 @cindex reading mail
408 @findex @code{mh-rmail}
409 @cindex @code{inc}
410 @cindex MH commands, @code{inc}
411 @cindex @code{scan}
412 @cindex MH commands, @code{scan}
413 @cindex MH-Folder mode
414 @cindex modes, MH-Folder
416 To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}.
417 This incorporates the new mail and put the output from @code{inc}
418 (called @dfn{scan lines} after the MH program @code{scan} which prints a
419 one-line summary of each message) into a buffer called @samp{+inbox}
420 whose major mode is MH-Folder.
422 @sp 2
423 @need 1000
424 @center @strong{NOTE}
426 @quotation
427 The @kbd{M-x mh-rmail} command will show you only new mail, not old
428 mail.  If you were to run this tour again, you would use @kbd{M-r} to
429 pull all your messages into mh-e.
430 @end quotation
432 You should see the scan line for your message, and perhaps others.  Use
433 @kbd{n} or @kbd{p} to move the cursor to your test message and type
434 @key{RET} to read your message.  You should see something like:
436 @example
437 @group
438 @cartouche
439   3  24Aug root      received fax files on Wed Aug 24 11:00:13 PDT 1994
440 # 4+ 24Aug To:wohler Test<<This is a test message to get the wheels chu
442 --%%-@{+inbox@} 4 msgs (1-4)      (MH-Folder Show)--Bot------------------
443 To: wohler
444 Subject: Test
445 Date: Wed, 24 Aug 1994 13:01:13 -0700
446 From: Bill Wohler <wohler@@newt.com>
448   This is a test message to get the wheels churning...
454 -----@{show-+inbox@} 4      (MH-Show)--Bot-------------------------------
456 @end cartouche
457 @i{After incorporating new messages}
458 @end group
459 @end example
461 If you typed a long message, you can view subsequent pages with @key{SPC}
462 and previous pages with @key{DEL}.
464 @node Processing Mail Tour, Leaving mh-e, Reading Mail Tour, Tour Through mh-e
465 @section Processing Mail
467 @cindex processing mail
469 The first thing we want to do is reply to the message that we sent
470 ourselves.  Ensure that the cursor is still on the same line as your
471 test message and type @kbd{r}.  You are prompted in the minibuffer with
472 @samp{Reply to whom:}.  Here mh-e is asking whether you'd like to reply
473 to the original sender only, to the sender and primary recipients, or to
474 the sender and all recipients.  If you simply hit @key{RET}, you'll
475 reply only to the sender.  Hit @key{RET} now.
477 You'll find yourself in an Emacs buffer similar to that when you were
478 sending the original message, like this:
480 @example
481 @group
482 @cartouche
483 To: wohler
484 Subject: Re: Test
485 In-reply-to: Bill Wohler's message of Wed, 24 Aug 1994 13:01:13 -0700
486              <199408242001.NAA00505@@newt.com>
487 --------
490 --**-@{draft@}      (MH-Letter)--All-------------------------------------
491 To: wohler
492 Subject: Test
493 Date: Wed, 24 Aug 1994 13:01:13 -0700
494 From: Bill Wohler <wohler@@newt.com>
496   This is a test message to get the wheels churning...
498 -----@{show-+inbox@} 4      (MH-Show)--Bot-------------------------------
499 Composing a reply...done
500 @end cartouche
501 @i{Composition window during reply}
502 @end group
503 @end example
505 By default, MH will not add you to the address list of your replies, so
506 if you find that the @samp{To:} header field is missing, don't worry.
507 In this case, type @kbd{C-c C-f C-t} to create and go to the @samp{To:}
508 field, where you can type your login name again.  You can move around
509 with the arrow keys or with @kbd{C-p} (@code{previous-line}), @kbd{C-n}
510 (@code{next-line}), @kbd{C-b} (@code{backward-char}), and @kbd{C-f}
511 (@code{forward-char}) and can delete the previous character with
512 @key{BS}.  When you're finished editing your message, send it with
513 @kbd{C-c C-c} as before.
515 @cindex folder
517 You'll often want to save messages that were sent to you in an organized
518 fashion.  This is done with @dfn{folders}.  You can use folders to keep
519 messages from your friends, or messages related to a particular topic.
520 With your cursor in the MH-Folder buffer and positioned on the message
521 you sent to yourself, type @kbd{o} to output (@code{refile} in MH
522 parlance) that message to a folder.  Enter @kbd{test} at the
523 @samp{Destination:} prompt and type @kbd{y} (or @key{SPC}) when mh-e
524 asks to create the folder @samp{+test}.  Note that a @samp{^} (caret)
525 appears next to the message number, which means that the message has
526 been marked for refiling but has not yet been refiled.  We'll talk about
527 how the refile is actually carried out in a moment.
529 @cindex MH-Folder mode
530 @cindex modes, MH-Folder
532 Your previous reply is now waiting in the system mailbox.  You
533 incorporate this mail into your MH-Folder buffer named @samp{+inbox}
534 with the @kbd{i} command.  Do this now.  After the mail is incorporated,
535 use @kbd{n} or @kbd{p} to move the cursor to the new message, and read
536 it with @key{RET}.  Let's delete this message by typing @kbd{d}.  Note
537 that a @samp{D} appears next to the message number.  This means that the
538 message is marked for deletion but is not yet deleted.  To perform the
539 deletion (and the refile we did previously), use the @kbd{x} command.
541 @findex @code{mh-smail}
543 If you want to send another message you can use @kbd{m} instead of
544 @kbd{M-x mh-smail}.  So go ahead, send some mail to your friends!
546 @node Leaving mh-e, More About mh-e, Processing Mail Tour, Tour Through mh-e
547 @section Leaving mh-e
549 @cindex Emacs, quitting
550 @cindex quitting
552 You may now wish to exit @code{emacs} entirely.  Use @kbd{C-x C-c} to
553 exit @code{emacs}.  If you exited without running @kbd{x} in the
554 @samp{+inbox} buffer, Emacs will offer to save it for you.  Type @kbd{y}
555 or @key{SPC} to save @samp{+inbox} changes, which means to perform any refiles
556 and deletes that you did there.
558 If you don't want to leave Emacs, you can type @kbd{q} to bury (hide)
559 the mh-e folder or delete them entirely with @kbd{C-x k}.  You can then
560 later recall them with @kbd{C-x b} or @kbd{M-x mh-rmail}.
562 @node More About mh-e,  , Leaving mh-e, Tour Through mh-e
563 @section More About mh-e
565 These are the basic commands to get you going, but there are plenty
566 more.  If you think that mh-e is for you, read @ref{Using mh-e} and
567 @ref{Customizing mh-e} to find out how you can:
569 @itemize @bullet
570 @item
571 Print your messages.  (@ref{Printing} and @ref{Customizing Printing}.)
572 @item
573 Edit messages and include your signature.  (@ref{Draft Editing}
574 and @ref{Customizing Draft Editing}.)
575 @item
576 Forward messages.  (@ref{Forwarding} and @ref{Customizing Forwarding}.)
577 @item
578 Read digests.  (@ref{Viewing}.)
579 @item
580 Edit bounced messages.  (@ref{Old Drafts} and @ref{Customizing Old Drafts}.)
581 @item
582 Send multimedia messages.  (@ref{Editing MIME} and @ref{Customizing Editing MIME}.)
583 @item
584 Process mail that was sent with @code{shar} or @code{uuencode}.
585 (@ref{Files and Pipes}.)
586 @item
587 Use sequences conveniently.  (@ref{Sequences}.)
588 @item
589 Show header fields in different fonts.  (@ref{Customizing Viewing}.)
590 @item
591 Find previously refiled messages.  (@ref{Searching}.)
592 @item
593 Place messages in a file.  (@ref{Files and Pipes}.)
594 @end itemize
596 Remember that you can also use MH commands when you're not running mh-e
597 (and when you are!).
599 @node    Using mh-e, Customizing mh-e, Tour Through mh-e, Top
600 @chapter Using mh-e
602 This chapter leaves the tutorial style and goes into more detail about
603 every mh-e command.  The default, or "out of the box," behavior is
604 documented.  If this is not to your liking (for instance, you print with
605 something other than @code{lpr)}, see the associated section in
606 @ref{Customizing mh-e} which is organized exactly like this chapter.
608 @cindex Emacs, functions; describe-mode
609 @cindex Emacs, online help
610 @cindex online help
612 There are many commands, but don't get intimidated.  There are command
613 summaries at the beginning of each section.  In case you have or would
614 like to rebind the keys, the command summaries also list the associated
615 Emacs Lisp function.  Furthermore, even if you're stranded on a desert
616 island with a laptop and are without your manuals, you can get a summary
617 of all these commands with GNU Emacs online help: use @kbd{C-h m}
618 (@code{describe-mode}) for a brief summary of commands or @kbd{C-h i} to
619 read this manual via Info.  The online help is quite good; try running
620 @kbd{C-h C-h C-h}.  This brings up a list of available help topics, one
621 of which displays the documentation for a given key (like @kbd{C-h k
622 C-n}).  In addition, review @ref{Conventions}, if any of the GNU Emacs
623 conventions are strange to you.
625 Let's get started!
627 @menu
628 * Reading Mail::
629 * Sending Mail::
630 * Draft Editing::
631 * Moving Mail::
632 * Searching::
633 * Sequences::
634 * Miscellaneous::
635 @end menu
637 @node Reading Mail, Sending Mail, Using mh-e, Using mh-e
638 @section Reading Your Mail
640 @cindex reading mail
641 @findex @code{mh-rmail}
642 @cindex MH-Folder mode
643 @cindex modes, MH-Folder
645 The mh-e entry point for reading mail is @kbd{M-x mh-rmail}.  This
646 command incorporates your mail and creates a buffer called @samp{+inbox}
647 in MH-Folder mode.  The @kbd{M-x mh-rmail} command shows you only new
648 mail, not old mail. @footnote{If you want to see your old mail as well,
649 use @kbd{M-r} to pull all your messages into mh-e.  Or, give a prefix
650 argument to @code{mh-rmail} so it will prompt you for folder to visit
651 like @kbd{M-f} (for example, @kbd{C-u M-x mh-rmail @key{RET} bob
652 @key{RET}}).  Both @kbd{M-r} and @kbd{M-f} are described in
653 @ref{Organizing}.}  The @samp{+inbox} buffer contains @dfn{scan lines},
654 which are one-line summaries of each incorporated message.  You can
655 perform most MH commands on these messages via one-letter commands
656 discussed in this chapter.  See @code{scan}(1) for a description of the
657 contents of the scan lines, and see the Figure in @ref{Reading Mail
658 Tour}, for an example.
660 @table @kbd
661 @item RET
662 Display a message (@code{mh-show}).
664 @item SPC
665 Go to next page in message (@code{mh-page-msg}).
667 @item BS
668 Go to previous page in message (@code{mh-previous-page}).
670 @item , (comma)
671 Display a message with all header fields (@code{mh-header-display}).
673 @item M-SPC
674 Go to next message in digest (@code{mh-page-digest}).
676 @item M-BS
677 Go to previous message in digest (@code{mh-page-digest-backwards}).
679 @item M-b
680 Break up digest into separate messages (@code{mh-burst-digest}).
682 @item n
683 Display next message (@code{mh-next-undeleted-msg}).
685 @item p
686 Display previous message (@code{mh-previous-undeleted-msg}).
688 @item g
689 Go to a message (@code{mh-goto-msg}).
691 @item M-<
692 Go to first message (@code{mh-first-msg}).
694 @item M->
695 Go to last message (@code{mh-last-msg}).
697 @item t
698 Toggle between MH-Folder and MH-Folder Show modes (@code{mh-toggle-showing}).
699 @end table
701 @menu
702 * Viewing::
703 * Moving Around::
704 @end menu
706 @node Viewing, Moving Around, Reading Mail, Reading Mail
707 @subsection Viewing Your Mail
709 @findex @code{mh-show}
710 @findex @code{mh-page-msg}
711 @findex @code{mh-previous-page}
712 @findex @code{mh-header-display}
714 The @kbd{RET} (@code{mh-show}) command displays the message that the
715 cursor is on.  If the message is already displayed, it scrolls to the
716 beginning of the message.  Use @key{SPC} (@code{mh-page-msg}) and
717 @key{BS} (@code{mh-previous-page}) to move forwards and backwards one
718 page at a time through the message.  You can give either of these
719 commands a prefix argument that specifies the number of lines to scroll
720 (such as @kbd{10 SPC}).  mh-e normally hides a lot of the
721 superfluous header fields that mailers add to a message, but if you wish
722 to see all of them, use the @kbd{,} (comma; @code{mh-header-display})
723 command.
725 @menu
726 * Reading Digests::
727 * Reading MIME::
728 @end menu
730 @node Reading Digests, Reading MIME, Viewing, Viewing
731 @subsubsection Reading Digests
733 @cindex digests
734 @findex @code{mh-page-digest}
735 @findex @code{mh-page-digest-backwards}
737 A digest is a message that contains other messages.  Special mh-e
738 commands let you read digests conveniently.  You can use @key{SPC} and
739 @key{BS} to page through the digest as if it were a normal message, but
740 if you wish to skip to the next message in the digest, use @kbd{M-SPC}
741 (@code{mh-page-digest}).  To return to a previous message, use
742 @kbd{M-BS} (@code{mh-page-digest-backwards}).
744 @cindex @code{burst}
745 @cindex MH commands, @code{burst}
746 @cindex MH-Folder Show mode
747 @cindex modes, MH-Folder Show
748 @findex @code{mh-burst-digest}
750 @c There was a page break at the colon in the following paragraph which
751 @c broke the transition to the example.
752 @need 2000
754 Another handy command is @kbd{M-b} (@code{mh-burst-digest}).  This
755 command uses the MH command @code{burst} to break out each message in
756 the digest into its own message.  Using this command, you can quickly
757 delete unwanted messages, like this: Once the digest is split up, toggle
758 out of MH-Folder Show mode with @kbd{t} (@pxref{Moving Around}) so that
759 the scan lines fill the screen and messages aren't displayed.  Then use
760 @kbd{d} (@pxref{Deleting}) to quickly delete messages that you don't
761 want to read (based on the @samp{Subject:} header field).  You can also
762 burst the digest to reply directly to the people who posted the messages
763 in the digest.  One problem you may encounter is that the @samp{From:}
764 header fields are preceded with a @samp{>} so that your reply can't
765 create the @samp{To:} field correctly.  In this case, you must correct
766 the @samp{To:} field yourself.  This is described later in @ref{Editing
767 Textual}.
769 @node Reading MIME,  , Reading Digests, Viewing
770 @subsubsection Reading Multimedia Mail
772 @cindex multimedia mail
773 @cindex MIME
774 @cindex @code{show}
775 @cindex MH commands, @code{show}
776 @cindex @code{mhshow}
777 @cindex MH commands, @code{mhshow}
779 MH has the ability to read @dfn{@sc{mime}} (Multipurpose Internet Mail
780 Extensions) messages.  Unfortunately, mh-e does not yet have this
781 ability, so you have to use the MH commands @code{show} or @code{mhshow}
782 from the shell to read @sc{mime} messages.  @footnote{You can call them
783 directly from Emacs if you're running the X Window System: type @kbd{M-!
784 xterm -e mhshow @var{message-number}}.  You can leave out the @code{xterm
785 -e} if you use @code{mhlist} or @code{mhstore}.}
787 @node Moving Around,  , Viewing, Reading Mail
788 @subsection Moving Around
790 @cindex moving between messages
791 @findex @code{mh-next-undeleted-msg}
792 @findex @code{mh-previous-undeleted-msg}
793 @findex @code{mh-goto-msg}
794 @findex @code{mh-last-msg}
795 @findex @code{mh-first-msg}
797 To move on to the next message, use the @kbd{n}
798 (@code{mh-next-undeleted-msg}) command; use the @kbd{p}
799 (@code{mh-previous-undeleted-msg}) command to read the previous message.
800 Both of these commands can be given a prefix argument to specify how
801 many messages to skip (for example, @kbd{5 n}).  You can also move to a
802 specific message with @kbd{g} (@code{mh-goto-msg}).  You can enter the
803 message number either before or after typing @kbd{g}.  In the latter
804 case, Emacs prompts you.  Finally, you can go to the first or last
805 message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->}
806 (@code{mh-last-msg}) respectively.
808 @cindex MH-Folder mode
809 @cindex modes, MH-Folder
811 You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) and
812 @kbd{C-n} (@code{next-line}) to move up and down the scan lines in the
813 MH-Folder window.  These commands can be used in conjunction with
814 @kbd{RET} to look at deleted or refiled messages.
816 @cindex MH-Folder mode
817 @cindex modes, MH-Folder
818 @cindex MH-Folder Show mode
819 @cindex modes, MH-Folder Show
820 @cindex junk mail
821 @findex @code{mh-toggle-showing}
823 The command @kbd{t} (@code{mh-toggle-showing}) switches between
824 MH-Folder mode and MH-Folder Show mode.  @footnote{For you Emacs
825 wizards, this is implemented as an Emacs minor mode.} MH-Folder mode
826 turns off the associated show buffer so that you can perform operations
827 on the messages quickly without reading them.  This is an excellent way
828 to prune out your junk mail or to refile a group of messages to another
829 folder for later examination.
831 @node Sending Mail, Draft Editing, Reading Mail, Using mh-e
832 @section Sending Mail
834 @cindex sending mail
835 @findex @code{mh-smail}
837 You can send a mail message in several ways.  You can call @kbd{M-x
838 mh-smail} directly, or from the command line like this:
840 @cindex starting from command line
842 @example
843 % @kbd{emacs -f mh-smail}
844 @end example
846 From within mh-e's MH-Folder mode, other methods of sending mail
847 are available as well:
849 @table @kbd
850 @item m
851 Compose a message (@code{mh-send}).
853 @item r
854 Reply to a message (@code{mh-reply}).
856 @item f
857 Forward message(s) (@code{mh-forward}).
859 @item M-d
860 Redistribute a message (@code{mh-redistribute}).
862 @item M-e
863 Edit a message that was bounced by mailer (@code{mh-extract-rejected-mail}).
865 @item M-a
866 Edit a message to send it again (@code{mh-edit-again}).
867 @end table
869 @cindex MH-Folder mode
870 @cindex modes, MH-Folder
871 @cindex MH-Letter mode
872 @cindex modes, MH-Letter
873 @findex @code{mh-send}
875 From within a MH-Folder buffer, you can simply use the command @kbd{m}
876 (@code{mh-send}).  However you invoke @code{mh-send}, you are prompted
877 for the @samp{To:}, @samp{cc:}, and @samp{Subject:} header fields.  Once
878 you've specified the recipients and subject, your message appears in an
879 Emacs buffer whose mode is MH-Letter (see the Figure in @ref{Sending
880 Mail} to see what the buffer looks like).  MH-Letter mode allows you to
881 edit your message, to check the validity of the recipients, to insert
882 other messages into your message, and to send the message.  We'll go
883 more into depth about editing a @dfn{draft} @footnote{I highly recommend
884 that you use a @dfn{draft folder} so that you can edit several drafts in
885 parallel.  To do so, create a folder (e.g., @file{+drafts}), and add a
886 profile component called @samp{Draft-Folder:} which contains
887 @file{+drafts} (see @code{mh-profile}(5)).} (a message you're composing)
888 in just a moment.
890 @findex @code{mh-smail}
891 @findex @code{mh-smail-other-window}
893 @code{mh-smail} always creates a two-window layout with the current
894 buffer on top and the draft on the bottom.  If you would rather preserve
895 the window layout, use @kbd{M-x mh-smail-other-window}.
897 @menu
898 * Replying::
899 * Forwarding::
900 * Redistributing::
901 * Old Drafts::
902 @end menu
904 @node Replying, Forwarding, Sending Mail, Sending Mail
905 @subsection Replying to Mail
907 @cindex replying
908 @cindex @code{mhl}
909 @cindex MH commands, @code{mhl}
910 @cindex @file{mhl.reply}
911 @cindex files, @file{mhl.reply}
912 @findex @code{mh-reply}
914 To compose a reply to a message, use the @kbd{r} (@code{mh-reply})
915 command.  If you supply a prefix argument (as in @kbd{C-u r}), the
916 message you are replying to is inserted in your reply after having first
917 been run through @code{mhl} with the format file @file{mhl.reply}.  See
918 @code{mhl}(1) to see how you can modify the default @file{mhl.reply}
919 file.
921 When you reply to a message, you are first prompted with @samp{Reply to
922 whom?}.  You have several choices here.
924 @example
925 @group
926 @b{Response}     @b{Reply Goes To}
928 @kbd{from}         @r{The person who sent the message.  This is the default,}
929              @r{so @key{RET} is sufficient.}
931 @kbd{to}           @r{Replies to the sender, plus all recipients in the}
932              @r{@samp{To:} header field.}
934 @kbd{all}
935 @kbd{cc}           @r{Forms a reply to the sender, plus all recipients.}
936 @end group
937 @end example
939 @cindex @code{repl}
940 @cindex MH commands, @code{repl}
942 Depending on your answer, @code{repl} is given a different argument to
943 form your reply.  Specifically, a choice of @kbd{from} or none at all
944 runs @code{repl -nocc all}, and a choice of @kbd{to} runs @code{repl -cc
945 to}.  Finally, either @kbd{cc} or @kbd{all} runs @code{repl -cc all
946 -nocc me}.
948 @cindex MH-Letter mode
949 @cindex modes, MH-Letter
951 Two windows are then created.  One window contains the message to which
952 you are replying.  Your draft, in MH-Letter mode (described in
953 @ref{Draft Editing}), is in the other window.
955 If you wish to customize the header or other parts of the reply draft,
956 please see @code{repl}(1) and @code{mh-format}(5).
958 @node Forwarding, Redistributing, Replying, Sending Mail
959 @subsection Forwarding Mail
961 @cindex forwarding
962 @cindex @code{forw}
963 @cindex MH commands, @code{forw}
964 @findex @code{mh-forward}
966 To forward a message, use the @kbd{f} (@code{mh-forward}) command.  You
967 are given a draft to edit that looks like it would if you had run the MH
968 command @code{forw}.  You are given a chance to add some text (see
969 @ref{Draft Editing}).
971 You can forward several messages by using a prefix argument; in this
972 case, you are prompted for the name of a @dfn{sequence}, a symbolic name
973 that represents a list or range of message numbers (for example,
974 @kbd{C-u f forbob @key{RET}}).  All of the messages in the sequence are
975 inserted into your draft.  By the way, although sequences are often
976 mentioned in this chapter, you don't have to worry about them for now;
977 the full description of sequences in mh-e is at the end in
978 @ref{Sequences}.  To learn more about sequences in general, please see
979 @code{mh-sequence}(5).
981 @node Redistributing, Old Drafts, Forwarding, Sending Mail
982 @subsection Redistributing Your Mail
984 @cindex redistributing
985 @findex @code{mh-redistribute}
987 The command @kbd{M-d} (@code{mh-redistribute}) is similar in function to
988 forwarding mail, but it does not allow you to edit the message, nor does
989 it add your name to the @samp{From:} header field.  It appears to the
990 recipient as if the message had come from the original sender.  For more
991 information on redistributing messages, see @code{dist}(1).  Also
992 investigate the @kbd{M-a} (@code{mh-edit-again}) command in @ref{Old
993 Drafts}, for another way to redistribute messages.
995 @node Old Drafts,  , Redistributing, Sending Mail
996 @subsection Editing Old Drafts and Bounced Messages
998 @cindex re-editing drafts
999 @cindex @file{draft}
1000 @cindex files, @file{draft}
1001 @findex @code{mh-edit-again}
1003 If you don't complete a draft for one reason or another, and if the
1004 draft buffer is no longer available, you can pick your draft up again
1005 with @kbd{M-a} (@code{mh-edit-again}).  If you don't use a draft folder,
1006 your last @file{draft} file will be used.  If you use draft folders,
1007 you'll need to visit the draft folder with @kbd{M-f drafts @key{RET}},
1008 use @kbd{n} to move to the appropriate message, and then use @kbd{M-a}
1009 to prepare the message for editing.
1011 The @kbd{M-a} command can also be used to take messages that were sent
1012 to you and to send them to more people.
1014 @cindex Mailer-Daemon
1015 @findex @code{mh-extract-rejected-mail}
1017 Don't use @kbd{M-a} to re-edit a message from a @i{Mailer-Daemon} who
1018 complained that your mail wasn't posted for some reason or another.  In
1019 this case, use @kbd{M-e} (@code{mh-extract-rejected-mail}) to prepare
1020 the message for editing by removing the @i{Mailer-Daemon} envelope and
1021 unneeded header fields.  Fix whatever addressing problem you had, and
1022 send the message again with @kbd{C-c C-c}.
1024 @node Draft Editing, Moving Mail, Sending Mail, Using mh-e
1025 @section Editing a Draft
1027 @cindex editing draft
1028 @cindex MH-Letter mode
1029 @cindex modes, MH-Letter
1031 When you edit a message that you want to send (called a @dfn{draft} in
1032 this case), the mode used is MH-Letter.  This mode provides
1033 several commands in addition to the normal Emacs editing commands to
1034 help you edit your draft.
1036 @table @kbd
1037 @item C-c C-y
1038 Insert contents of message to which you're replying (@code{mh-yank-cur-msg}).
1040 @item C-c C-i
1041 Insert a message from a folder (@code{mh-insert-letter}).
1043 @item C-c C-f C-t
1044 Move to @samp{To:} header field (@code{mh-to-field}).
1046 @item C-c C-f C-c
1047 Move to @samp{cc:} header field (@code{mh-to-field}).
1049 @item C-c C-f C-s
1050 Move to @samp{Subject:} header field (@code{mh-to-field}).
1052 @item C-c C-f C-f
1053 Move to @samp{From:} header field (@code{mh-to-field}).
1055 @item C-c C-f C-b
1056 Move to @samp{Bcc:} header field (@code{mh-to-field}).
1058 @item C-c C-f C-f
1059 Move to @samp{Fcc:} header field (@code{mh-to-fcc}).
1061 @item C-c C-f C-d
1062 Move to @samp{Dcc:} header field (@code{mh-to-field}).
1064 @item C-c C-w
1065 Display expanded recipient list (@code{mh-check-whom}).
1067 @item C-c C-s
1068 Insert signature in message (@code{mh-insert-signature}).
1070 @item C-c C-m C-f
1071 Include forwarded message (@sc{mime}) (@code{mh-mhn-compose-forw}).
1073 @item C-c C-m C-e
1074 Include anonymous ftp reference (@sc{mime}) (@code{mh-mhn-compose-anon-ftp}).
1076 @item C-c C-m C-t
1077 Include anonymous ftp reference to compressed tar file (@sc{mime})
1078 (@code{mh-mhn-compose-external-compressed-tar}).
1080 @item C-c C-m C-i
1081 Include binary, image, sound, etc. (@sc{mime})
1082 (@code{mh-mhn-compose-insertion}).
1084 @item C-c C-e
1085 Run through @code{mhn} before sending (@code{mh-edit-mhn}).
1087 @item C-c C-m C-u
1088 Undo effects of @code{mhn} (@code{mh-revert-mhn-edit}).
1090 @item C-c C-c
1091 Save draft and send message (@code{mh-send-letter}).
1093 @item C-c C-q
1094 Quit editing and delete draft message (@code{mh-fully-kill-draft}).
1095 @end table
1097 @menu
1098 * Editing Textual::
1099 * Editing MIME::
1100 * Sending Message::
1101 * Killing Draft::
1102 @end menu
1104 @node Editing Textual, Editing MIME, Draft Editing, Draft Editing
1105 @subsection Editing Textual Messages
1107 The following sections show you how to edit a draft.
1108 The commands described here are also applicable to messages that have
1109 multimedia components.
1111 @menu
1112 * Inserting Letter::
1113 * Inserting Messages::
1114 * Header::
1115 * Recipients::
1116 * Signature::
1117 @end menu
1119 @node Inserting Letter, Inserting Messages, Editing Textual, Editing Textual
1120 @subsubsection Inserting letter to which you're replying
1122 @cindex inserting messages
1123 @findex @code{mh-yank-cur-msg}
1125 It is often useful to insert a snippet of text from a letter that
1126 someone mailed to provide some context for your reply.  The command
1127 @kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by yanking a portion of
1128 text from the message to which you're replying and inserting @samp{> }
1129 before each line.
1131 @cindex mark
1132 @cindex Emacs, mark
1133 @cindex point
1134 @cindex Emacs, point
1135 @cindex region
1136 @cindex Emacs, region
1138 You can control how much text is included when you run this command.  If
1139 you run this command right away, without entering the buffer containing
1140 the message to you, this command will yank the entire message, as is,
1141 into your reply. @footnote{If you'd rather have the header cleaned up,
1142 use @kbd{C-u r} instead of @kbd{r} when replying (see @ref{Replying}).}
1143 If you enter the buffer containing the message sent to you and move the
1144 cursor to a certain point and return to your reply and run @kbd{C-c
1145 C-y}, then the text yanked will range from that point to the end of the
1146 message.  Finally, the most common action you'll perform is to enter the
1147 message sent to you, move the cursor to the beginning of a paragraph or
1148 phrase, set the @dfn{mark} with @kbd{C-SPC} or @kbd{C-@@}, and move the
1149 cursor to the end of the paragraph or phrase.  The cursor position is
1150 called the @dfn{point}, and the space between the mark and point is
1151 called the @dfn{region}.  Having done that, @kbd{C-c C-y} will insert
1152 the region you selected.
1154 @node Inserting Messages, Header, Inserting Letter, Editing Textual
1155 @subsubsection Inserting messages
1157 @cindex inserting messages
1158 @findex @code{mh-insert-letter}
1160 Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}).
1161 This command prompts you for the folder and message number and inserts
1162 the message, indented by @samp{> }.  Certain undesirable header fields
1163 are removed before insertion.  If given a prefix argument (like @kbd{C-u
1164 C-c C-i}), the header is left intact, the message is not indented, and
1165 @samp{> } is not inserted before each line.
1167 @node Header, Recipients, Inserting Messages, Editing Textual
1168 @subsubsection Editing the header
1170 @cindex editing header
1171 @findex @code{mh-to-field}
1173 Because the header is part of the message, you can edit the header
1174 fields as you wish.  However, several convenience functions exist to
1175 help you create and edit them.  For example, the command @kbd{C-c C-f
1176 C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the
1177 cursor to the @samp{To:} header field, creating it if necessary.  The
1178 functions to move to the @samp{cc:}, @samp{Subject:}, @samp{From:},
1179 @samp{Bcc:}, and @samp{Dcc:} header fields are similar.
1181 @findex @code{mh-to-fcc}
1183 One function behaves differently from the others, namely, @kbd{C-c C-f
1184 C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}).  This function
1185 will prompt you for the folder name in which to file a copy of the draft.
1187 Be sure to leave a row of dashes or a blank line between the header and
1188 the body of the message.
1190 @node Recipients, Signature, Header, Editing Textual
1191 @subsubsection Checking recipients
1193 @cindex checking recipients
1194 @cindex @code{whom}
1195 @cindex MH commands, @code{whom}
1196 @findex @code{mh-check-whom}
1198 The @kbd{C-c C-w} (@code{mh-check-whom}) command expands aliases so you
1199 can check the actual address(es) in the alias.  A new buffer is created
1200 with the output of @code{whom}.
1202 @node Signature,  , Recipients, Editing Textual
1203 @subsubsection Inserting your signature
1205 @cindex inserting signature
1206 @cindex signature
1207 @cindex @file{.signature}
1208 @cindex files, @file{.signature}
1209 @findex @code{mh-insert-signature}
1211 You can insert your signature at the current cursor location with the
1212 @kbd{C-c C-s} (@code{mh-insert-signature}) command.  The text of your
1213 signature is taken from the file @file{~/.signature}.
1215 @node Editing MIME, Sending Message, Editing Textual, Draft Editing
1216 @subsection Editing Multimedia Messages
1218 @cindex MIME
1219 @cindex multimedia mail
1220 @cindex @code{mhn}
1221 @cindex MH commands, @code{mhn}
1223 mh-e has the capability to create multimedia messages.  It uses the
1224 @sc{mime} (Multipurpose Internet Mail Extensions) protocol.  The
1225 @sc{mime} protocol allows you to incorporate images, sound, video,
1226 binary files, and even commands that fetch a file with @samp{ftp} when
1227 your recipient reads the message!  If you were to create a multimedia
1228 message with plain MH commands, you would use @code{mhn}.  Indeed, the
1229 mh-e @sc{mime} commands merely insert @code{mhn} directives which are
1230 later expanded by @code{mhn}.
1232 Each of the mh-e commands for editing multimedia messages or for
1233 incorporating multimedia objects is prefixed with @kbd{C-c C-m} .
1235 @cindex content types
1236 @cindex MIME, content types
1238 Several @sc{mime} objects are defined.  They are called @dfn{content
1239 types}.  The table in @ref{Customizing Draft Editing} contains a list of
1240 the content types that mh-e currently knows about.  Several of the mh-e
1241 commands fill in the content type for you, whereas others require you to
1242 enter one.  Most of the time, it should be obvious which one to use
1243 (e.g., use @kbd{image/jpeg} to include a @sc{jpeg} image).  If not, you
1244 can refer to @sc{rfc} 1521,
1245 @c Footnotes are very fragile.  Hence the duplication.
1246 @c The line break in the footnote was necessary since TeX wasn't creating one.
1247 @ifclear html
1248 @footnote{This @sc{rfc} (Request For Comments) is
1249 available via the @sc{url} @*
1250 @file{ftp://ds.internic.net/rfc/rfc1521.txt}.}
1251 @end ifclear
1252 @ifset html
1253 @footnote{This @sc{rfc} (Request For Comments) is
1254 available via the @sc{url} @*
1255 @file{<A HREF="ftp://ds.internic.net/rfc/rfc1521.txt">ftp://ds.internic.net/rfc/rfc1521.txt</A>}.}
1256 @end ifset
1257 which defines the @sc{mime} protocol, for a list of valid content types.
1259 @cindex content description
1260 @cindex MIME, content description
1262 You are also sometimes asked for a @dfn{content description}.  This is
1263 simply an optional brief phrase, in your own words, that describes the
1264 object.  If you don't care to enter a content description, just press
1265 return and none will be included; however, a reader may skip over
1266 multimedia fields unless the content description is compelling.
1268 Remember: you can always add @code{mhn} directives by hand.
1270 @menu
1271 * Forwarding MIME::
1272 * FTP::
1273 * Tar::
1274 * Other MIME Objects::
1275 * Sending MIME::
1276 @end menu
1278 @node Forwarding MIME, FTP, Editing MIME, Editing MIME
1279 @subsubsection Forwarding multimedia messages
1281 @findex @code{mh-mhn-compose-forw}
1283 Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m C-f}
1284 (@code{mh-mhn-compose-forw}).  You are prompted for a content
1285 description, the name of the folder in which the messages to forward are
1286 located, and the messages' numbers.
1288 @node FTP, Tar, Forwarding MIME, Editing MIME
1289 @subsubsection Including an ftp reference
1291 @cindex @code{ftp}
1292 @cindex Unix commands, @code{ftp}
1293 @cindex MIME, @code{ftp}
1294 @findex @code{mh-mhn-compose-anon-ftp}
1296 You can even have your message initiate an @code{ftp} transfer when the
1297 recipient reads the message.  To do this, use the @kbd{C-c C-m C-e}
1298 (@code{mh-mhn-compose-anon-ftp}) command.  You are prompted for the
1299 remote host and pathname, the content type, and the content description.
1301 @node Tar, Other MIME Objects, FTP, Editing MIME
1302 @subsubsection Including tar files
1304 @cindex @code{tar}
1305 @cindex Unix commands, @code{tar}
1306 @cindex MIME, @code{tar}
1307 @cindex @code{ftp}
1308 @cindex Unix commands, @code{ftp}
1309 @cindex MIME, @code{ftp}
1310 @findex @code{mh-mhn-compose-external-compressed-tar}
1312 If the remote file (@pxref{FTP}) is a compressed tar file, you can use
1313 @kbd{C-c C-m C-t} (@code{mh-mhn-compose-external-compressed-tar}).
1314 Then, in addition to retrieving the file via anonymous @emph{ftp}, the
1315 file will also be uncompressed and untarred.  You are prompted for the
1316 remote host and pathname and the content description.  The pathname
1317 should contain at least one @samp{/} (slash), because the pathname is
1318 broken up into directory and name components.
1320 @node Other MIME Objects, Sending MIME, Tar, Editing MIME
1321 @subsubsection Including other multimedia objects
1323 @cindex images
1324 @cindex MIME, images
1325 @cindex sound
1326 @cindex MIME, sound
1327 @cindex video
1328 @cindex MIME, video
1329 @findex @code{mh-mhn-compose-insertion}
1331 Images, sound, and video can be inserted in your message with the
1332 @kbd{C-c C-m C-i} (@code{mh-mhn-compose-insertion}) command.  You are
1333 prompted for the filename containing the object, the content type, and a
1334 content description of the object.
1336 @node Sending MIME,  , Other MIME Objects, Editing MIME
1337 @subsubsection Readying multimedia messages for sending
1339 When you are finished editing a @sc{mime} message, it might look like this:
1341 @example
1342 @group
1343 @cartouche
1344    3  24Aug  root               received fax files on Wed Aug 24 11:00:13
1345    4+ 24Aug  To:wohler          Test<<This is a test message to get the wh
1351 --%%-@{+inbox@} 4 msgs (1-4)      (MH-Folder Show)--Bot-------------------
1352 To: wohler
1354 Subject: Test of MIME
1355 --------
1356 #@@application/octet-stream [Nonexistent ftp test file] \
1357 access-type=anon-ftp; site=berzerk.com; name=panacea.tar.gz; \
1358 directory="/pub/"
1359 #audio/basic [Test sound bite] /tmp/noise.au
1360 --**-@{draft@}      (MH-Letter)--All--------------------------------------
1362 @end cartouche
1363 @i{mh-e @sc{mime} draft}
1364 @end group
1365 @end example
1367 @cindex @code{mhn}
1368 @cindex MH commands, @code{mhn}
1369 @findex @code{mh-edit-mhn}
1371 The lines added by the previous commands are @code{mhn} directives and
1372 need to be converted to @sc{mime} directives before sending.  This is
1373 accomplished by the command @kbd{C-c C-e} (@code{mh-edit-mhn}), which
1374 runs @code{mhn} on the message.  The following screen shows what those
1375 commands look like in full @sc{mime} format.  You can see why mail user
1376 agents are usually built to hide these details from the user.
1378 @example
1379 @group
1380 @cartouche
1381 To: wohler
1383 Subject: Test of MIME
1384 MIME-Version: 1.0
1385 Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
1386 Content-ID: <1623.777796162.0@@newt.com>
1388 ------- =_aaaaaaaaaa0
1389 Content-Type: message/external-body; access-type="anon-ftp";
1390         site="berzerk.com"; name="panacea.tar.gz"; directory="/pub/"
1392 Content-Type: application/octet-stream
1393 Content-ID: <1623.777796162.1@@newt.com>
1394 Content-Description: Nonexistent ftp test file
1396 ------- =_aaaaaaaaaa0
1397 Content-Type: audio/basic
1398 Content-ID: <1623.777796162.2@@newt.com>
1399 Content-Description: Test sound bite
1400 Content-Transfer-Encoding: base64
1402 Q3JlYXRpdmUgVm9pY2UgRmlsZRoaAAoBKREBQh8AgwCAgH9/f35+fn59fX5+fn5+f39/f39/f3
1403 f4B/f39/f39/f39/f39/f39+f39+f39/f39/f4B/f39/fn5/f39/f3+Af39/f39/gH9/f39/fn
1404 -----@{draft@}      (MH-Letter)--Top--------------------------------------
1406 @end cartouche
1407 @i{mh-e @sc{mime} draft ready to send}
1408 @end group
1409 @end example
1411 @findex @code{mh-revert-mhn-edit}
1413 This action can be undone by running @kbd{C-c C-m C-u}
1414 (@code{mh-revert-mhn-edit}).  It does this by reverting to a backup
1415 file.  You are prompted to confirm this action, but you can avoid the
1416 confirmation by adding an argument (for example, @kbd{C-u C-c C-m C-u}).
1418 @node Sending Message, Killing Draft, Editing MIME, Draft Editing
1419 @subsection Sending a Message
1421 @cindex sending mail
1422 @findex @code{mh-send-letter}
1424 When you are all through editing a message, you send it with the
1425 @kbd{C-c C-c} (@code{mh-send-letter}) command.  You can give an argument
1426 (as in @kbd{C-u C-c C-c}) to monitor the first stage of the delivery.
1428 @node Killing Draft,  , Sending Message, Draft Editing
1429 @subsection Killing the Draft
1431 @cindex killing draft
1432 @findex @code{mh-fully-kill-draft}
1434 If for some reason you are not happy with the draft, you can kill it
1435 instead with @kbd{C-c C-q} (@code{mh-fully-kill-draft}).  Emacs then
1436 kills the draft buffer and deletes the draft message.
1438 @node Moving Mail, Searching, Draft Editing, Using mh-e
1439 @section Moving Your Mail Around
1441 @cindex processing mail
1443 This section covers how messages and folders can be moved about or
1444 manipulated.  Messages may be incorporated into your @file{+inbox},
1445 deleted, and refiled.  Messages containing @code{shar} or
1446 @code{uuencode} output can be stored.  Folders can be visited, sorted,
1447 packed, or deleted.  Here's a list of the available commands to do these
1448 things:
1450 @c Stephen thinks that ? should be documented here, since it also shows
1451 @c which folders a message will be refiled to. XXX
1453 @table @kbd
1454 @item i
1455 Incorporate new mail into folder (@code{mh-inc-folder}).
1457 @item d
1458 Delete message (@code{mh-delete-msg}).
1460 @item C-d
1461 Delete message, don't move to next message (@code{mh-delete-msg-no-motion}).
1463 @item M-s
1464 Find messages that meet search criteria (@code{mh-search-folder}).
1466 @item o
1467 Output (refile) message to folder (@code{mh-refile-msg}).
1469 @item c
1470 Copy message to folder (@code{mh-copy-msg}).
1472 @item C-o
1473 Output (write) message to file (@code{mh-write-msg-to-file}).
1475 @item !
1476 Repeat last output command (@code{mh-refile-or-write-again}).
1478 @item l
1479 Print message with @code{lpr} (@code{mh-print-msg}).
1481 @item |
1482 Pipe message through shell command (@code{mh-pipe-msg}).
1484 @item M-n
1485 Unpack message created with @code{uudecode} or @code{shar}
1486 (@code{mh-store-msg}).
1488 @item M-l
1489 List all folders (@code{mh-list-folders}).
1491 @item M-f
1492 Visit folder (@code{mh-visit-folder}).
1494 @item M-r
1495 Regenerate scan lines (@code{mh-rescan-folder}).
1497 @item M-x mh-sort-folder
1498 Sort folder.
1500 @item M-p
1501 Pack folder (@code{mh-pack-folder}).
1503 @item M-k
1504 Remove folder (@code{mh-kill-folder}).
1506 @item x
1507 Execute pending refiles and deletes (@code{mh-execute-commands}).
1509 @item u
1510 Undo pending refile or delete (@code{mh-undo}).
1512 @item M-u
1513 Undo all pending refiles and deletes (@code{mh-undo-folder}).
1515 @item q
1516 Quit (@code{mh-quit}).
1517 @end table
1519 @menu
1520 * Incorporating::
1521 * Deleting::
1522 * Organizing::
1523 * Printing::
1524 * Files and Pipes::
1525 * Finishing Up::
1526 @end menu
1528 @node Incorporating, Deleting, Moving Mail, Moving Mail
1529 @subsection Incorporating Your Mail
1531 @cindex incorporating
1532 @findex @code{mh-inc-folder}
1534 If at any time you receive new mail, incorporate the new mail into your
1535 @samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}).  Note that
1536 @kbd{i} will display the @samp{+inbox} buffer, even if there isn't any
1537 new mail.  You can incorporate mail from any file into the current
1538 folder by specifying a prefix argument; you'll be prompted for the name
1539 of the file to use (for example, @kbd{C-u i ~/mbox @key{RET}}).
1541 @cindex Emacs, notification of new mail
1542 @cindex notification of new mail
1543 @cindex new mail
1544 @cindex @file{.emacs}
1545 @cindex files, @file{.emacs}
1547 Emacs can notify you when you have new mail by displaying @samp{Mail} in
1548 the mode line.  To enable this behavior, and to have a clock in the mode
1549 line besides, add the following to @file{~/.emacs}:
1551 @findex @code{display-time}
1553 @lisp
1554 (display-time)
1555 @end lisp
1557 @node Deleting, Organizing, Incorporating, Moving Mail
1558 @subsection Deleting Your Mail
1560 @cindex deleting
1561 @findex @code{mh-delete-msg}
1562 @findex @code{mh-delete-msg-no-motion}
1564 To mark a message for deletion, use the @kbd{d} (@code{mh-delete-msg})
1565 command.  A @samp{D} is placed by the message in the scan window, and
1566 the next message is displayed.  If the previous command had been
1567 @kbd{p}, then the next message displayed is the message previous to the
1568 message just deleted.  If you specify a prefix argument, you will be
1569 prompted for a sequence (@pxref{Sequences}) to delete (for example,
1570 @kbd{C-u d frombob RET}).  The @kbd{x} command actually carries out the
1571 deletion (@pxref{Finishing Up}).  @kbd{C-d}
1572 (@code{mh-delete-msg-no-motion}) marks the message for deletion but
1573 leaves the cursor at the current message in case you wish to perform
1574 other operations on the message.
1576 @node Organizing, Printing, Deleting, Moving Mail
1577 @subsection Organizing Your Mail with Folders
1579 @cindex using folders
1580 @cindex @code{folder}
1581 @cindex MH commands, @code{folder}
1582 @cindex @code{refile}
1583 @cindex MH commands, @code{refile}
1584 @findex @code{mh-refile-msg}
1586 mh-e has analogies for each of the MH @code{folder} and @code{refile}
1587 commands.  To refile a message in another folder, use the @kbd{o}
1588 (@code{mh-refile-msg}) (mnemonic: ``output'') command.  You are prompted
1589 for the folder name.
1591 @findex @code{mh-refile-or-write-again}
1593 If you are refiling several messages into the same folder, you can use
1594 the @kbd{!} (@code{mh-refile-or-write-again}) command to repeat the last
1595 refile or write (see the description of @kbd{C-o} in @ref{Files and
1596 Pipes}).  Or, place the messages into a sequence (@ref{Sequences}) and
1597 specify a prefix argument to @kbd{o}, in which case you'll be prompted
1598 for the name of the sequence (for example, @kbd{C-u o search RET}).
1600 @findex @code{mh-copy-msg}
1602 If you wish to copy a message to another folder, you can use the @kbd{c}
1603 (@code{mh-copy-msg}) command (see the @code{-link} argument to
1604 @code{refile}(1)).  You are prompted for a folder, and you can specify a
1605 prefix argument if you want to copy a sequence into another folder.  In
1606 this case, you are then prompted for the sequence.  Note that unlike the
1607 @kbd{o} command, the copy takes place immediately.  The original copy
1608 remains in the current folder.
1610 @findex @code{mh-visit-folder}
1612 When you want to read the messages that you have refiled into folders,
1613 use the @kbd{M-f} (@code{mh-visit-folder}) command to visit the folder.
1614 You are prompted for the folder name.
1616 @findex @code{mh-list-folders}
1617 @findex @code{mh-kill-folder}
1618 @findex @code{mh-visit-folder}
1619 @findex @code{mh-sort-folder}
1620 @findex @code{mh-pack-folder}
1621 @findex @code{mh-rescan-folder}
1623 Other commands you can perform on folders include: @kbd{M-l}
1624 (@code{mh-list-folders}), to list all the folders in your mail
1625 directory; @kbd{M-k} (@code{mh-kill-folder}), to remove a folder;
1626 @kbd{M-x mh-sort-folder}, to sort the messages by date (see
1627 @code{sortm}(1) to see how to sort by other criteria); @kbd{M-p}
1628 (@code{mh-pack-folder}), to pack a folder, removing gaps from the
1629 numbering sequence; and @kbd{M-r} (@code{mh-rescan-folder}), to rescan
1630 the folder, which is useful to grab all messages in your @file{+inbox}
1631 after processing your new mail for the first time.  If you don't want to
1632 rescan the entire folder, give @kbd{M-r} or @kbd{M-p} a prefix argument
1633 and you'll be prompted for a range of messages to display (for instance,
1634 @kbd{C-u M-r last:50 RET}).
1636 @node Printing, Files and Pipes, Organizing, Moving Mail
1637 @subsection Printing Your Mail
1639 @cindex printing
1640 @cindex @code{mhl}
1641 @cindex MH commands, @code{mhl}
1642 @cindex @code{lpr}
1643 @cindex Unix commands, @code{lpr}
1644 @findex @code{mh-print-msg}
1646 Printing mail is simple.  Enter @kbd{l} (@code{mh-print-msg}) (for
1647 @i{l}ine printer or @i{l}pr).  The message is formatted with @code{mhl}
1648 and printed with the @code{lpr} command.  You can print all the messages
1649 in a sequence by specifying a prefix argument, in which case you are
1650 prompted for the name of the sequence (as in @kbd{C-u l frombob RET}).
1652 @node Files and Pipes, Finishing Up, Printing, Moving Mail
1653 @subsection Files and Pipes
1655 @cindex using files
1656 @cindex using pipes
1657 @findex @code{mh-write-msg-to-file}
1659 mh-e does offer a couple of commands that are not a part of MH@.  The
1660 first one, @kbd{C-o} (@code{mh-write-msg-to-file}), writes a message to
1661 a file (think of the @kbd{o} as in "output").  You are prompted for the
1662 filename.  If the file already exists, the message is appended to it.
1663 You can also write the message to the file without the header by
1664 specifying a prefix argument (such as @kbd{C-u C-o /tmp/foobar RET}).
1665 Subsequent writes to the same file can be made with the @kbd{!}
1666 command.
1668 @findex @code{mh-pipe-msg}
1670 You can also pipe the message through a Unix shell command with the
1671 @kbd{|} (@code{mh-pipe-msg}) command.  You are prompted for the
1672 Unix command through which you wish to run your message.  If you
1673 give an argument to this command, the message header is included in the
1674 text passed to the command (the contrived example @kbd{C-u | lpr}
1675 would be done with the @kbd{l} command instead).
1677 @cindex @code{shar}
1678 @cindex Unix commands, @code{shar}
1679 @cindex @code{uuencode}
1680 @cindex Unix commands, @code{uuencode}
1681 @findex @code{mh-store-msg}
1683 If the message is a shell archive @code{shar} or has been run through
1684 @code{uuencode} use @kbd{M-n} (@code{mh-store-msg}) to extract the body
1685 of the message.  The default directory for extraction is the current
1686 directory, and you have a chance to specify a different extraction
1687 directory.  The next time you use this command, the default directory is
1688 the last directory you used.
1690 @node Finishing Up,  , Files and Pipes, Moving Mail
1691 @subsection Finishing Up
1693 @cindex expunging refiles and deletes
1694 @findex @code{mh-undo}
1695 @findex @code{mh-undo-folder}
1697 If you've deleted a message or refiled it, but changed your mind, you
1698 can cancel the action before you've executed it.  Use @kbd{u}
1699 (@code{mh-undo}) to undo a refile on or deletion of a single message.
1700 You can also undo refiles and deletes for messages that belong to a
1701 given sequence by specifying a prefix argument.  You'll be prompted for
1702 the name of the sequence (as in @kbd{C-u u frombob RET}).
1703 Alternatively, you can use @kbd{M-u} (@code{mh-undo-folder}) to undo all
1704 refiles or deletes in the current folder.
1706 @findex @code{mh-execute-commands}
1708 If you've marked messages to be deleted or refiled and you want to go
1709 ahead and delete or refile the messages, use @kbd{x}
1710 (@code{mh-execute-commands}).  Many mh-e commands that may affect the
1711 numbering of the messages (such as @kbd{M-r} or @kbd{M-p}) will ask if you
1712 want to process refiles or deletes first and then either run @kbd{x} for
1713 you or undo the pending refiles and deletes, which are lost.
1715 @findex @code{mh-rmail}
1716 @findex @code{mh-quit}
1718 When you want to quit using mh-e and go back to editing, you can use the
1719 @kbd{q} (@code{mh-quit}) command.  This buries the buffers of the
1720 current mh-e folder and restores the buffers that were present when you
1721 first ran @kbd{M-x mh-rmail}.  You can later restore your mh-e session
1722 by selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail}
1723 again.
1725 @node Searching, Sequences, Moving Mail, Using mh-e
1726 @section Searching Through Messages
1728 @cindex searching
1729 @findex @code{mh-search-folder}
1731 You can search a folder for messages to or from a particular person or
1732 about a particular subject.  In fact, you can also search for messages
1733 containing selected strings in any arbitrary header field or any string
1734 found within the messages.  Use the @kbd{M-s} (@code{mh-search-folder})
1735 command.  You are first prompted for the name of the folder to search
1736 and then placed in the following buffer in MH-Pick mode:
1738 @example
1739 @group
1740 @cartouche
1741 From: #
1744 Date:
1745 Subject:
1746 --------
1756 --**-Emacs: pick-pattern    (MH-Pick)------All--------------------------
1758 @end cartouche
1759 @i{Pick window}
1760 @end group
1761 @end example
1763 @cindex @code{pick}
1764 @cindex MH commands, @code{pick}
1766 Edit this template by entering your search criteria in an appropriate
1767 header field that is already there, or create a new field yourself.  If
1768 the string you're looking for could be anywhere in a message, then place
1769 the string underneath the row of dashes.  The @kbd{M-s} command uses the
1770 MH command @code{pick} to do the real work, so read @code{pick}(1) to
1771 find out more about how to enter the criteria.
1773 There are no semantics associated with the search criteria---they are
1774 simply treated as strings.  Case is ignored when all lowercase is used,
1775 and regular expressions (a la @code{ed}) are available.  It is all right
1776 to specify several search criteria.  What happens then is that a logical
1777 @emph{and} of the various fields is performed.  If you prefer a logical
1778 @emph{or} operation, run @kbd{M-s} multiple times.
1780 As an example, let's say that we want to find messages from Ginnean
1781 about horseback riding in the Kosciusko National Park (Australia) during
1782 January, 1994.  Normally we would start with a broad search and narrow
1783 it down if necessary to produce a manageable amount of data, but we'll
1784 cut to the chase and create a fairly restrictive set of criteria as
1785 follows:
1787 @example
1788 @group
1789 From: ginnean
1792 Date: Jan 1994
1793 Subject: horse.*kosciusko
1794 --------
1795 @end group
1796 @end example
1798 @findex @code{mh-to-field}
1800 As with MH-Letter mode, MH-Pick provides commands like
1801 @kbd{C-c C-f C-t} to help you fill in the blanks.
1803 @table @kbd
1804 @item C-c C-f C-t
1805 Move to @samp{To:} header field (@code{mh-to-field}).
1807 @item C-c C-f C-c
1808 Move to @samp{cc:} header field (@code{mh-to-field}).
1810 @item C-c C-f C-s
1811 Move to @samp{Subject:} header field (@code{mh-to-field}).
1813 @item C-c C-f C-f
1814 Move to @samp{From:} header field (@code{mh-to-field}).
1816 @item C-c C-f C-b
1817 Move to @samp{Bcc:} header field (@code{mh-to-field}).
1819 @item C-c C-f C-f
1820 Move to @samp{Fcc:} header field (@code{mh-to-field}).
1822 @item C-c C-f C-d
1823 Move to @samp{Dcc:} header field (@code{mh-to-field}).
1825 @item C-c C-c
1826 Execute the search (@code{mh-do-pick-search}).
1827 @end table
1829 @findex @code{mh-do-pick-search}
1831 To perform the search, type @kbd{C-c C-c} (@code{mh-do-pick-search}).
1832 The selected messages are placed in the @i{search} sequence, which you
1833 can use later in forwarding (@pxref{Forwarding}), printing
1834 (@pxref{Printing}), or narrowing your field of view (@pxref{Sequences}).
1835 Subsequent searches are appended to the @i{search} sequence.  If,
1836 however, you wish to start with a clean slate, first delete the
1837 @i{search} sequence (how to do this is discussed in @ref{Sequences}).
1839 @cindex MH-Folder mode
1840 @cindex modes, MH-Folder
1842 If you're searching in a folder that is already displayed in a
1843 MH-Folder buffer, only those messages contained in the buffer are
1844 used for the search.  Therefore, if you want to search in all messages,
1845 first kill the folder's buffer with @kbd{C-x k} or scan the entire
1846 folder with @kbd{M-r}.
1848 @node Sequences, Miscellaneous, Searching, Using mh-e
1849 @section Using Sequences
1851 @cindex sequences
1853 For the whole scoop on MH sequences, refer to @code{mh-sequence}(5).  As
1854 you've read, several of the mh-e commands can operate on a sequence,
1855 which is a shorthand for a range or group of messages.  For example, you
1856 might want to forward several messages to a friend or colleague.  Here's
1857 how to manipulate sequences.
1859 @table @kbd
1860 @item %
1861 Put message in a sequence (@code{mh-put-msg-in-seq}).
1863 @item ?
1864 Display sequences that message belongs to (@code{mh-msg-is-in-seq}).
1866 @item M-q
1867 List all sequences in folder (@code{mh-list-sequences}).
1869 @item M-%
1870 Remove message from sequence (@code{mh-delete-msg-from-seq}).
1872 @item M-#
1873 Delete sequence (@code{mh-delete-seq}).
1875 @item C-x n
1876 Restrict display to messages in sequence (@code{mh-narrow-to-seq}).
1878 @item C-x w
1879 Remove restriction; display all messages (@code{mh-widen}).
1881 @item M-x mh-update-sequences
1882 Push mh-e's state out to MH@.
1883 @end table
1885 @cindex @code{pick}
1886 @cindex MH commands, @code{pick}
1887 @findex @code{mh-put-msg-in-seq}
1889 To place a message in a sequence, use @kbd{%} (@code{mh-put-msg-in-seq})
1890 to do it manually, or use the MH command @code{pick} or the mh-e version
1891 of @code{pick} (@ref{Searching}) which create a sequence automatically.
1892 Give @kbd{%} a prefix argument and you can add all the messages in one
1893 sequence to another sequence (for example, @kbd{C-u % SourceSequence
1894 RET}).
1896 @cindex MH-Folder mode
1897 @cindex modes, MH-Folder
1898 @findex @code{mh-narrow-to-seq}
1899 @findex @code{mh-widen}
1901 Once you've placed some messages in a sequence, you may wish to narrow
1902 the field of view to just those messages in the sequence you've created.
1903 To do this, use @kbd{C-x n} (@code{mh-narrow-to-seq}).  You are prompted
1904 for the name of the sequence.  What this does is show only those
1905 messages that are in the selected sequence in the MH-Folder buffer.  In
1906 addition, it limits further mh-e searches to just those messages.  When
1907 you want to widen the view to all your messages again, use @kbd{C-x w}
1908 (@code{mh-widen}).
1910 @findex @code{mh-msg-is-in-seq}
1911 @findex @code{mh-list-sequences}
1913 You can see which sequences a message is in with the @kbd{?}
1914 (@code{mh-msg-is-in-seq}) command.
1915 @c Doesn't work:
1916 @c use a prefix argument to query a
1917 @c message other than the current one (as in @kbd{C-u ? 42 RET}). XXX
1918 Or, you can list all sequences in a selected folder (default is current
1919 folder) with @kbd{M-q} (@code{mh-list-sequences}).
1921 @findex @code{mh-delete-msg-from-seq}
1922 @findex @code{mh-delete-seq}
1924 If you want to remove a message from a sequence, use @kbd{M-%}
1925 (@code{mh-delete-msg-from-seq}), and if you want to delete an entire
1926 sequence, use @kbd{M-#} (@code{mh-delete-seq}).  In the latter case you
1927 are prompted for the sequence to delete.  Note that this deletes only
1928 the sequence, not the messages in the sequence.  If you want to delete
1929 the messages, use @kbd{C-u d} (see @ref{Deleting} above).
1931 @cindex @code{mark}
1932 @cindex MH commands, @code{mark}
1934 @findex @code{mh-update-sequences}
1936 Two sequences are maintained internally by mh-e and pushed out to MH
1937 when you type either the @kbd{x} or @kbd{q} command.  They are the
1938 sequence specified by your @samp{Unseen-Sequence:} profile entry and
1939 @i{cur}.  However, you can also just update MH's state with the command
1940 @kbd{M-x mh-update-sequences}.  See @ref{Customizing Viewing} for an
1941 example of how this command might be used.
1943 With the exceptions of @kbd{C-x n} and @kbd{C-x w}, the underlying MH
1944 command dealing with sequences is @code{mark}.
1946 @node Miscellaneous,  , Sequences, Using mh-e
1947 @section Miscellaneous Commands
1949 @findex @code{mh-version}
1951 One other command worth noting is @kbd{M-x mh-version}. You can
1952 compare the version this command prints to the latest release
1953 (@pxref{Getting mh-e}). The output of @kbd{M-x mh-version} should
1954 always be included with any bug report you submit (@pxref{Bug Reports}).
1956 @node    Customizing mh-e, Odds and Ends, Using mh-e, Top
1957 @chapter Customizing mh-e
1959 Until now, we've talked about the mh-e commands as they work ``out of the
1960 box.''  Of course, it is also possible to reconfigure mh-e
1961 to fit the needs of even the most demanding user.
1962 The following sections describe all of the
1963 customization variables, show the defaults, and make recommendations for
1964 customization.  The outline of this chapter is identical to that of
1965 @ref{Using mh-e}, to make it easier to find the variables you'd need to
1966 modify to affect a particular command.
1968 However, when customizing your mail environment, first try to change
1969 what you want in MH, and only change mh-e if changing MH is not
1970 possible.  That way you will get the same behavior inside and outside
1971 GNU Emacs.  Note that mh-e does not provide hooks for customizations
1972 that can be done in MH; this omission is intentional.
1974 @cindex @file{.emacs}
1975 @cindex files, @file{.emacs}
1977 Many string or integer variables are easy enough to modify using Emacs
1978 Lisp.  Any such modifications should be placed in a file called
1979 @file{.emacs} in your home directory (that is, @file{~/.emacs}).  For
1980 example, to modify the variable that controls printing, you could add:
1982 @vindex @code{mh-lpr-command-format}, example
1984 @lisp
1985 (setq mh-lpr-command-format "nenscript -G -r -2 -i'%s'")
1986 @end lisp
1988 @ref{Customizing Printing} talks more about this variable.
1990 @cindex setting variables
1991 @cindex Emacs, setting variables
1993 Variables can also hold Boolean values.  In Emacs Lisp, the Boolean
1994 values are @code{nil}, which means false, and @code{t}, which means true.
1995 Usually, variables are turned off by setting their value to @code{nil}, as
1998 @vindex @code{mh-bury-show-buffer}, example
2000 @lisp
2001 (setq mh-bury-show-buffer nil)
2002 @end lisp
2004 which keeps the MH-Show buffer at the top of the buffer stack.
2005 To turn a variable on, you use
2007 @lisp
2008 (setq mh-bury-show-buffer t)
2009 @end lisp
2011 which places the MH-Show buffer at the bottom of the buffer
2012 stack.  However, the text says to turn on a variable by setting it to a
2013 @emph{non-@code{nil}} value, because sometimes values other than @code{t} are
2014 meaningful (for example, see @code{mhl-formfile}, described in
2015 @ref{Customizing Viewing}).  Other variables, such as hooks, involve a
2016 little more Emacs Lisp programming expertise.
2018 You can also ``preview'' the effects of changing variables before
2019 committing the changes to @file{~/.emacs}.  Variables can be changed in
2020 the current Emacs session by using @kbd{M-x set-variable}.
2022 @c XXX Stephen says: would be easier to just call them functions, which
2023 @c you mostly do.
2024 In general, @dfn{commands} in this text refer to Emacs Lisp functions.
2025 Programs outside of Emacs are specifically called MH commands, shell
2026 commands, or Unix commands.
2028 @cindex Emacs, Emacs Lisp manual
2029 @cindex Emacs, online help
2030 @cindex online help
2031 @cindex Emacs, info
2032 @cindex info
2034 I hope I've included enough examples here to get you well on your way.
2035 If you want to explore Emacs Lisp further, a programming manual does
2036 exist,
2037 @c Yes, some of the stuff in the following sections is redundant, but
2038 @c TeX barfs if the @ifs are inside the @footnote.
2039 @iftex
2040 @footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available
2041 online in the Info system by typing @kbd{C-h i m Emacs Lisp RET}.  If
2042 not, you can order a printed manual, which has the desirable side-effect
2043 of helping to support the Free Software Foundation which made all this
2044 great software available.  You can find an order form by running
2045 @kbd{C-h C-d}, or you can request an order form from
2046 @i{gnu@@gnu.org}.}
2047 @end iftex
2048 @ifinfo
2049 @footnote{Perhaps you can find the online version of @ref{Top, The GNU
2050 Emacs Lisp Reference Manual, , elisp, GNU Emacs Lisp Reference Manual}.
2051 If not, you can order a printed manual, which has the desirable
2052 side-effect of helping to support the Free Software Foundation which
2053 made all this great software available.  You can find an order form by
2054 running @kbd{C-h C-d}, or you can request an order form from
2055 @i{gnu@@gnu.org}.}
2056 @end ifinfo
2057 and you can look at the code itself for examples.  Look in the Emacs
2058 Lisp directory on your system (such as @file{/usr/local/lib/emacs/lisp})
2059 and find all the @file{mh-*.el} files there.  When calling mh-e and
2060 other Emacs Lisp functions directly from Emacs Lisp code, you'll need to
2061 know the correct arguments.  Use the online help for this.  For example,
2062 try @kbd{C-h f mh-execute-commands RET}.  If you write your own
2063 functions, please do not prefix your symbols (variables and functions)
2064 with @code{mh-}.  This prefix is reserved for the mh-e package.  To
2065 avoid conflicts with existing mh-e symbols, use a prefix like @code{my-}
2066 or your initials.
2068 @menu
2069 * Customizing Reading::
2070 * Customizing Sending::
2071 * Customizing Draft Editing::
2072 * Customizing Moving Mail::
2073 * Customizing Searching::
2074 @end menu
2076 @node Customizing Reading, Customizing Sending, Customizing mh-e, Customizing mh-e
2077 @section Reading Your Mail
2079 @cindex reading mail
2080 @cindex @file{.emacs}
2081 @cindex files, @file{.emacs}
2083 I'll start out by including a function that I use as a front end to
2084 mh-e.  @footnote{Stephen Gildea's favorite binding is
2085 @kbd{(global-set-key "\C-cr" 'mh-rmail)}.} It toggles between your
2086 working window configuration, which may be quite involved---windows
2087 filled with source, compilation output, man pages, and other
2088 documentation---and your mh-e window configuration.  Like the rest of
2089 the customization described in this chapter, simply add the following
2090 code to @file{~/.emacs}.  Don't be intimidated by the size of this
2091 example; most customizations are only one line.
2093 @iftex
2094 @filbreak
2095 @end iftex
2097 @findex @code{mh-rmail}, example
2099 @lisp
2100 @group
2101 @i{Starting mh-e}
2103 (defvar my-mh-screen-saved nil
2104   "Set to non-@code{nil} when mh-e window configuration shown.")
2105 (defvar my-normal-screen nil "Normal window configuration.")
2106 (defvar my-mh-screen nil "mh-e window configuration.")
2108 (defun my-mh-rmail (&optional arg)
2109   "Toggle between mh-e and normal screen configurations.
2110 With non-@code{nil} or prefix argument, @i{inc} mailbox as well
2111 when going into mail."
2112   (interactive "P")                 ; @r{user callable function, P=prefix arg}
2113   (setq my-mh-screen-saved          ; @r{save state}
2114         (cond
2115          ;; @r{Bring up mh-e screen if arg or normal window configuration.}
2116          ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.}
2117          ((or arg (null my-mh-screen-saved))
2118           (setq my-normal-screen (current-window-configuration))
2119           (if (or arg (null (get-buffer "+inbox")))
2120               (mh-rmail)
2121             (set-window-configuration my-mh-screen))
2122           t)                        ; @r{set my-mh-screen-saved to @code{t}}
2123          ;; @r{Otherwise, save mh-e screen and restore normal screen.}
2124          (t
2125           (setq my-mh-screen (current-window-configuration))
2126           (set-window-configuration my-normal-screen)
2127           nil))))                   ; @r{set my-mh-screen-saved to nil}
2129 (global-set-key "\C-x\r" 'my-mh-rmail)  ;@r{ call with C-x RET}
2130 @end group
2131 @end lisp
2133 If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved}
2134 is @code{nil} (meaning a non-mh-e window configuration), the current window
2135 configuration is saved, either +inbox is displayed or @code{mh-rmail} is
2136 run, and the mh-e window configuration is shown.  Otherwise, the mh-e
2137 window configuration is saved and the original configuration is
2138 displayed.
2140 Now to configure mh-e.  The following table lists general mh-e variables
2141 and variables that are used while reading mail.
2142 @c XXX Seth wishes the descriptions to be more parallel.  That is,
2143 @c some are actions, and some are objects. Hmmm.
2145 @table @code
2146 @item mh-progs
2147 Directory containing MH programs (default: dynamic).
2149 @item mh-lib
2150 Directory containing MH support files and programs (default: dynamic).
2152 @item mh-do-not-confirm
2153 Don't confirm on non-reversible commands (default: @code{nil}).
2155 @item mh-summary-height
2156 Number of scan lines to show (includes mode line) (default: 4).
2158 @item mh-folder-mode-hook
2159 Functions to run in MH-Folder mode (default: @code{nil}).
2161 @item mh-clean-message-header
2162 Remove extraneous headers (default: @code{nil}).
2164 @item mh-invisible-headers
2165 Headers to hide (default: @samp{"^Received: \\| ^Message-Id: \\|
2166 ^Remailed-\\| ^Via: \\| ^Mail-from: \\| ^Return-Path: \\| ^In-Reply-To:
2167 \\| ^Resent-"}).
2169 @item mh-visible-headers
2170 Headers to display (default: @code{nil}).
2172 @item mhl-formfile
2173 Format file for @code{mhl} (default: @code{nil}).
2175 @item mh-show-hook
2176 Functions to run when showing message (default: @code{nil}).
2178 @item mh-show-mode-hook
2179 Functions to run when showing message (default: @code{nil}).
2181 @item mh-bury-show-buffer
2182 Leave show buffer at bottom of stack (default: @code{t}).
2184 @item mh-show-buffer-mode-line-buffer-id
2185 Name of show buffer in mode line (default: @samp{"@{show-%s@} %d"}).
2186 @end table
2188 @vindex @code{mh-progs}
2189 @vindex @code{mh-lib}
2191 The two variables @code{mh-progs} and @code{mh-lib} are used to tell
2192 mh-e where the MH programs and supporting files are kept, respectively.
2193 mh-e does try to figure out where they are kept for itself by looking in
2194 common places and in the user's @samp{PATH} environment variable, but if
2195 it cannot find the directories, or finds the wrong ones, you should set
2196 these variables.  The name of the directory should be placed in double
2197 quotes, and there should be a
2198 trailing slash (@samp{/}).  See the example in @ref{Getting Started}.
2200 @vindex @code{mh-do-not-confirm}
2201 @findex @code{mh-kill-folder}
2203 If you never make mistakes, and you do not like confirmations for your
2204 actions, you can set @code{mh-do-not-confirm} to a non-@code{nil} value to
2205 disable confirmation for unrecoverable commands such as @kbd{M-k}
2206 (@code{mh-kill-folder}) and @kbd{M-u} (@code{mh-undo-folder}).  Here's
2207 how you set boolean values:
2209 @lisp
2210 (setq mh-do-not-confirm t)
2211 @end lisp
2213 @vindex @code{mh-summary-height}
2214 @cindex MH-Folder mode
2215 @cindex modes, MH-Folder
2217 @c Prevent page break between paragraph and example.
2218 @need 2000
2219 The variable @code{mh-summary-height} controls the number of scan lines
2220 displayed in the MH-Folder window, including the mode line.  The
2221 default value of 4 means that 3 scan lines are displayed.  Here's how
2222 you set numerical values:
2224 @lisp
2225 (setq mh-summary-height 2)              ; @r{only show the current scan line}
2226 @end lisp
2228 @vindex @code{mh-bury-show-buffer}
2229 @cindex MH-Folder mode
2230 @cindex modes, MH-Folder
2232 Normally the buffer for displaying messages is buried at the bottom at
2233 the buffer stack.  You may wish to disable this feature by setting
2234 @code{mh-bury-show-buffer} to @code{nil}.  One advantage of not burying the
2235 show buffer is that one can delete the show buffer more easily in an
2236 electric buffer list because of its proximity to its associated
2237 MH-Folder buffer.  Try running @kbd{M-x electric-buffer-list} to
2238 see what I mean.
2240 @vindex @code{mh-folder-mode-hook}
2241 @cindex MH-Folder mode
2242 @cindex modes, MH-Folder
2244 The hook @code{mh-folder-mode-hook} is called when a new folder is
2245 created with MH-Folder mode.  This could be used to set your own
2246 key bindings, for example:
2248 @vindex @code{mh-folder-mode-hook}, example
2250 @lisp
2251 @group
2252 @i{Create additional key bindings via mh-folder-mode-hook}
2254 (defvar my-mh-init-done nil "Non-@code{nil} when one-time mh-e settings made.")
2256 (defun my-mh-folder-mode-hook ()
2257   "Hook to set key bindings in MH-Folder mode."
2258   (if (not my-mh-init-done)             ; @r{only need to bind the keys once }
2259       (progn
2260         (local-set-key "/" 'search-msg)
2261         (local-set-key "b" 'mh-burst-digest)    ; @r{better use of @kbd{b}}
2262         (setq my-mh-init-done t))))
2264 ;;; @r{Emacs 19}
2265 (add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook)
2266 ;;; @r{Emacs 18}
2267 ;;;   @r{(setq mh-folder-mode-hook (cons 'my-mh-folder-mode-hook}
2268 ;;;                               @r{mh-folder-mode-hook))}
2270 (defun search-msg ()
2271   "Search for a regexp in the current message."
2272   (interactive)                         ; @r{user function}
2273   (save-window-excursion
2274     (other-window 1)                    ; @r{go to next window}
2275     (isearch-forward-regexp)))          ; @r{string search; hit return (ESC}
2276                                         ;   @r{in Emacs 18) when done}
2277 @end group
2278 @end lisp
2280 @menu
2281 * Customizing Viewing::
2282 * Customizing Moving Around::
2283 @end menu
2285 @node Customizing Viewing, Customizing Moving Around, Customizing Reading, Customizing Reading
2286 @subsection Viewing Your Mail
2288 @vindex @code{mh-clean-message-header}
2289 @vindex @code{mh-invisible-headers}
2290 @vindex @code{mh-visible-headers}
2292 Several variables control what displayed messages look like.  Normally
2293 messages are delivered with a handful of uninteresting header fields.
2294 You can make them go away by setting @code{mh-clean-message-header} to a
2295 non-@code{nil} value.  The header can then be cleaned up in two ways.  By
2296 default, the header fields in @code{mh-invisible-headers} are removed.
2297 On the other hand, you could set @code{mh-visible-headers} to the fields
2298 that you would like to see.  If this variable is set,
2299 @code{mh-invisible-headers} is ignored.  I suggest that you not set
2300 @code{mh-visible-headers} since if you use this variable, you might miss
2301 a lot of header fields that you'd rather not miss.  As an example of how
2302 to set a string variable, @code{mh-visible-headers} can be set to show a
2303 minimum set of header fields (see (@ref{Regexps, , Syntax of Regular
2304 Expressions, emacs, The GNU Emacs Manual}, for a description of the
2305 special characters in this string):
2307 @lisp
2308 (setq mh-visible-headers "^From: \\|^Subject: \\|^Date: ")
2309 @end lisp
2311 @cindex @code{mhl}
2312 @cindex MH commands, @code{mhl}
2313 @vindex @code{mhl-formfile}
2315 Normally mh-e takes care of displaying messages itself (rather than
2316 calling an MH program to do the work).  If you'd rather have @code{mhl}
2317 display the message (within mh-e), set the variable @code{mhl-formfile}
2318 to a non-@code{nil} value.  You can set this variable either to @code{t}
2319 to use the default format file or to a filename if you have your own
2320 format file (@code{mhl}(1) tells you how to write one).  When writing
2321 your own format file, use a nonzero value for @code{overflowoffset} to
2322 ensure the header is RFC 822 compliant and parsable by mh-e.
2323 @code{mhl} is always used for printing and forwarding; in this case, the
2324 value of @code{mhl-formfile} is consulted if it is a filename.
2326 @vindex @code{mh-show-mode-hook}
2328 Two hooks can be used to control how messages are displayed.  The first
2329 hook, @code{mh-show-mode-hook}, is called early on in the process of
2330 displaying of messages.  It is used to perform some actions on the
2331 contents of messages, such as highlighting the header fields.  If you're
2332 running Emacs 19 under the X Window System, the following example will
2333 highlight the @samp{From:} and @samp{Subject:} header fields.  This is a
2334 very nice feature indeed.
2336 @vindex @code{mh-show-mode-hook}, example
2338 @lisp
2339 @group
2340 @i{Emphasize header fields in different fonts via mh-show-mode-hook}
2342 (defvar my-mh-keywords
2343    '(("^From: \\(.*\\)" 1 'bold t)
2344      ("^Subject: \\(.*\\)" 1 'highlight t))
2345   "mh-e additions for font-lock-keywords.")
2347 (defun my-mh-show-mode-hook ()
2348   "Hook to turn on and customize fonts."
2349   (font-lock-add-keywords nil my-mh-keywords))
2351 (add-hook 'mh-show-mode-hook 'my-mh-show-mode-hook))
2352 @end group
2353 @end lisp
2355 @vindex @code{mh-show-hook}
2357 The second hook, @code{mh-show-hook}, is the last thing called after
2358 messages are displayed.  It's used to affect the behavior of mh-e in
2359 general or when @code{mh-show-mode-hook} is too early.  For example, if
2360 you wanted to keep mh-e in sync with MH, you could use
2361 @code{mh-show-hook} as follows:
2363 @vindex @code{mh-show-hook}, example
2365 @lisp
2366 (add-hook 'mh-show-hook 'mh-update-sequences)
2367 @end lisp
2369 @vindex @code{mh-show-buffer-mode-line-buffer-id}
2370 @cindex MH-Show mode
2371 @cindex modes, MH-Show
2373 The function @code{mh-update-sequences} is documented in @ref{Finishing
2374 Up}.  For those who like to modify their mode lines, use
2375 @code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in the
2376 MH-Show buffers.  Place the two escape strings @samp{%s} and @samp{%d},
2377 which will display the folder name and the message number, respectively,
2378 somewhere in the string in that order.  The default value of
2379 @samp{"@{show-%s@} %d"} yields a mode line of
2381 @example
2382 -----@{show-+inbox@} 4      (MH-Show)--Bot--------------------------------
2383 @end example
2385 @node Customizing Moving Around,  , Customizing Viewing, Customizing Reading
2386 @subsection Moving Around
2388 @cindex moving between messages
2389 @cindex MH-Show mode
2390 @cindex modes, MH-Show
2391 @cindex MH-Folder mode
2392 @cindex modes, MH-Folder
2393 @vindex @code{mh-recenter-summary-p}
2395 When you use @kbd{t} (@code{mh-toggle-showing}) to toggle between show
2396 mode and scan mode, the MH-Show buffer is hidden and the
2397 MH-Folder buffer is left alone.  Setting
2398 @code{mh-recenter-summary-p} to a non-@code{nil} value causes the toggle to
2399 display as many scan lines as possible, with the cursor at the middle.
2400 The effect of @code{mh-recenter-summary-p} is rather useful, but it can
2401 be annoying on a slow network connection.
2403 @node Customizing Sending, Customizing Draft Editing, Customizing Reading, Customizing mh-e
2404 @section Sending Mail
2406 @cindex sending mail
2408 You may wish to start off by adding the following useful key bindings to
2409 your @file{.emacs} file:
2411 @lisp
2412 (global-set-key "\C-xm" 'mh-smail)
2413 (global-set-key "\C-x4m" 'mh-smail-other-window)
2414 @end lisp
2416 In addition, several variables are useful when sending mail or replying
2417 to mail.  They are summarized in the following table.
2419 @table @code
2420 @item mh-comp-formfile
2421 Format file for drafts (default: @samp{"components"}).
2423 @item mh-repl-formfile
2424 Format file for replies (default: @samp{"replcomps"}).
2426 @item mh-letter-mode-hook
2427 Functions to run in MH-Letter mode (default: @code{nil}).
2429 @item mh-compose-letter-function
2430 Functions to run when starting a new draft (default: @code{nil}).
2432 @item mh-reply-default-reply-to
2433 Whom reply goes to (default: @code{nil}).
2435 @item mh-forward-subject-format
2436 Format string for forwarded message subject (default: @samp{"%s: %s"}).
2438 @item mh-redist-full-contents
2439 @code{send} requires entire message (default: @code{nil}).
2441 @item mh-new-draft-cleaned-headers
2442 Remove these header fields from re-edited draft.  The default is:
2443 @example
2444 "^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\|
2445 ^Sender:\\| ^Delivery-Date:\\| ^Return-Path:".
2446 @end example
2447 @end table
2449 @cindex @code{comp}
2450 @cindex MH commands, @code{comp}
2451 @vindex @code{mh-comp-formfile}
2452 @cindex @file{components}
2453 @cindex files, @file{components}
2454 @cindex @code{repl}
2455 @cindex MH commands, @code{repl}
2456 @cindex @file{replcomps}
2457 @cindex files, @file{replcomps}
2458 @vindex @code{mh-repl-formfile}
2460 Since mh-e does not use @code{comp} to create the initial draft, you
2461 need to set @code{mh-comp-formfile} to the name of your components file
2462 if it isn't @file{components}.  This is the name of the file that
2463 contains the form for composing messages.  If it does not contain an
2464 absolute pathname, mh-e searches for the file first in your MH directory
2465 and then in the system MH library directory (such as
2466 @file{/usr/local/lib/mh}).  Replies, on the other hand, are built using
2467 @code{repl}.  You can change the location of the field file from the
2468 default of @file{replcomps} by modifying @code{mh-repl-formfile}.
2470 @vindex @code{mh-letter-mode-hook}
2471 @cindex @code{repl}
2472 @cindex MH commands, @code{repl}
2473 @cindex @file{components}
2474 @cindex files, @file{components}
2476 Two hooks are provided to run commands on your freshly created draft.
2477 The first hook, @code{mh-letter-mode-hook}, allows you to do some
2478 processing before editing a letter.  For example, you may wish to modify
2479 the header after @code{repl} has done its work, or you may have a
2480 complicated @file{components} file and need to tell mh-e where the
2481 cursor should go.  Here's an example of how you would use this hook---all
2482 of the other hooks are set in this fashion as well.
2484 @findex @code{mh-insert-signature}, example
2486 @lisp
2487 @group
2488 @i{Prepare draft for editing via mh-letter-mode-hook}
2490 (defvar letter-mode-init-done nil
2491   "Non-@code{nil} when one-time mh-e settings have made.")
2493 (defun my-mh-letter-mode-hook ()
2494   "Hook to prepare letter for editing."
2495   (if (not letter-mode-init-done)    ; @r{only need to bind the keys once}
2496       (progn
2497         (local-set-key "\C-ctb" 'add-enriched-text)
2498         (local-set-key "\C-cti" 'add-enriched-text)
2499         (local-set-key "\C-ctf" 'add-enriched-text)
2500         (local-set-key "\C-cts" 'add-enriched-text)
2501         (local-set-key "\C-ctB" 'add-enriched-text)
2502         (local-set-key "\C-ctu" 'add-enriched-text)
2503         (local-set-key "\C-ctc" 'add-enriched-text)
2504         (setq letter-mode-init-done t)))
2505   (setq fill-prefix "  ")            ; @r{I find indented text easier to read}
2506   (save-excursion
2507     (goto-char (point-max))          ; @r{go to end of message to}
2508     (mh-insert-signature)))          ;   @r{insert signature}
2510 (add-hook 'mh-letter-mode-hook 'my-mh-letter-mode-hook)
2511 @end group
2512 @end lisp
2514 The function, @code{add-enriched-text} is defined in the example in
2515 @ref{Customizing Editing MIME}.
2517 @vindex @code{mh-compose-letter-function}
2519 The second hook, a function really, is
2520 @code{mh-compose-letter-function}.  Like @code{mh-letter-mode-hook}, it
2521 is called just before editing a new message; however, it is the last
2522 function called before you edit your message.  The consequence of this
2523 is that you can write a function to write and send the message for you.
2524 This function is passed three arguments: the contents of the @samp{To:},
2525 @samp{Subject:}, and @samp{cc:} header fields.
2527 @menu
2528 * Customizing Replying::
2529 * Customizing Forwarding::
2530 * Customizing Redistributing::
2531 * Customizing Old Drafts::
2532 @end menu
2534 @node Customizing Replying, Customizing Forwarding, Customizing Sending, Customizing Sending
2535 @subsection Replying to Mail
2537 @cindex replying
2538 @vindex @code{mh-reply-default-reply-to}
2540 If you find that most of the time that you specify @kbd{cc} when you
2541 reply to a message, set @code{mh-reply-default-reply-to} to @samp{cc}.
2542 This variable is normally set to @code{nil} so that you are prompted for
2543 the recipient of a reply.  It can be set to one of @samp{from},
2544 @samp{to}, or @samp{cc}; you are then no longer prompted for the
2545 recipient(s) of your reply.
2547 @node Customizing Forwarding, Customizing Redistributing, Customizing Replying, Customizing Sending
2548 @subsection Forwarding Mail
2550 @cindex forwarding
2551 @vindex @code{mh-forward-subject-format}
2553 When forwarding a message, the format of the @samp{Subject:} header
2554 field can be modified by the variable @code{mh-forward-subject-format}.
2555 This variable is a string which includes two escapes (@samp{%s}).  The
2556 first @samp{%s} is replaced with the sender of the original message, and
2557 the second one is replaced with the original @samp{Subject:}.  The
2558 default value of @samp{"%s: %s"} takes a message with the header:
2560 @example
2561 @group
2562 To: Bill Wohler <wohler@@newt.com>
2563 Subject: Re: 49er football
2564 From: Greg DesBrisay <gd@@cellnet.com>
2565 @end group
2566 @end example
2568 and creates a subject header field of:
2570 @example
2571 Subject: Greg DesBrisay: Re: 49er football
2572 @end example
2574 @node Customizing Redistributing, Customizing Old Drafts, Customizing Forwarding, Customizing Sending
2575 @subsection Redistributing Your Mail
2577 @cindex redistributing
2578 @vindex @code{mh-redist-full-contents}
2579 @cindex @code{dist}
2580 @cindex MH commands, @code{dist}
2581 @cindex @code{send}
2582 @cindex MH commands, @code{send}
2584 The variable @code{mh-redist-full-contents} must be set to non-@code{nil} if
2585 @code{dist} requires the whole letter for redistribution, which is the
2586 case if @code{send} is compiled with the @sc{berk} @footnote{To see which
2587 options your copy of MH was compiled with, use @kbd{M-x mh-version}
2588 (@ref{Miscellaneous}).}  option (which many people abhor).  If you find
2589 that MH will not allow you to redistribute a message that has been
2590 redistributed before, this variable should be set to @code{nil}.
2592 @node Customizing Old Drafts,  , Customizing Redistributing, Customizing Sending
2593 @subsection Editing Old Drafts and Bounced Messages
2595 @cindex re-editing drafts
2596 @vindex @code{mh-new-draft-cleaned-headers}
2598 The header fields specified by @code{mh-new-draft-cleaned-headers} are
2599 removed from an old draft that has been recreated with @kbd{M-e}
2600 (@code{mh-extract-rejected-mail}) or @kbd{M-a} (@code{mh-edit-again}).
2601 If when you edit an old draft with these commands you find that there
2602 are header fields that you don't want included, you can append them to
2603 this variable.  For example,
2605 @vindex @code{mh-new-draft-cleaned-headers}, example
2607 @lisp
2608 (setq mh-new-draft-cleaned-headers
2609       (concat mh-new-draft-cleaned-headers "\\|^Some-Field:"))
2610 @end lisp
2612 @cindex regular expressions
2614 This appends the regular expression @samp{\\|^Some-Field:} to the
2615 variable (@pxref{Regexps, , Syntax of Regular Expressions, emacs, The
2616 GNU Emacs Manual}).  The @samp{\\|} means @emph{or}, and the @samp{^}
2617 (caret) matches the beginning of the line.  This is done to be very
2618 specific about which fields match.  The literal @samp{:} is appended for
2619 the same reason.
2621 @node Customizing Draft Editing, Customizing Moving Mail, Customizing Sending, Customizing mh-e
2622 @section Editing a Draft
2624 @cindex editing draft
2626 There are several variables used during the draft editing phase.
2627 Examples include changing the name of the file that holds your signature
2628 or telling mh-e about new multimedia types.  They are:
2630 @table @code
2631 @item mh-yank-from-start-of-msg
2632 How to yank when region not set (default: @code{t}).
2634 @item mh-ins-buf-prefix
2635 Indent for yanked messages (default: @samp{"> "}).
2637 @item mail-citation-hook
2638 Functions to run on yanked messages (default: @code{nil}).
2640 @item mh-delete-yanked-msg-window
2641 Delete message window on yank (default: @code{nil}).
2643 @c Need the @* because otherwise TeX fills it wrong and complains
2644 @c about overfull hbox.
2645 @item mh-mime-content-types
2646 List of valid content types (default: @samp{'(("text/plain")@*
2647 ("text/richtext") ("multipart/mixed") ("multipart/alternative")@*
2648 ("multipart/digest") ("multipart/parallel") ("message/rfc822")@*
2649 ("message/partial") ("message/external-body")@*
2650 ("application/octet-stream") ("application/postscript")@*
2651 ("image/jpeg") ("image/gif") ("audio/basic") ("video/mpeg"))}).
2653 @item mh-mhn-args
2654 Additional arguments for @code{mhn} (default: @code{nil}).
2656 @item mh-signature-file-name
2657 File containing signature (default: @samp{"~/.signature"}).
2659 @item mh-before-send-letter-hook
2660 Functions to run before sending draft (default: @code{nil}).
2662 @item mh-send-prog
2663 MH program used to send messages (default: @samp{"send"}).
2664 @end table
2666 @menu
2667 * Customizing Editing Textual::
2668 * Customizing Editing MIME::
2669 * Customizing Sending Message::
2670 @end menu
2672 @node Customizing Editing Textual, Customizing Editing MIME, Customizing Draft Editing, Customizing Draft Editing
2673 @subsection Editing Textual Messages
2675 The following two sections include variables that customize the way you
2676 edit a draft.  The discussion here applies to editing multimedia
2677 messages as well.
2679 @menu
2680 * Customizing Inserting Letter::
2681 * Customizing Signature::
2682 @end menu
2684 @node Customizing Inserting Letter, Customizing Signature, Customizing Editing Textual, Customizing Editing Textual
2685 @subsubsection Inserting letter to which you're replying
2687 @cindex inserting messages
2688 @vindex @code{mh-yank-from-start-of-msg}
2689 @vindex @code{mh-ins-buf-prefix}
2690 @vindex @code{mail-citation-hook}
2691 @vindex @code{mh-ins-buf-prefix}
2692 @vindex @code{mh-delete-yanked-msg-window}
2694 To control how much of the message to which you are replying is yanked
2695 by @kbd{C-c C-y} (@code{mh-yank-cur-msg}) into your reply, modify
2696 @code{mh-yank-from-start-of-msg}.  The default value of @code{t} means
2697 that the entire message is copied.  If it is set to @code{'body} (don't
2698 forget the apostrophe), then only the message body is copied.  If it is
2699 set to @code{nil}, only the part of the message following point (the
2700 current cursor position in the message's buffer) is copied.  In any
2701 case, this variable is ignored if a region is set in the message you are
2702 replying to.  The string contained in @code{mh-ins-buf-prefix} is
2703 inserted before each line of a message that is inserted into a draft
2704 with @kbd{C-c C-y} (@code{mh-yank-cur-msg}).  I suggest that you not
2705 modify this variable.  The default value of @samp{"> "} is the default
2706 string for many mailers and news readers: messages are far easier to
2707 read if several included messages have all been indented by the same
2708 string.  The variable @code{mail-citation-hook} is @code{nil} by
2709 default, which means that when a message is inserted into the letter,
2710 each line is prefixed by @code{mh-ins-buf-prefix}.  Otherwise, it can be
2711 set to a function that modifies an included
2712 @cindex Emacs, packages, supercite
2713 citation.
2714 @c Footnotes are fragile; hence the redundancy.
2715 @c TeX not inserting a line break; hence the @*
2716 @ifclear html
2717 @footnote{@emph{Supercite} is an example of a full-bodied, full-featured
2718 citation package.  It is in Emacs versions 19.15 and later, and can be
2719 found via anonymous @code{ftp} on @samp{archive.cis.ohio-state.edu} in
2720 @* @file{/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z}}
2721 @end ifclear
2722 @ifset html
2723 @footnote{@emph{Supercite} is an example of a full-bodied,
2724 full-featured citation package.  It is in Emacs versions 19.15 and
2725 later, and its @sc{url} is @*
2726 @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>}}
2727 @end ifset
2728 If you like to yank all the text from the message you're replying to in
2729 one go, set @code{mh-delete-yanked-msg-window} to non-@code{nil} to delete
2730 the window containing the original message after yanking it to make more
2731 room on your screen for your reply.
2733 @node Customizing Signature,  , Customizing Inserting Letter, Customizing Editing Textual
2734 @subsubsection Inserting your signature
2736 @cindex inserting signature
2737 @cindex signature
2738 @vindex @code{mh-signature-file-name}
2739 @cindex @file{.signature}
2740 @cindex files, @file{.signature}
2742 You can change the name of the file inserted with @kbd{C-c C-s}
2743 (@code{mh-insert-signature}) by changing @code{mh-signature-file-name}
2744 (default: @file{"~/.signature"}).
2746 @node Customizing Editing MIME, Customizing Sending Message, Customizing Editing Textual, Customizing Draft Editing
2747 @subsection Editing Multimedia Messages
2749 @cindex MIME
2750 @cindex multimedia mail
2751 @vindex @code{mh-mime-content-types}
2753 The variable @code{mh-mime-content-types} contains a list of the
2754 currently valid content types.  They are listed in the table in
2755 @ref{Customizing Draft Editing}.  If you encounter a new content type,
2756 you can add it like this:
2758 @vindex @code{mh-mime-content-types}, example
2760 @lisp
2761 (setq mh-mime-content-types (append mh-mime-content-types
2762                                     '(("@var{new/type}"))))
2763 @end lisp
2765 Emacs macros can be used to insert enriched text directives like
2766 @samp{<bold>}.  The following code will make, for example, @kbd{C-c t
2767 b} insert the @samp{<bold>} directive.
2769 @smallexample
2770 @group
2771 @i{Emacs macros for entering enriched text}
2773 (defvar enriched-text-types '(("b" . "bold") ("i" . "italic")
2774                               ("f" . "fixed") ("s" . "smaller")
2775                               ("B" . "bigger") ("u" . "underline")
2776                               ("c" . "center"))
2777   "Alist of (final-character . directive) choices for add-enriched-text.
2778 Additional types can be found in RFC 1563.")
2780 (defun add-enriched-text (begin end)
2781   "Add enriched text directives around region.
2782 The directive used comes from the list enriched-text-types and is
2783 specified by the last keystroke of the command.  When called from Lisp,
2784 arguments are BEGIN and END@."
2785   (interactive "r")
2786   ;; @r{Set type to the directive indicated by the last keystroke.}
2787   (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`}))
2788                           enriched-text-types))))
2789     (save-restriction              ; @r{restores state from narrow-to-region}
2790       (narrow-to-region begin end) ; @r{narrow view to region}
2791       (goto-char (point-min))      ; @r{move to beginning of text}
2792       (insert "<" type ">")        ; @r{insert beginning directive}
2793       (goto-char (point-max))      ; @r{move to end of text}
2794       (insert "</" type ">"))))    ; @r{insert terminating directive}
2795 @end group
2796 @end smallexample
2798 To use the function @code{add-enriched-text}, first create key bindings
2799 for it (@pxref{Customizing Sending}).  Then, set the mark with
2800 @kbd{C-@@} or @kbd{C-SPC}, type in the text to be highlighted, and type
2801 @kbd{C-c t b}.  This adds @samp{<bold>} where you set the mark and
2802 adds @samp{</bold>} at the location of your cursor, giving you something
2803 like: @samp{You should be <bold>very</bold>}.  You may also be
2804 interested in investigating @code{sgml-mode}.
2806 @menu
2807 * Customizing Sending MIME::
2808 @end menu
2810 @node Customizing Sending MIME,  , Customizing Editing MIME, Customizing Editing MIME
2811 @subsubsection Readying multimedia messages for sending
2813 @vindex @code{mh-mhn-args}
2815 If you wish to pass additional arguments to @code{mhn} to affect how it
2816 builds your message, use the variable @code{mh-mhn-args}.  For example,
2817 you can build a consistency check into the message by setting
2818 @code{mh-mhn-args} to @code{-check}.  The recipient of your message can
2819 then run @code{mhn -check} on the message---@code{mhn} will complain if
2820 the message has been corrupted on the way.  The @kbd{C-c C-e}
2821 (@code{mh-mhn-edit}) command only consults this variable when given a
2822 prefix argument.
2824 @node Customizing Sending Message,  , Customizing Editing MIME, Customizing Draft Editing
2825 @subsection Sending a Message
2827 @cindex sending mail
2828 @cindex spell check
2829 @vindex @code{mh-before-send-letter-hook}
2831 If you want to check your spelling in your message before sending, use
2832 @code{mh-before-send-letter-hook} like this:
2834 @i{Spell-check message via mh-before-send-letter-hook}
2836 @vindex @code{mh-before-send-letter-hook}, example
2838 @lisp
2839 (add-hook 'mh-before-send-letter-hook 'ispell-message)
2840 @end lisp
2842 @cindex @code{send}
2843 @cindex MH commands, @code{send}
2844 @vindex @code{mh-send-prog}
2846 In case the MH @code{send} program is installed under a different name,
2847 use @code{mh-send-prog} to tell mh-e the name.
2849 @node Customizing Moving Mail, Customizing Searching, Customizing Draft Editing, Customizing mh-e
2850 @section Moving Your Mail Around
2852 @cindex processing mail
2854 If you change the name of some of the MH programs or have your own
2855 printing programs, the following variables can help you.
2856 They are described in detail in the subsequent sections.
2858 @table @code
2859 @item mh-inc-prog
2860 Program to incorporate mail (default: @samp{"inc"}).
2862 @item mh-inc-folder-hook
2863 Functions to run when incorporating mail (default: @code{nil}).
2865 @item mh-delete-msg-hook
2866 Functions to run when deleting messages (default: @code{nil}).
2868 @item mh-print-background
2869 Print in foreground or background (default: @code{nil}).
2871 @item mh-lpr-command-format
2872 Command used to print (default: @samp{"lpr -J '%s'"}).
2874 @item mh-default-folder-for-message-function
2875 Function to generate a default folder (default: @code{nil}).
2877 @item mh-auto-folder-collect
2878 Collect folder names in background at startup (default: @code{t}).
2880 @item mh-recursive-folders
2881 Collect nested folders (default: @code{nil}).
2883 @item mh-refile-msg-hook
2884 Functions to run when refiling message (default: @code{nil}).
2886 @item mh-store-default-directory
2887 Default directory for storing files created by @code{uuencode} or @code{shar}
2888 (default: @code{nil}).
2890 @item mh-sortm-args
2891 Additional arguments for @code{sortm} (default: @code{nil}).
2893 @item mh-scan-prog
2894 Program to scan messages (default: @samp{"scan"}).
2896 @item mh-before-quit-hook
2897 Functions to run before quitting (default: @code{nil}).  See also
2898 @code{mh-quit-hook}.
2900 @item mh-quit-hook
2901 Functions to run after quitting (default: @code{nil}). See also
2902 @code{mh-before-quit-hook}.
2903 @end table
2905 @menu
2906 * Customizing Incorporating::
2907 * Customizing Deleting::
2908 * Customizing Organizing::
2909 * Customizing Printing::
2910 * Customizing Files and Pipes::
2911 * Customizing Finishing Up::
2912 @end menu
2914 @node Customizing Incorporating, Customizing Deleting, Customizing Moving Mail, Customizing Moving Mail
2915 @subsection Incorporating Your Mail
2917 @cindex incorporating
2918 @vindex @code{mh-inc-prog}
2919 @cindex @code{inc}
2920 @cindex MH commands, @code{inc}
2921 @vindex @code{mh-progs}
2922 @vindex @code{mh-scan-prog}
2923 @vindex @code{mh-inc-folder-hook}
2925 The name of the program that incorporates new mail is stored in
2926 @code{mh-inc-prog}; it is @samp{"inc"} by default.  This program
2927 generates a one-line summary for each of the new messages.  Unless it is
2928 an absolute pathname, the file is assumed to be in the @code{mh-progs}
2929 directory.  You may also link a file to @code{inc} that uses a different
2930 format (see @code{mh-profile}(5)).  You'll then need to modify several
2931 variables appropriately; see @code{mh-scan-prog} below.  You can set the
2932 hook @code{mh-inc-folder-hook}, which is called after new mail is
2933 incorporated by the @kbd{i} (@code{mh-inc-folder}) command.  A good use
2934 of this hook is to rescan the whole folder either after running @kbd{M-x
2935 mh-rmail} the first time or when you've changed the message numbers from
2936 outside of mh-e.
2938 @findex @code{mh-execute-commands}
2939 @findex @code{mh-rescan-folder}, example
2940 @findex @code{mh-show}, example
2941 @vindex @code{mh-inc-folder-hook}, example
2943 @lisp
2944 @group
2945 @i{Rescan folder after incorporating new mail via mh-inc-folder-hook}
2947 (defun my-mh-inc-folder-hook ()
2948   "Hook to rescan folder after incorporating mail."
2949   (if (buffer-modified-p)            ; @r{if outstanding refiles and deletes,}
2950       (mh-execute-commands))         ;   @r{carry them out}
2951   (mh-rescan-folder)                 ; @r{synchronize with +inbox}
2952   (mh-show))                         ; @r{show the current message}
2954 (add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook)
2955 @end group
2956 @end lisp
2958 @node Customizing Deleting, Customizing Organizing, Customizing Incorporating, Customizing Moving Mail
2959 @subsection Deleting Your Mail
2961 @cindex deleting
2962 @vindex @code{mh-delete-msg-hook}
2964 The hook @code{mh-delete-msg-hook} is called after you mark a message
2965 for deletion.  For example, the current maintainer of mh-e used this
2966 once when he kept statistics on his mail usage.
2968 @node Customizing Organizing, Customizing Printing, Customizing Deleting, Customizing Moving Mail
2969 @subsection Organizing Your Mail with Folders
2971 @cindex using folders
2972 @vindex @code{mh-recursive-folders}
2973 @vindex @code{mh-auto-folder-collect}
2975 By default, operations on folders work only one level at a time.  Set
2976 @code{mh-recursive-folders} to non-@code{nil} to operate on all folders.
2977 This mostly means that you'll be able to see all your folders when you
2978 press @key{TAB} when prompted for a folder name.  The variable
2979 @code{mh-auto-folder-collect} is normally turned on to generate a list
2980 of folder names in the background as soon as mh-e is loaded.  Otherwise,
2981 the list is generated when you need a folder name the first time (as
2982 with @kbd{o} (@code{mh-refile-msg})).  If you have a lot of folders and
2983 you have @code{mh-recursive-folders} set, this could take a while, which
2984 is why it's nice to do the folder collection in the background.
2986 @vindex @code{mh-default-folder-for-message-function}
2987 @findex @code{mh-refile-msg}
2988 @findex @code{mh-to-fcc}
2989 @cindex @file{.emacs}
2990 @cindex files, @file{.emacs}
2992 The function @code{mh-default-folder-for-message-function} is used by
2993 @kbd{o} (@code{mh-refile-msg}) and @kbd{C-c C-f C-f} (@code{mh-to-fcc})
2994 to generate a default folder.  The generated folder name should be a
2995 string with a @samp{+} before it.  For each of my correspondents, I use the
2996 same name for both an alias and a folder.  So, I wrote a function that
2997 takes the address in the @samp{From:} header field, finds it in my alias
2998 file, and returns the alias, which is used as a default folder name.
2999 This is the most complicated example given here, and it demonstrates
3000 several features of Emacs Lisp programming.  You should be able to drop
3001 this into @file{~/.emacs}, however.  If you use this to store messages
3002 in a subfolder of your Mail directory, you can modify the line that
3003 starts @samp{(format +%s...}  and insert your subfolder after the folder
3004 symbol @samp{+}.
3005 @c Note for me: if I insert a new version, don't forget to remove the
3006 @c "a/" from the folder name.
3008 @iftex
3009 @filbreak
3010 @end iftex
3012 @vindex @code{mh-default-folder-for-message-function}, example
3013 @vindex @code{mh-user-path}, example
3015 @smallexample
3016 @group
3017 @i{Creating useful default folder for refiling via mh-default-folder-for-message-function}
3019 (defun my-mh-folder-from-address ()
3020   "Determine folder name from address.
3021 Takes the address in the From: header field, and returns its
3022 corresponding alias from the user's personal aliases file. Returns
3023 @code{nil} if the address was not found."
3024   (require 'rfc822)                         ; @r{for the rfc822 functions}
3025   (search-forward-regexp "^From: \\(.*\\)") ; @r{grab header field contents}
3026   (save-excursion                     ; @r{save state}
3027     (let ((addr (car (rfc822-addresses  ; @r{get address}
3028                       (buffer-substring (match-beginning 1)
3029                                         (match-end 1)))))
3030           (buffer (get-buffer-create " *temp*")) ; @r{set local variables}
3031           folder)
3032       (set-buffer buffer)             ; @r{jump to temporary buffer}
3033       (unwind-protect                 ; @r{run kill-buffer when done}
3034           (progn                      ; @r{function grouping construct}
3035             (insert-file-contents (expand-file-name "aliases"
3036                                                     mh-user-path))
3037             (goto-char (point-min))   ; @r{grab aliases file and go to start}
3038             (setq folder
3039                   ;; @r{Search for the given address, even commented-out}
3040                   ;; @r{addresses are found!}
3041                   ;; @r{The function search-forward-regexp sets values that}
3042                   ;; @r{are later used by match-beginning and match-end.}
3043                   (if (search-forward-regexp (format "^;*\\(.*\\):.*%s"
3044                                                      addr) nil t)
3045                       ;; @r{NOTE WELL: this is what the return value looks}
3046                       ;; @r{like. You can modify the format string to match}
3047                       ;; @r{your own Mail hierarchy.}
3048                       (format "+%s" (buffer-substring
3049                                       (match-beginning 1)
3050                                       (match-end 1))))))
3051         (kill-buffer buffer))          ; @r{get rid of our temporary buffer}
3052       folder)))                        ; @r{function's return value}
3054 (setq mh-default-folder-for-message-function 'my-mh-folder-from-address)
3055 @end group
3056 @end smallexample
3058 @vindex @code{mh-refile-msg-hook}
3060 The hook @code{mh-refile-msg-hook} is called after a message is marked
3061 to be refiled.
3063 @vindex @code{mh-sortm-args}
3064 @cindex @code{sortm}
3065 @cindex MH commands, @code{sortm}
3066 @findex @code{mh-sort-folder}
3067 @cindex MH profile components, @code{sortm}
3068 @cindex @file{.mh_profile}
3069 @cindex files, @file{.mh_profile}
3071 The variable @code{mh-sortm-args} holds extra arguments to pass on to
3072 the @code{sortm} command.  Note: this variable is only consulted when a
3073 prefix argument is given to @kbd{M-x mh-sort-folder}.  It is used to
3074 override any arguments given in a @code{sortm:} entry in your MH profile
3075 (@file{~/.mh_profile}).
3077 @menu
3078 * Customizing Scan Line Formats::
3079 @end menu
3081 @node Customizing Scan Line Formats,  , Customizing Organizing, Customizing Organizing
3082 @subsubsection Scan line formatting
3084 @vindex @code{mh-scan-prog}
3085 @cindex @code{scan}
3086 @cindex MH commands, @code{scan}
3087 @vindex @code{mh-progs}
3089 The name of the program that generates a listing of one line per message
3090 is held in @code{mh-scan-prog} (default: @samp{"scan"}).  Unless this
3091 variable contains an absolute pathname, it is assumed to be in the
3092 @code{mh-progs} directory.  You may link another program to @code{scan}
3093 (see @code{mh-profile}(5)) to produce a different type of listing.
3095 If you change the format of the scan lines you'll need to tell mh-e how
3096 to parse the new format.  As you see, quite a lot of variables are
3097 involved to do that.  The first variable has to do with pruning out
3098 garbage.
3100 @table @code
3101 @item mh-valid-scan-line
3102 @vindex @code{mh-valid-scan-line}
3103 @cindex @code{inc}
3104 @cindex MH commands, @code{inc}
3105 @cindex @code{scan}
3106 @cindex MH commands, @code{scan}
3107 This regular expression describes a valid scan line.  This is used to
3108 eliminate error messages that are occasionally produced by @code{inc} or
3109 @code{scan} (default: @samp{"^ *[0-9]"}).
3110 @end table
3112 Next, two variables control how the message numbers are parsed.
3114 @table @code
3116 @item mh-msg-number-regexp
3117 @vindex @code{mh-msg-number-regexp}
3118 This regular expression is used to extract the message number from a
3119 scan line.  Note that the message number must be placed in quoted
3120 parentheses, (\\(...\\)), as in the default of @w{@samp{"^
3121 *\\([0-9]+\\)"}}.
3123 @item mh-msg-search-regexp
3124 @vindex @code{mh-msg-search-regexp}
3125 Given a message number (which is inserted in @samp{%d}), this regular
3126 expression will match the scan line that it represents (default:
3127 @samp{"^[^0-9]*%d[^0-9]"}).
3128 @end table
3130 Finally, there are a slew of variables that control how mh-e marks up
3131 the scan lines.
3133 @table @code
3134 @item mh-cmd-note
3135 @vindex @code{mh-cmd-note}
3136 Number of characters to skip over before inserting notation (default:
3137 4).  Note how it relates to the following regular expressions.
3139 @item mh-deleted-msg-regexp
3140 @vindex @code{mh-deleted-msg-regexp}
3141 This regular expression describes deleted messages (default:
3142 @samp{"^....D"}).  See also @code{mh-note-deleted}.
3144 @item mh-refiled-msg-regexp
3145 @vindex @code{mh-refiled-msg-regexp}
3146 This regular expression describes refiled messages (default:
3147 @samp{"^....\\^"}).  See also @code{mh-note-refiled}.
3149 @item mh-cur-scan-msg-regexp
3150 @vindex @code{mh-cur-scan-msg-regexp}
3151 This regular expression matches the current message (default:
3152 @samp{"^....\\+"}).  See also @code{mh-note-cur}.
3154 @item mh-good-msg-regexp
3155 @vindex @code{mh-good-msg-regexp}
3156 This regular expression describes which messages should be shown when
3157 mh-e goes to the next or previous message.  Normally, deleted or refiled
3158 messages are skipped over (default: @samp{"^....[^D^]"}).
3160 @item mh-note-deleted
3161 @vindex @code{mh-note-deleted}
3162 Messages that have been deleted to are marked by this string (default:
3163 @samp{"D"}).  See also @code{mh-deleted-msg-regexp}.
3165 @item mh-note-refiled
3166 @vindex @code{mh-note-refiled}
3167 Messages that have been refiled are marked by this string (default:
3168 @samp{"^"}).  See also @code{mh-refiled-msg-regexp}.
3170 @item mh-note-copied
3171 @vindex @code{mh-note-copied}
3172 Messages that have been copied are marked by this string (default:
3173 @samp{"C"}).
3175 @item mh-note-cur
3176 @vindex @code{mh-note-cur}
3177 The current message (in MH, not in mh-e) is marked by this string
3178 (default: @samp{"+"}).  See also @code{mh-cur-scan-msg-regexp}.
3180 @item mh-note-repl
3181 @vindex @code{mh-note-repl}
3182 Messages that have been replied to are marked by this string (default:
3183 @samp{"-"}).
3185 @item mh-note-forw
3186 @vindex @code{mh-note-forw}
3187 Messages that have been forwarded are marked by this string (default:
3188 @samp{"F"}).
3190 @item mh-note-dist
3191 @vindex @code{mh-note-dist}
3192 Messages that have been redistributed are marked by this string
3193 (default: @samp{"R"}).
3195 @item mh-note-printed
3196 @vindex @code{mh-note-printed}
3197 Messages that have been printed are marked by this string (default:
3198 @samp{"P"}).
3200 @item mh-note-seq
3201 @vindex @code{mh-note-seq}
3202 Messages in a sequence are marked by this string (default: @samp{"%"}).
3203 @end table
3205 @node Customizing Printing, Customizing Files and Pipes, Customizing Organizing, Customizing Moving Mail
3206 @subsection Printing Your Mail
3208 @cindex printing
3209 @vindex @code{mh-print-background}
3210 @vindex @code{mh-lpr-command-format}
3211 @cindex @code{lpr}
3212 @cindex Unix commands, @code{lpr}
3214 Normally messages are printed in the foreground.  If this is slow on
3215 your system, you may elect to set @code{mh-print-background} to
3216 non-@code{nil} to print in the background.  If you do this, do not delete
3217 the message until it is printed or else the output may be truncated.
3218 The variable @code{mh-lpr-command-format} controls how the printing is
3219 actually done.  The string can contain one escape, @samp{%s}, which is
3220 filled with the name of the folder and the message number and is useful
3221 for print job names.  As an example, the default is @samp{"lpr -J
3222 '%s'"}.
3224 @node Customizing Files and Pipes, Customizing Finishing Up, Customizing Printing, Customizing Moving Mail
3225 @subsection Files and Pipes
3227 @cindex using files
3228 @cindex using pipes
3229 @findex @code{mh-store-msg}
3230 @vindex @code{mh-store-default-directory}
3232 The initial directory for the @code{mh-store-msg} command is held in
3233 @code{mh-store-default-directory}.  Since I almost always run
3234 @code{mh-store-msg} on sources, I set it to my personal source directory
3235 like this:
3237 @vindex @code{mh-store-default-directory}, example
3239 @lisp
3240 (setq mh-store-default-directory (expand-file-name "~/src/"))
3241 @end lisp
3243 @findex @code{mh-store-buffer}
3244 @cindex @code{uuencode}
3245 @cindex Unix commands, @code{uuencode}
3246 @cindex @code{shar}
3247 @cindex Unix commands, @code{shar}
3249 Subsequent incarnations of @code{mh-store-msg} offer the last directory
3250 used as the default.  By the way, @code{mh-store-msg} calls the Emacs
3251 Lisp function @code{mh-store-buffer}.  I mention this because you can use
3252 it directly if you're editing a buffer that contains a file that has
3253 been run through @code{uuencode} or @code{shar}.  For example, you can
3254 extract the contents of the current buffer in your home directory by
3255 typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}.
3257 @node Customizing Finishing Up,  , Customizing Files and Pipes, Customizing Moving Mail
3258 @subsection Finishing Up
3260 @cindex quitting
3261 @vindex @code{mh-before-quit-hook}
3262 @vindex @code{mh-quit-hook}
3263 @findex @code{mh-execute-commands}
3265 The two variables @code{mh-before-quit-hook} and @code{mh-quit-hook} are
3266 called by @kbd{q} (@code{mh-quit}).  The former one is called before the
3267 quit occurs, so you might use it to perform any mh-e operations; you
3268 could perform some query and abort the quit or call
3269 @code{mh-execute-commands}, for example.  The latter is not run in an
3270 mh-e context, so you might use it to modify the window setup.
3272 @node Customizing Searching,  , Customizing Moving Mail, Customizing mh-e
3273 @section Searching Through Messages
3275 @cindex searching
3276 @vindex @code{mh-pick-mode-hook}
3277 @vindex @code{mh-partial-folder-mode-line-annotation}
3279 If you find that you do the same thing over and over when editing the
3280 search template, you may wish to bind some shortcuts to keys.  This can
3281 be done with the variable @code{mh-pick-mode-hook}, which is called when
3282 @kbd{M-s} (@code{mh-search-folder}) is run on a new pattern.
3284 The string
3285 @code{mh-partial-folder-mode-line-annotation} is used to annotate the
3286 mode line when only a portion of the folder is shown.  For example, this
3287 will be displayed after running @kbd{M-s} (@code{mh-search-folder}) to
3288 list messages based on some search criteria (see @ref{Searching}).  The
3289 default annotation of @samp{"select"} yields a mode line that looks
3290 like:
3292 @example
3293 --%%-@{+inbox/select@} 2 msgs (2-3)      (MH-Folder)--All-----------------
3294 @end example
3296 @node Odds and Ends, History, Customizing mh-e, Top
3297 @appendix Odds and Ends
3299 This appendix covers a few topics that don't fit elsewhere.  Here I tell
3300 you how to report bugs and how to get on the mh-e mailing list.  I also
3301 point out some additional sources of information.
3303 @menu
3304 * Bug Reports::
3305 * Mailing List::
3306 * MH FAQ::
3307 * Getting mh-e::
3308 @end menu
3310 @node Bug Reports, Mailing List, Odds and Ends, Odds and Ends
3311 @appendixsec Bug Reports
3313 @cindex bugs
3314 @cindex Wohler, Bill
3315 @cindex SourceForge
3317 The current maintainer of mh-e is Bill Wohler
3318 <@i{wohler@@newt.com}>. Bug reports should be filed at
3319 @uref{https://sourceforge.net/bugs/?group_id=13357, SourceForge}.
3320 Please include the output of
3321 @kbd{M-x mh-version} (@pxref{Miscellaneous}) in any bug report you send.
3323 @node Mailing List, MH FAQ, Bug Reports, Odds and Ends
3324 @appendixsec mh-e Mailing List
3326 @cindex mailing list
3327 @cindex SourceForge
3329 There are actually several mailing lists for mh-e. They are
3330 @i{mh-e-users@@lists.sourceforge.net},
3331 @i{mh-e-announce@@lists.sourceforge.net}, and
3332 @i{mh-e-devel@@lists.sourceforge.net}. You can subscribe or view the
3333 archives at @uref{https://sourceforge.net/mail/?group_id=13357,
3334 SourceForge}. Do not report bugs on these lists; please submit them
3335 via SourceForge (@pxref{Bug Reports}).
3337 @node MH FAQ, Getting mh-e, Mailing List, Odds and Ends
3338 @appendixsec MH FAQ
3340 @cindex MH FAQ
3341 @cindex FAQ
3343 An FAQ appears monthly in the newsgroup @samp{comp.mail.mh}.  While very
3344 little is there that deals with mh-e specifically, there is an
3345 incredible wealth of material about MH itself which you will find
3346 useful.  The subject of the FAQ is @cite{MH Frequently Asked Questions
3347 (FAQ) with Answers}.
3349 The FAQ is available via the World Wide Web (WWW) at
3350 @uref{http://www.faqs.org/faqs/mail/mh-faq/part1/preamble.html, faqs.org}.
3352 @node Getting mh-e,  , MH FAQ, Odds and Ends
3353 @appendixsec Getting mh-e
3355 @cindex obtaining mh-e
3357 The version of mh-e in the current version of Emacs should be up to
3358 date. It is most likely to be more up to date than the copy that comes
3359 with the MH distribution in @file{miscellany/mh-e}.
3361 @c intentionally wordy to avoid overfull hbox
3362 New mh-e releases are always available for downloading at
3363 @uref{https://sourceforge.net/project/showfiles.php?group_id=13357,
3364 SourceForge} before they appear in an Emacs release. You can read the
3365 release notes on that page to determine if the given release of mh-e
3366 is already installed in your version of Emacs.
3368 If you go this route, I suggest that you extract the files from
3369 @file{mh-e-@var{m.n}.tgz} in the following fashion:
3371 @smallexample
3372 @group
3373 % @kbd{cd}                                  # @r{Start in your home directory}
3374 % @kbd{mkdir lib lib/emacs}                 # @r{Create directory for mh-e}
3375 % @kbd{cd lib/emacs}
3376 % @kbd{zcat @var{path/to/}mh-e-@var{m.n}.tgz | tar xvf -}    # @r{Extract files}
3377 @end group
3378 @end smallexample
3380 @cindex @file{.emacs}
3381 @cindex files, @file{.emacs}
3383 To use these new files, add the following to @file{~/.emacs}:
3385 @lisp
3386 (setq load-path (cons (expand-file-name "~/lib/emacs") load-path))
3387 @end lisp
3389 @cindex news
3390 @cindex files, @samp{MH-E-NEWS}
3392 That's it!  If you're already running Emacs, please quit that session
3393 and start again to load in the new mh-e.  Check that you're running the
3394 new version with the command @kbd{M-x mh-version} after running any mh-e
3395 command.  The distribution comes with a file called @file{MH-E-NEWS} so
3396 you can see what's new.
3398 @node    History, Copying, Odds and Ends, Top
3399 @appendix History of mh-e
3401 @cindex Gildea, Stephen
3402 @cindex Larus, Jim
3403 @cindex Reid, Brian
3404 @cindex SourceForge
3405 @cindex history of mh-e
3407 mh-e was originally written by Brian Reid in 1983 and has changed
3408 hands several times since then. Jim Larus wanted to do something
3409 similar for GNU Emacs, and ended up completely rewriting it that same
3410 year. In 1989, Stephen Gildea picked it up and added many improvements.
3411 Bill Wohler then took over in 2000 and moved its development to
3412 @uref{http://sourceforge.net/, SourceForge}.
3414 @menu
3415 * From Brian Reid::
3416 * From Jim Larus::
3417 * From Stephen Gildea::
3418 @end menu
3420 @node From Brian Reid, From Jim Larus, History, History
3421 @appendixsec From Brian Reid
3423 @cindex Reid, Brian
3425 One day in 1983 I got the flu and had to stay home from work for three
3426 days with nothing to do.  I used that time to write MHE@.  The
3427 fundamental idea behind MHE was that it was a ``puppeteer'' driving the MH
3428 programs underneath it.  MH had a model that the editor was supposed to
3429 run as a subprocess of the mailer, which seemed to me at the time to be
3430 the tail wagging the dog.  So I turned it around and made the editor
3431 drive the MH programs.  I made sure that the UCI people (who were
3432 maintaining MH at the time) took in my changes and made them stick.
3434 Today, I still use my own version of MHE because I don't at all like the
3435 way that GNU mh-e works and I've never gotten to be good enough at
3436 hacking Emacs Lisp to make GNU mh-e do what I want.  The Gosling-emacs
3437 version of MHE and the GNU Emacs version of mh-e have almost nothing in
3438 common except similar names.  They work differently, have different
3439 conceptual models, and have different key bindings.  @footnote{After
3440 reading this article, I questioned Brian about his version of MHE, and
3441 received some great ideas for improving mh-e such as a dired-like method
3442 of selecting folders; and removing the prompting when sending mail,
3443 filling in the blanks in the draft buffer instead.  I passed them on to
3444 Stephen Gildea, the current maintainer, and he was excited about the
3445 ideas as well.  Perhaps one day, mh-e will again resemble MHE, although
3446 none of these ideas are manifest in Version 5.0.}
3448 Brian Reid, June 1994
3450 @node From Jim Larus, From Stephen Gildea, From Brian Reid, History
3451 @appendixsec From Jim Larus
3453 @cindex Larus, Jim
3455 Brian Reid, while at CMU or shortly after going to Stanford wrote a mail
3456 reading program called MHE for Gosling Emacs.  It had much the same
3457 structure as mh-e (i.e., invoked MH programs), though it was simpler and
3458 the commands were slightly different.  Unfortunately, I no longer have a
3459 copy so the differences are lost in the mists of time.
3461 In '82-83, I was working at BBN and wrote a lot of mlisp code in Gosling
3462 Emacs to make it look more like Tennex Emacs.  One of the packages that
3463 I picked up and improved was Reid's mail system.  In '83, I went back to
3464 Berkeley.  About that time, Stallman's first version of GNU Emacs came
3465 out and people started to move to it from Gosling Emacs (as I recall,
3466 the transition took a year or two).  I decided to port Reid's MHE and
3467 used the mlisp to Emacs Lisp translator that came with GNU Emacs.  It
3468 did a lousy job and the resulting code didn't work, so I bit the bullet
3469 and rewrote the code by hand (it was a lot smaller and simpler then, so
3470 it took only a day or two).
3472 Soon after that, mh-e became part of the standard Emacs distribution and
3473 suggestions kept dribbling in for improvements.  mh-e soon reached
3474 sufficient functionality to keep me happy, but I kept on improving it
3475 because I was a graduate student with plenty of time on my hands and it
3476 was more fun than my dissertation.  In retrospect, the one thing that I
3477 regret is not writing any documentation, which seriously limited the use
3478 and appeal of the package.
3480 @cindex @code{xmh}, in mh-e history
3482 In '89, I came to Wisconsin as a professor and decided not to work on
3483 mh-e.  It was stable, except for minor bugs, and had enough
3484 functionality, so I let it be for a few years.  Stephen Gildea of BBN
3485 began to pester me about the bugs, but I ignored them.  In 1990, he went
3486 off to the X Consortium, said good bye, and said that he would now be
3487 using @code{xmh}.  A few months later, he came back and said that he
3488 couldn't stand @code{xmh} and could I put a few more bug fixes into
3489 mh-e.  At that point, I had no interest in fixing mh-e, so I gave the
3490 responsibility of maintenance to him and he has done a fine job since
3491 then.
3493 Jim Larus, June 1994
3495 @node From Stephen Gildea,  , From Jim Larus, History
3496 @appendixsec From Stephen Gildea
3498 @cindex Gildea, Stephen
3500 In 1987 I went to work for Bolt Beranek and Newman, as Jim had before
3501 me.  In my previous job, I had been using RMAIL, but as my folders tend
3502 to run large, I was frustrated with the speed of RMAIL@.  However, I
3503 stuck with it because I wanted the GNU Emacs interface.  I am very
3504 familiar and comfortable with the Emacs interface (with just a few
3505 modifications of my own) and dislike having to use applications with
3506 embedded editors; they never live up to Emacs.
3508 MH is the mail reader of choice at BBN, so I converted to it.  Since I
3509 didn't want to give up using an Emacs interface, I started using mh-e.
3510 As is my wont, I started hacking on it almost immediately.  I first used
3511 version 3.4m.  One of the first features I added was to treat the folder
3512 buffer as a file-visiting buffer: you could lock it, save it, and be
3513 warned of unsaved changes when killing it.  I also worked to bring its
3514 functionality a little closer to RMAIL@.  Jim Larus was very cooperative
3515 about merging in my changes, and my efforts first appeared in version
3516 3.6, distributed with Emacs 18.52 in 1988.  Next I decided mh-e was too
3517 slow and optimized it a lot.  Version, 3.7, distributed with Emacs 18.56
3518 in 1990, was noticeably faster.
3520 When I moved to the X Consortium I became the first person there to not
3521 use xmh.  (There is now one other engineer there using mh-e.)  About
3522 this point I took over maintenance of mh-e from Jim and was finally able
3523 to add some features Jim hadn't accepted, such as the backward searching
3524 undo.  My first release was 3.8 (Emacs 18.58) in 1992.
3526 Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0.
3527 Version 4.0 added many new features, including background folder
3528 collection and support for composing @sc{mime} messages.  (Reading
3529 @sc{mime} messages remains to be done, alas.)  While writing this book,
3530 Bill Wohler gave mh-e its closest examination ever, uncovering bugs and
3531 inconsistencies that required a new major version to fix, and so version
3532 5 was released.
3534 Stephen Gildea, June 1994
3536 @node Copying, Command Index, History, Top
3537 @appendix GNU GENERAL PUBLIC LICENSE
3539 @center Version 2, June 1991
3541 @display
3542 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
3543 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
3545 Everyone is permitted to copy and distribute verbatim copies
3546 of this license document, but changing it is not allowed.
3547 @end display
3549 @appendixsec Preamble
3551   The licenses for most software are designed to take away your
3552 freedom to share and change it.  By contrast, the GNU General Public
3553 License is intended to guarantee your freedom to share and change free
3554 software---to make sure the software is free for all its users.  This
3555 General Public License applies to most of the Free Software
3556 Foundation's software and to any other program whose authors commit to
3557 using it.  (Some other Free Software Foundation software is covered by
3558 the GNU Library General Public License instead.)  You can apply it to
3559 your programs, too.
3561   When we speak of free software, we are referring to freedom, not
3562 price.  Our General Public Licenses are designed to make sure that you
3563 have the freedom to distribute copies of free software (and charge for
3564 this service if you wish), that you receive source code or can get it
3565 if you want it, that you can change the software or use pieces of it
3566 in new free programs; and that you know you can do these things.
3568   To protect your rights, we need to make restrictions that forbid
3569 anyone to deny you these rights or to ask you to surrender the rights.
3570 These restrictions translate to certain responsibilities for you if you
3571 distribute copies of the software, or if you modify it.
3573   For example, if you distribute copies of such a program, whether
3574 gratis or for a fee, you must give the recipients all the rights that
3575 you have.  You must make sure that they, too, receive or can get the
3576 source code.  And you must show them these terms so they know their
3577 rights.
3579   We protect your rights with two steps: (1) copyright the software, and
3580 (2) offer you this license which gives you legal permission to copy,
3581 distribute and/or modify the software.
3583   Also, for each author's protection and ours, we want to make certain
3584 that everyone understands that there is no warranty for this free
3585 software.  If the software is modified by someone else and passed on, we
3586 want its recipients to know that what they have is not the original, so
3587 that any problems introduced by others will not reflect on the original
3588 authors' reputations.
3590   Finally, any free program is threatened constantly by software
3591 patents.  We wish to avoid the danger that redistributors of a free
3592 program will individually obtain patent licenses, in effect making the
3593 program proprietary.  To prevent this, we have made it clear that any
3594 patent must be licensed for everyone's free use or not licensed at all.
3596   The precise terms and conditions for copying, distribution and
3597 modification follow.
3599 @iftex
3600 @appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3601 @end iftex
3602 @ifinfo
3603 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
3604 @end ifinfo
3606 @enumerate 0
3607 @item
3608 This License applies to any program or other work which contains
3609 a notice placed by the copyright holder saying it may be distributed
3610 under the terms of this General Public License.  The ``Program,'' below,
3611 refers to any such program or work, and a ``work based on the Program''
3612 means either the Program or any derivative work under copyright law:
3613 that is to say, a work containing the Program or a portion of it,
3614 either verbatim or with modifications and/or translated into another
3615 language.  (Hereinafter, translation is included without limitation in
3616 the term ``modification.'')  Each licensee is addressed as ``you.''
3618 Activities other than copying, distribution and modification are not
3619 covered by this License; they are outside its scope.  The act of
3620 running the Program is not restricted, and the output from the Program
3621 is covered only if its contents constitute a work based on the
3622 Program (independent of having been made by running the Program).
3623 Whether that is true depends on what the Program does.
3625 @item
3626 You may copy and distribute verbatim copies of the Program's
3627 source code as you receive it, in any medium, provided that you
3628 conspicuously and appropriately publish on each copy an appropriate
3629 copyright notice and disclaimer of warranty; keep intact all the
3630 notices that refer to this License and to the absence of any warranty;
3631 and give any other recipients of the Program a copy of this License
3632 along with the Program.
3634 You may charge a fee for the physical act of transferring a copy, and
3635 you may at your option offer warranty protection in exchange for a fee.
3637 @item
3638 You may modify your copy or copies of the Program or any portion
3639 of it, thus forming a work based on the Program, and copy and
3640 distribute such modifications or work under the terms of Section 1
3641 above, provided that you also meet all of these conditions:
3643 @enumerate a
3644 @item
3645 You must cause the modified files to carry prominent notices
3646 stating that you changed the files and the date of any change.
3648 @item
3649 You must cause any work that you distribute or publish, that in
3650 whole or in part contains or is derived from the Program or any
3651 part thereof, to be licensed as a whole at no charge to all third
3652 parties under the terms of this License.
3654 @item
3655 If the modified program normally reads commands interactively
3656 when run, you must cause it, when started running for such
3657 interactive use in the most ordinary way, to print or display an
3658 announcement including an appropriate copyright notice and a
3659 notice that there is no warranty (or else, saying that you provide
3660 a warranty) and that users may redistribute the program under
3661 these conditions, and telling the user how to view a copy of this
3662 License.  (Exception: if the Program itself is interactive but
3663 does not normally print such an announcement, your work based on
3664 the Program is not required to print an announcement.)
3665 @end enumerate
3667 These requirements apply to the modified work as a whole.  If
3668 identifiable sections of that work are not derived from the Program,
3669 and can be reasonably considered independent and separate works in
3670 themselves, then this License, and its terms, do not apply to those
3671 sections when you distribute them as separate works.  But when you
3672 distribute the same sections as part of a whole which is a work based
3673 on the Program, the distribution of the whole must be on the terms of
3674 this License, whose permissions for other licensees extend to the
3675 entire whole, and thus to each and every part regardless of who wrote it.
3677 Thus, it is not the intent of this section to claim rights or contest
3678 your rights to work written entirely by you; rather, the intent is to
3679 exercise the right to control the distribution of derivative or
3680 collective works based on the Program.
3682 In addition, mere aggregation of another work not based on the Program
3683 with the Program (or with a work based on the Program) on a volume of
3684 a storage or distribution medium does not bring the other work under
3685 the scope of this License.
3687 @item
3688 You may copy and distribute the Program (or a work based on it,
3689 under Section 2) in object code or executable form under the terms of
3690 Sections 1 and 2 above provided that you also do one of the following:
3692 @enumerate a
3693 @item
3694 Accompany it with the complete corresponding machine-readable
3695 source code, which must be distributed under the terms of Sections
3696 1 and 2 above on a medium customarily used for software interchange; or,
3698 @item
3699 Accompany it with a written offer, valid for at least three
3700 years, to give any third party, for a charge no more than your
3701 cost of physically performing source distribution, a complete
3702 machine-readable copy of the corresponding source code, to be
3703 distributed under the terms of Sections 1 and 2 above on a medium
3704 customarily used for software interchange; or,
3706 @item
3707 Accompany it with the information you received as to the offer
3708 to distribute corresponding source code.  (This alternative is
3709 allowed only for noncommercial distribution and only if you
3710 received the program in object code or executable form with such
3711 an offer, in accord with Subsection b above.)
3712 @end enumerate
3714 The source code for a work means the preferred form of the work for
3715 making modifications to it.  For an executable work, complete source
3716 code means all the source code for all modules it contains, plus any
3717 associated interface definition files, plus the scripts used to
3718 control compilation and installation of the executable.  However, as a
3719 special exception, the source code distributed need not include
3720 anything that is normally distributed (in either source or binary
3721 form) with the major components (compiler, kernel, and so on) of the
3722 operating system on which the executable runs, unless that component
3723 itself accompanies the executable.
3725 If distribution of executable or object code is made by offering
3726 access to copy from a designated place, then offering equivalent
3727 access to copy the source code from the same place counts as
3728 distribution of the source code, even though third parties are not
3729 compelled to copy the source along with the object code.
3731 @item
3732 You may not copy, modify, sublicense, or distribute the Program
3733 except as expressly provided under this License.  Any attempt
3734 otherwise to copy, modify, sublicense or distribute the Program is
3735 void, and will automatically terminate your rights under this License.
3736 However, parties who have received copies, or rights, from you under
3737 this License will not have their licenses terminated so long as such
3738 parties remain in full compliance.
3740 @item
3741 You are not required to accept this License, since you have not
3742 signed it.  However, nothing else grants you permission to modify or
3743 distribute the Program or its derivative works.  These actions are
3744 prohibited by law if you do not accept this License.  Therefore, by
3745 modifying or distributing the Program (or any work based on the
3746 Program), you indicate your acceptance of this License to do so, and
3747 all its terms and conditions for copying, distributing or modifying
3748 the Program or works based on it.
3750 @item
3751 Each time you redistribute the Program (or any work based on the
3752 Program), the recipient automatically receives a license from the
3753 original licensor to copy, distribute or modify the Program subject to
3754 these terms and conditions.  You may not impose any further
3755 restrictions on the recipients' exercise of the rights granted herein.
3756 You are not responsible for enforcing compliance by third parties to
3757 this License.
3759 @item
3760 If, as a consequence of a court judgment or allegation of patent
3761 infringement or for any other reason (not limited to patent issues),
3762 conditions are imposed on you (whether by court order, agreement or
3763 otherwise) that contradict the conditions of this License, they do not
3764 excuse you from the conditions of this License.  If you cannot
3765 distribute so as to satisfy simultaneously your obligations under this
3766 License and any other pertinent obligations, then as a consequence you
3767 may not distribute the Program at all.  For example, if a patent
3768 license would not permit royalty-free redistribution of the Program by
3769 all those who receive copies directly or indirectly through you, then
3770 the only way you could satisfy both it and this License would be to
3771 refrain entirely from distribution of the Program.
3773 If any portion of this section is held invalid or unenforceable under
3774 any particular circumstance, the balance of the section is intended to
3775 apply and the section as a whole is intended to apply in other
3776 circumstances.
3778 It is not the purpose of this section to induce you to infringe any
3779 patents or other property right claims or to contest validity of any
3780 such claims; this section has the sole purpose of protecting the
3781 integrity of the free software distribution system, which is
3782 implemented by public license practices.  Many people have made
3783 generous contributions to the wide range of software distributed
3784 through that system in reliance on consistent application of that
3785 system; it is up to the author/donor to decide if he or she is willing
3786 to distribute software through any other system and a licensee cannot
3787 impose that choice.
3789 This section is intended to make thoroughly clear what is believed to
3790 be a consequence of the rest of this License.
3792 @item
3793 If the distribution and/or use of the Program is restricted in
3794 certain countries either by patents or by copyrighted interfaces, the
3795 original copyright holder who places the Program under this License
3796 may add an explicit geographical distribution limitation excluding
3797 those countries, so that distribution is permitted only in or among
3798 countries not thus excluded.  In such case, this License incorporates
3799 the limitation as if written in the body of this License.
3801 @item
3802 The Free Software Foundation may publish revised and/or new versions
3803 of the General Public License from time to time.  Such new versions will
3804 be similar in spirit to the present version, but may differ in detail to
3805 address new problems or concerns.
3807 Each version is given a distinguishing version number.  If the Program
3808 specifies a version number of this License which applies to it and ``any
3809 later version,'' you have the option of following the terms and conditions
3810 either of that version or of any later version published by the Free
3811 Software Foundation.  If the Program does not specify a version number of
3812 this License, you may choose any version ever published by the Free Software
3813 Foundation.
3815 @item
3816 If you wish to incorporate parts of the Program into other free
3817 programs whose distribution conditions are different, write to the author
3818 to ask for permission.  For software which is copyrighted by the Free
3819 Software Foundation, write to the Free Software Foundation; we sometimes
3820 make exceptions for this.  Our decision will be guided by the two goals
3821 of preserving the free status of all derivatives of our free software and
3822 of promoting the sharing and reuse of software generally.
3824 @iftex
3825 @heading NO WARRANTY
3826 @end iftex
3827 @ifinfo
3828 @center NO WARRANTY
3829 @end ifinfo
3831 @item
3832 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
3833 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
3834 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
3835 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
3836 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
3837 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
3838 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
3839 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
3840 REPAIR OR CORRECTION.
3842 @item
3843 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
3844 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
3845 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
3846 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
3847 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
3848 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
3849 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
3850 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
3851 POSSIBILITY OF SUCH DAMAGES.
3852 @end enumerate
3854 @iftex
3855 @heading END OF TERMS AND CONDITIONS
3856 @end iftex
3857 @ifinfo
3858 @center END OF TERMS AND CONDITIONS
3859 @end ifinfo
3861 @page
3862 @appendixsec How to Apply These Terms to Your New Programs
3864   If you develop a new program, and you want it to be of the greatest
3865 possible use to the public, the best way to achieve this is to make it
3866 free software which everyone can redistribute and change under these terms.
3868   To do so, attach the following notices to the program.  It is safest
3869 to attach them to the start of each source file to most effectively
3870 convey the exclusion of warranty; and each file should have at least
3871 the ``copyright'' line and a pointer to where the full notice is found.
3873 @smallexample
3874 @var{one line to give the program's name and an idea of what it does.}
3875 Copyright (C) 20@var{yy}  @var{name of author}
3877 This program is free software; you can redistribute it and/or
3878 modify it under the terms of the GNU General Public License
3879 as published by the Free Software Foundation; either version 2
3880 of the License, or (at your option) any later version.
3882 This program is distributed in the hope that it will be useful,
3883 but WITHOUT ANY WARRANTY; without even the implied warranty of
3884 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
3885 GNU General Public License for more details.
3887 You should have received a copy of the GNU General Public License along
3888 with this program; if not, write to the Free Software Foundation, Inc.,
3889 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
3890 @end smallexample
3892 Also add information on how to contact you by electronic and paper mail.
3894 If the program is interactive, make it output a short notice like this
3895 when it starts in an interactive mode:
3897 @smallexample
3898 Gnomovision version 69, Copyright (C) 20@var{yy} @var{name of author}
3899 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
3900 type `show w'.  This is free software, and you are welcome
3901 to redistribute it under certain conditions; type `show c'
3902 for details.
3903 @end smallexample
3905 The hypothetical commands @samp{show w} and @samp{show c} should show
3906 the appropriate parts of the General Public License.  Of course, the
3907 commands you use may be called something other than @samp{show w} and
3908 @samp{show c}; they could even be mouse-clicks or menu items---whatever
3909 suits your program.
3911 You should also get your employer (if you work as a programmer) or your
3912 school, if any, to sign a ``copyright disclaimer'' for the program, if
3913 necessary.  Here is a sample; alter the names:
3915 @smallexample
3916 @group
3917 Yoyodyne, Inc., hereby disclaims all copyright
3918 interest in the program `Gnomovision'
3919 (which makes passes at compilers) written
3920 by James Hacker.
3922 @var{signature of Ty Coon}, 1 April 1989
3923 Ty Coon, President of Vice
3924 @end group
3925 @end smallexample
3927 This General Public License does not permit incorporating your program into
3928 proprietary programs.  If your program is a subroutine library, you may
3929 consider it more useful to permit linking proprietary applications with the
3930 library.  If this is what you want to do, use the GNU Library General
3931 Public License instead of this License.
3933 @node    Command Index, Variable Index, Copying, Top
3934 @unnumbered Command Index
3936 @printindex fn
3938 @node    Variable Index, Concept Index, Command Index, Top
3939 @unnumbered Variable Index
3941 @printindex vr
3943 @node    Concept Index,  , Variable Index, Top
3944 @unnumbered Concept Index
3946 @printindex cp
3948 @contents
3949 @bye
3951 @c XXX In the sections on customizing mh-e, you can add cross-references
3952 @c to the Emacs manual and the Emacs Lisp manual wherever they are
3953 @c useful. @pxref{node, , section, emacs, The GNU Emacs Manual}
3955 @ignore
3956    arch-tag: b778477d-1a10-4a99-84de-f877a2ea6bef
3957 @end ignore