Andreas Krennmair:
[apps/madmutt.git] / doc / manual.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <title>The Mutt E-Mail Client
6 <author>by Michael Elkins <htmlurl url="mailto:me@cs.hmc.edu" name="&lt;me@cs.hmc.edu&gt;">
7 <date>version 1.5.6
8 <abstract>
9 ``All mail clients suck.  This one just sucks less.'' -me, circa 1995
10 </abstract>
11
12 <toc>
13
14 <sect>Introduction
15 <p>
16 <bf/Mutt/ is a small but very powerful text-based MIME mail client.  Mutt is
17 highly configurable, and is well suited to the mail power user with advanced
18 features like key bindings, keyboard macros, mail threading, regular
19 expression searches and a powerful pattern matching language for selecting
20 groups of messages.
21
22 <sect1>Mutt Home Page
23 <p>
24 <htmlurl url="http://www.mutt.org/"
25 name="http://www.mutt.org/">
26
27 <sect1>Mailing Lists
28 <p>
29 To subscribe to one of the following mailing lists, send a message with the
30 word <em/subscribe/ in the body to
31 <tt/list-name/<em/-request/<tt/@mutt.org/.
32
33 <itemize>
34 <item><htmlurl url="mailto:mutt-announce-request@mutt.org"
35 name="mutt-announce@mutt.org"> -- low traffic list for announcements
36 <item><htmlurl url="mailto:mutt-users-request@mutt.org"
37 name="mutt-users@mutt.org"> -- help, bug reports and feature requests
38 <item><htmlurl url="mailto:mutt-dev-request@mutt.org" name="mutt-dev@mutt.org"> -- development mailing list
39 </itemize>
40
41 <bf/Note:/ all messages posted to <em/mutt-announce/ are automatically
42 forwarded to <em/mutt-users/, so you do not need to be subscribed to both
43 lists.
44
45 <sect1>Software Distribution Sites
46 <p>
47 <itemize>
48 <item><htmlurl url="ftp://ftp.mutt.org/mutt/"
49 name="ftp://ftp.mutt.org/mutt/">
50 </itemize>
51 <p>
52 For a list of mirror sites, please refer to <htmlurl
53 url="http://www.mutt.org/download.html"
54 name="http://www.mutt.org/download.html">.
55
56 <sect1>IRC
57 <p>
58 Visit channel <em/#mutt/ on <htmlurl
59 url="http://www.openprojects.net" name="OpenProjects.Net
60 (www.openprojects.net)"> to chat with other people interested in Mutt.
61
62 <sect1>USENET
63 <p>
64 See the newsgroup <htmlurl url="news:comp.mail.mutt" name="comp.mail.mutt">.
65
66 <sect1>Copyright
67 <p>
68 Mutt is Copyright (C) 1996-2000 Michael R. Elkins
69 &lt;me@cs.hmc.edu&gt; and others
70
71 This program is free software; you can redistribute it and/or modify
72 it under the terms of the GNU General Public License as published by
73 the Free Software Foundation; either version 2 of the License, or
74 (at your option) any later version.
75
76 This program is distributed in the hope that it will be useful,
77 but WITHOUT ANY WARRANTY; without even the implied warranty of
78 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
79 GNU General Public License for more details.
80
81 You should have received a copy of the GNU General Public License
82 along with this program; if not, write to the Free Software
83 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
84
85 <sect>Getting Started
86 <p>
87
88 This section is intended as a brief overview of how to use Mutt.  There are
89 many other features which are described elsewhere in the manual.  There
90 is even more information available in the Mutt FAQ and various web
91 pages.  See the <htmlurl url="http://www.mutt.org/mutt/"
92 name="Mutt Page"> for more details.
93
94 The keybindings described in this section are the defaults as distributed.
95 Your local system administrator may have altered the defaults for your site.
96 You can always type ``?'' in any menu to display the current bindings.
97
98 The first thing you need to do is invoke mutt, simply by typing mutt
99 at the command line.  There are various command-line options, see 
100 either the mutt man page or the <ref id="commandline" name="reference">.
101
102 <sect1>Moving Around in Menus
103 <p>
104
105 Information is presented in menus, very similar to ELM.  Here is a table
106 showing the common keys used to navigate menus in Mutt.
107
108 <tscreen><verb>
109 j or Down       next-entry      move to the next entry
110 k or Up         previous-entry  move to the previous entry
111 z or PageDn     page-down       go to the next page
112 Z or PageUp     page-up         go to the previous page
113 = or Home       first-entry     jump to the first entry
114 * or End        last-entry      jump to the last entry
115 q               quit            exit the current menu
116 ?               help            list all keybindings for the current menu
117 </verb></tscreen>
118
119 <sect1>Editing Input Fields<label id="editing">
120 <p>
121 Mutt has a builtin line editor which is used as the primary way to input
122 textual data such as email addresses or filenames.  The keys used to move
123 around while editing are very similar to those of Emacs.
124
125 <tscreen><verb>
126 ^A or <Home>    bol             move to the start of the line
127 ^B or <Left>    backward-char   move back one char
128 Esc B           backward-word   move back one word
129 ^D or <Delete>  delete-char     delete the char under the cursor
130 ^E or <End>     eol             move to the end of the line
131 ^F or <Right>   forward-char    move forward one char
132 Esc F           forward-word    move forward one word
133 <Tab>           complete        complete filename or alias
134 ^T              complete-query  complete address with query
135 ^K              kill-eol        delete to the end of the line
136 ESC d           kill-eow        delete to the end ot the word
137 ^W              kill-word       kill the word in front of the cursor
138 ^U              kill-line       delete entire line
139 ^V              quote-char      quote the next typed key
140 <Up>            history-up      recall previous string from history
141 <Down>          history-down    recall next string from history
142 <BackSpace>     backspace       kill the char in front of the cursor
143 Esc u           upcase-word     convert word to upper case
144 Esc l           downcase-word   convert word to lower case
145 Esc c           capitalize-word capitalize the word
146 ^G              n/a             abort
147 <Return>        n/a             finish editing
148 </verb></tscreen>
149
150 You can remap the <em/editor/ functions using the <ref id="bind" name="bind">
151 command.  For example, to make the <em/Delete/ key delete the character in
152 front of the cursor rather than under, you could use
153
154 <tt/bind editor &lt;delete&gt; backspace/
155
156 <sect1>Reading Mail - The Index and Pager
157 <p>
158
159 Similar to many other mail clients, there are two modes in which mail is
160 read in Mutt.  The first is the index of messages in the mailbox, which is
161 called the ``index'' in Mutt.  The second mode is the display of the
162 message contents.  This is called the ``pager.''
163
164 The next few sections describe the functions provided in each of these
165 modes.
166
167 <sect2>The Message Index
168 <p>
169
170 <tscreen><verb>
171 c               change to a different mailbox
172 ESC c           change to a folder in read-only mode
173 C               copy the current message to another mailbox
174 ESC C           decode a message and copy it to a folder
175 ESC s           decode a message and save it to a folder
176 D               delete messages matching a pattern
177 d               delete the current message
178 F               mark as important
179 l               show messages matching a pattern
180 N               mark message as new
181 o               change the current sort method
182 O               reverse sort the mailbox
183 q               save changes and exit
184 s               save-message
185 T               tag messages matching a pattern
186 t               toggle the tag on a message
187 ESC t           toggle tag on entire message thread
188 U               undelete messages matching a pattern
189 u               undelete-message
190 v               view-attachments
191 x               abort changes and exit
192 <Return>        display-message
193 <Tab>           jump to the next new message
194 @               show the author's full e-mail address
195 $               save changes to mailbox
196 /               search
197 ESC /           search-reverse
198 ^L              clear and redraw the screen
199 ^T              untag messages matching a pattern
200 </verb></tscreen>
201
202 <sect3>Status Flags
203 <p>
204
205 In addition to who sent the message and the subject, a short summary of
206 the disposition of each message is printed beside the message number.
207 Zero or more of the following ``flags'' may appear, which mean:
208
209 <p>
210 <descrip>
211 <tag/D/ message is deleted (is marked for deletion)
212 <tag/d/ message have attachments marked for deletion
213 <tag/K/ contains a PGP public key
214 <tag/N/ message is new
215 <tag/O/ message is old
216 <tag/P/ message is PGP encrypted
217 <tag/r/ message has been replied to
218 <tag/S/ message is signed, and the signature is succesfully verified
219 <tag/s/ message is signed
220 <tag/!/ message is flagged
221 <tag/*/ message is tagged
222 </descrip>
223
224 Some of the status flags can be turned on or off using
225 <itemize>
226 <item><bf/set-flag/ (default: w)
227 <item><bf/clear-flag/ (default: W)
228 </itemize>
229
230 <p>
231 Furthermore, the following flags reflect who the message is addressed
232 to.  They can be customized with the
233 <ref id="to_chars" name="&dollar;to&lowbar;chars"> variable.
234
235 <p>
236 <descrip>
237 <tag/+/ message is to you and you only
238 <tag/T/ message is to you, but also to or cc'ed to others
239 <tag/C/ message is cc'ed to you
240 <tag/F/ message is from you
241 <tag/L/ message is sent to a subscribed mailing list
242 </descrip>
243
244 <sect2>The Pager
245 <p>
246
247 By default, Mutt uses its builtin pager to display the body of messages.
248 The pager is very similar to the Unix program <em/less/ though not nearly as
249 featureful.
250
251 <tscreen><verb>
252 <Return>        go down one line
253 <Space>         display the next page (or next message if at the end of a message)
254 -               go back to the previous page
255 n               search for next match
256 S               skip beyond quoted text
257 T               toggle display of quoted text
258 ?               show keybindings
259 /               search for a regular expression (pattern)
260 ESC /           search backwards for a regular expression
261 \               toggle search pattern coloring
262 ^               jump to the top of the message
263 </verb></tscreen>
264
265 In addition, many of the functions from the <em/index/ are available in
266 the pager, such as <em/delete-message/ or <em/copy-message/ (this is one
267 advantage over using an external pager to view messages).
268
269 Also, the internal pager supports a couple other advanced features. For
270 one, it will accept and translate the ``standard'' nroff sequences for
271 bold and underline. These sequences are a series of either the letter,
272 backspace (^H), the letter again for bold or the letter, backspace,
273 ``&lowbar;'' for denoting underline. Mutt will attempt to display these
274 in bold and underline respectively if your terminal supports them. If
275 not, you can use the bold and underline <ref id="color" name="color">
276 objects to specify a color or mono attribute for them.
277
278 Additionally, the internal pager supports the ANSI escape sequences for
279 character attributes.  Mutt translates them into the correct color and
280 character settings.  The sequences Mutt supports are:
281
282 <p>
283 <tscreen><verb>
284 ESC [ Ps;Ps;Ps;...;Ps m
285 where Ps =
286 0    All Attributes Off
287 1    Bold on
288 4    Underline on
289 5    Blink on
290 7    Reverse video on
291 3x   Foreground color is x
292 4x   Background color is x
293
294 Colors are
295 0    black
296 1    red
297 2    green
298 3    yellow
299 4    blue
300 5    magenta
301 6    cyan
302 7    white
303 </verb></tscreen>
304
305 Mutt uses these attributes for handling text/enriched messages, and they
306 can also be used by an external <ref id="auto_view" name="autoview">
307 script for highlighting purposes.  <bf/Note:/ If you change the colors for your
308 display, for example by changing the color associated with color2 for
309 your xterm, then that color will be used instead of green.
310
311 <sect2>Threaded Mode<label id="threads">
312 <p>
313 When the mailbox is <ref id="sort" name="sorted"> by <em/threads/, there are
314 a few additional functions available in the <em/index/ and <em/pager/ modes.
315
316 <tscreen><verb>
317 ^D      delete-thread           delete all messages in the current thread
318 ^U      undelete-thread         undelete all messages in the current thread
319 ^N      next-thread             jump to the start of the next thread
320 ^P      previous-thread         jump to the start of the previous thread
321 ^R      read-thread             mark the current thread as read
322 ESC d   delete-subthread        delete all messages in the current subthread
323 ESC u   undelete-subthread      undelete all messages in the current subthread
324 ESC n   next-subthread          jump to the start of the next subthread
325 ESC p   previous-subthread      jump to the start of the previous subthread
326 ESC r   read-subthread          mark the current subthread as read
327 ESC t   tag-thread              toggle the tag on the current thread
328 ESC v   collapse-thread         toggle collapse for the current thread
329 ESC V   collapse-all            toggle collapse for all threads
330 P       parent-message          jump to parent message in thread
331 </verb></tscreen>
332
333 <bf/Note:/ Collapsing a thread displays only the first message
334 in the thread and hides the others. This is useful when threads
335 contain so many messages that you can only see a handful of threads on
336 the screen. See %M in <ref id="index_format"name="&dollar;index&lowbar;format">.
337 For example, you could use "&percnt;?M?(#&percnt;03M)&amp;(&percnt;4l)?" in <ref
338 id="index_format"name="&dollar;index&lowbar;format"> to optionally
339 display the number of hidden messages if the thread is collapsed.
340
341 See also: <ref id="strict_threads" name="&dollar;strict&lowbar;threads">.
342
343 <sect2>Miscellaneous Functions
344 <p><bf/create-alias/<label id="create-alias"> (default: a)<newline>
345
346 Creates a new alias based upon the current message (or prompts for a
347 new one).  Once editing is complete, an <ref id="alias" name="alias">
348 command is added to the file specified by the <ref id="alias_file"
349 name="&dollar;alias&lowbar;file"> variable for future use. <bf/Note:/
350 Specifying an <ref id="alias_file" name="&dollar;alias&lowbar;file">
351 does not add the aliases specified there-in, you must also <ref
352 id="source" name="source"> the file.
353
354 <p><bf/check-traditional-pgp/<label id="check-traditional-pgp"> (default: ESC P)<newline>
355
356 This function will search the current message for content signed or
357 encrypted with PGP the "traditional" way, that is, without proper
358 MIME tagging.  Technically, this function will temporarily change
359 the MIME content types of the body parts containing PGP data; this
360 is similar to the <ref id="edit-type" name="edit-type"> function's
361 effect.
362
363
364 <p><bf/display-toggle-weed/<label id="display-toggle-weed"> (default: h)<newline>
365
366 Toggles the weeding of message header fields specified by <ref id="ignore"
367 name="ignore"> commands.
368
369 <p><bf/edit/<label id="edit"> (default: e)<newline>
370
371 This command (available in the ``index'' and ``pager'') allows you to
372 edit the raw current message as it's present in the mail folder.
373 After you have finished editing, the changed message will be
374 appended to the current folder, and the original message will be
375 marked for deletion.
376
377 <p><bf/edit-type/<label id="edit-type"><newline>
378 (default: ^E on the attachment menu, and in the pager and index menus; ^T on the
379 compose menu)
380
381 This command is used to temporarily edit an attachment's content
382 type to fix, for instance, bogus character set parameters.  When
383 invoked from the index or from the pager, you'll have the
384 opportunity to edit the top-level attachment's content type.  On the
385 <ref id="attach_menu" name="attachment menu">, you can change any
386 attachment's content type. These changes are not persistent, and get
387 lost upon changing folders.
388
389 Note that this command is also available on the <ref
390 id="compose_menu" name="compose menu">.  There, it's used to
391 fine-tune the properties of attachments you are going to send.
392
393 <p><bf/enter-command/<label id="enter-command"> (default: ``:'')<newline>
394
395 This command is used to execute any command you would normally put in a
396 configuration file.  A common use is to check the settings of variables, or
397 in conjunction with <ref id="macro" name="macros"> to change settings on the
398 fly.
399
400 <p><bf/extract-keys/<label id="extract-keys"> (default: ^K)<newline>
401
402 This command extracts PGP public keys from the current or tagged
403 message(s) and adds them to your PGP public key ring.
404
405 <p><bf/forget-passphrase/<label id="forget-passphrase"> (default:
406 ^F)<newline> 
407
408 This command wipes the passphrase(s) from memory. It is useful, if
409 you misspelled the passphrase.
410
411 <p><bf/list-reply/<label id="list-reply"> (default: L)<newline>
412
413 Reply to the current or tagged message(s) by extracting any addresses which
414 match the addresses given by the <ref id="lists" name="lists or subscribe">
415 commands, but also honor any <tt/Mail-Followup-To/ header(s) if the
416 <ref id="honor_followup_to" name="&dollar;honor&lowbar;followup&lowbar;to">
417 configuration variable is set.  Using this when replying to messages posted
418 to mailing lists helps avoid duplicate copies being sent to the author of
419 the message you are replying to.
420
421 <bf/pipe-message/<label id="pipe-message"> (default: |)<newline>
422
423 Asks for an external Unix command and pipes the current or
424 tagged message(s) to it.  The variables <ref id="pipe_decode"
425 name="&dollar;pipe&lowbar;decode">, <ref id="pipe_split"
426 name="&dollar;pipe&lowbar;split">, <ref id="pipe_sep"
427 name="&dollar;pipe&lowbar;sep"> and <ref id="wait_key"
428 name="&dollar;wait&lowbar;key"> control the exact behaviour of this
429 function.
430
431 <bf/resend-message/<label id="resend-message"> (default: ESC e)<newline>
432
433 With resend-message, mutt takes the current message as a template for a
434 new message.  This function is best described as "recall from arbitrary
435 folders".  It can conveniently be used to forward MIME messages while
436 preserving the original mail structure. Note that the amount of headers
437 included here depends on the value of the <ref id="weed" name="&dollar;weed">
438 variable.
439
440 This function is also available from the attachment menu. You can use this
441 to easily resend a message which was included with a bounce message
442 as a message/rfc822 body part.
443
444 <bf/shell-escape/<label id="shell-escape"> (default: !)<newline>
445
446 Asks for an external Unix command and executes it.  The <ref
447 id="wait_key" name="&dollar;wait&lowbar;key"> can be used to control
448 whether Mutt will wait for a key to be pressed when the command returns
449 (presumably to let the user read the output of the command), based on
450 the return status of the named command.
451
452 <bf/toggle-quoted/<label id="toggle-quoted"> (default: T)<newline>
453
454 The <em/pager/ uses the <ref id="quote_regexp"
455 name="&dollar;quote&lowbar;regexp"> variable to detect quoted text when
456 displaying the body of the message.  This function toggles the display
457 of the quoted material in the message.  It is particularly useful when
458 are interested in just the response and there is a large amount of
459 quoted text in the way.
460
461 <bf/skip-quoted/<label id="skip-quoted"> (default: S)<newline>
462
463 This function will go to the next line of non-quoted text which come
464 after a line of quoted text in the internal pager.
465
466 <sect1>Sending Mail
467 <p>
468
469 The following bindings are available in the <em/index/ for sending
470 messages.
471
472 <tscreen><verb>
473 m       compose         compose a new message
474 r       reply           reply to sender
475 g       group-reply     reply to all recipients
476 L       list-reply      reply to mailing list address
477 f       forward         forward message
478 b       bounce          bounce (remail) message
479 ESC k   mail-key        mail a PGP public key to someone
480 </verb></tscreen>
481
482 Bouncing a message sends the message as is to the recipient you
483 specify.  Forwarding a message allows you to add comments or
484 modify the message you are forwarding.  These items are discussed
485 in greater detail in the next chapter <ref id="forwarding_mail"
486 name="``Forwarding and Bouncing Mail''">.
487
488 Mutt will then enter the <em/compose/ menu and prompt you for the
489 recipients to place on the ``To:'' header field.  Next, it will ask
490 you for the ``Subject:'' field for the message, providing a default if
491 you are replying to or forwarding a message.  See also <ref id="askcc"
492 name="&dollar;askcc">, <ref id="askbcc" name="&dollar;askbcc">, <ref
493 id="autoedit" name="&dollar;autoedit">, <ref id="bounce"
494 name="&dollar;bounce">, and <ref id="fast_reply"
495 name="&dollar;fast&lowbar;reply"> for changing how Mutt asks these
496 questions.
497
498 Mutt will then automatically start your <ref id="editor"
499 name="&dollar;editor"> on the message body.  If the <ref id="edit_headers"
500 name="&dollar;edit&lowbar;headers"> variable is set, the headers will be at
501 the top of the message in your editor.  Any messages you are replying
502 to will be added in sort order to the message, with appropriate <ref
503 id="attribution" name="&dollar;attribution">, <ref id="indent_string"
504 name="&dollar;indent&lowbar;string"> and <ref id="post_indent_string"
505 name="&dollar;post&lowbar;indent&lowbar;string">.  When forwarding a
506 message, if the <ref id="mime_forward" name="&dollar;mime&lowbar;forward">
507 variable is unset, a copy of the forwarded message will be included.  If
508 you have specified a <ref id="signature" name="&dollar;signature">, it
509 will be appended to the message.
510
511 Once you have finished editing the body of your mail message, you are
512 returned to the <em/compose/ menu.  The following options are available:
513
514 <tscreen><verb>
515 a       attach-file             attach a file
516 A       attach-message          attach message(s) to the message
517 ESC k   attach-key              attach a PGP public key
518 d       edit-description        edit description on attachment
519 D       detach-file             detach a file
520 t       edit-to                 edit the To field
521 ESC f   edit-from               edit the From field
522 r       edit-reply-to           edit the Reply-To field
523 c       edit-cc                 edit the Cc field
524 b       edit-bcc                edit the Bcc field
525 y       send-message            send the message
526 s       edit-subject            edit the Subject
527 S       smime-menu              select S/MIME options
528 f       edit-fcc                specify an ``Fcc'' mailbox
529 p       pgp-menu                select PGP options
530 P       postpone-message        postpone this message until later
531 q       quit                    quit (abort) sending the message
532 w       write-fcc               write the message to a folder
533 i       ispell                  check spelling (if available on your system)
534 ^F      forget-passphrase       wipe passphrase(s) from memory
535 </verb></tscreen>
536
537 <bf/Note:/ The attach-message function will prompt you for a folder to
538 attach messages from. You can now tag messages in that folder and they
539 will be attached to the message you are sending. Note that certain
540 operations like composing a new mail, replying, forwarding, etc. are
541 not permitted when you are in that folder. The %r in <ref
542 id="status_format" name="&dollar;status&lowbar;format"> will change to
543 a 'A' to indicate that you are in attach-message mode.
544
545 <sect2>Editing the message header
546 <p>
547 When editing the header of your outgoing message, there are a couple of
548 special features available.
549
550 If you specify<newline>
551 <tt/Fcc:/ <em/filename/<newline>
552 Mutt will pick up <em/filename/
553 just as if you had used the <em/edit-fcc/ function in the <em/compose/ menu.
554
555 You can also attach files to your message by specifying<newline>
556 <tt/Attach:/ <em/filename/  &lsqb; <em/description/ &rsqb;<newline>
557 where <em/filename/ is the file to attach and <em/description/ is an
558 optional string to use as the description of the attached file.
559
560 When replying to messages, if you remove the <em/In-Reply-To:/ field from
561 the header field, Mutt will not generate a <em/References:/ field, which
562 allows you to create a new message thread.
563
564 Also see <ref id="edit_headers" name="edit&lowbar;headers">.
565
566 <sect2>Using Mutt with PGP
567
568 <p>
569 If you want to use PGP, you can specify 
570
571 <tt/Pgp:/ &lsqb; <tt/E/ | <tt/S/ | <tt/S&lt;id/&gt; &rsqb; <newline>
572
573 ``E'' encrypts, ``S'' signs and
574 ``S&lt;id&gt;'' signs with the given key, setting <ref
575 id="pgp_sign_as" name="&dollar;pgp&lowbar;sign&lowbar;as"> permanently.
576
577 If you have told mutt to PGP encrypt a message, it will guide you
578 through a key selection process when you try to send the message.
579 Mutt will not ask you any questions about keys which have a
580 certified user ID matching one of the message recipients' mail
581 addresses.  However, there may be situations in which there are
582 several keys, weakly certified user ID fields, or where no matching
583 keys can be found.
584
585 In these cases, you are dropped into a menu with a list of keys from
586 which you can select one.  When you quit this menu, or mutt can't
587 find any matching keys, you are prompted for a user ID.  You can, as
588 usually, abort this prompt using <tt/^G/.  When you do so, mutt will
589 return to the compose screen.
590
591 Once you have successfully finished the key selection, the message
592 will be encrypted using the selected public keys, and sent out.
593
594 Most fields of the entries in the key selection menu (see also <ref
595 id="pgp_entry_format" name="&dollar;pgp&lowbar;entry&lowbar;format">) 
596 have obvious meanings.  But some explanations on the capabilities, flags, 
597 and validity fields are in order.
598
599 The flags sequence (&percnt;f) will expand to one of the following flags:
600 <tscreen><verb>
601 R            The key has been revoked and can't be used.
602 X            The key is expired and can't be used.
603 d            You have marked the key as disabled.
604 c            There are unknown critical self-signature 
605              packets.
606 </verb></tscreen>
607
608 The capabilities field (&percnt;c) expands to a two-character sequence
609 representing a key's capabilities.  The first character gives
610 the key's encryption capabilities: A minus sign (<bf/-/) means 
611 that the key cannot be used for encryption.  A dot (<bf/./) means that
612 it's marked as a signature key in one of the user IDs, but may 
613 also be used for encryption.  The letter <bf/e/ indicates that 
614 this key can be used for encryption.
615  
616 The second character indicates the key's signing capabilities.  Once 
617 again, a ``<bf/-/'' implies ``not for signing'', ``<bf/./'' implies
618 that the key is marked as an encryption key in one of the user-ids, and
619 ``<bf/s/'' denotes a key which can be used for signing.
620
621 Finally, the validity field (%t) indicates how well-certified a user-id
622 is.  A question mark (<bf/?/) indicates undefined validity, a minus 
623 character (<bf/-/) marks an untrusted association, a space character 
624 means a partially trusted association, and a plus character (<bf/+/) 
625 indicates complete validity.
626
627 <sect2>Sending anonymous messages via mixmaster.
628
629 <p>
630 You may also have configured mutt to co-operate with Mixmaster, an
631 anonymous remailer.  Mixmaster permits you to send your messages
632 anonymously using a chain of remailers. Mixmaster support in mutt is for 
633 mixmaster version 2.04 (beta 45 appears to be the latest) and 2.03. 
634 It does not support earlier versions or the later so-called version 3 betas, 
635 of which the latest appears to be called 2.9b23.
636
637 To use it, you'll have to obey certain restrictions.  Most
638 important, you cannot use the <tt/Cc/ and <tt/Bcc/ headers.  To tell
639 Mutt to use mixmaster, you have to select a remailer chain, using
640 the mix function on the compose menu.  
641
642 The chain selection screen is divided into two parts.  In the
643 (larger) upper part, you get a list of remailers you may use.  In
644 the lower part, you see the currently selected chain of remailers.
645
646 You can navigate in the chain using the <tt/chain-prev/ and
647 <tt/chain-next/ functions, which are by default bound to the left
648 and right arrows and to the <tt/h/ and <tt/l/ keys (think vi
649 keyboard bindings).  To insert a remailer at the current chain
650 position, use the <tt/insert/ function.  To append a remailer behind
651 the current chain position, use <tt/select-entry/ or <tt/append/.
652 You can also delete entries from the chain, using the corresponding
653 function.  Finally, to abandon your changes, leave the menu, or
654 <tt/accept/ them pressing (by default) the <tt/Return/ key.
655
656 Note that different remailers do have different capabilities,
657 indicated in the &percnt;c entry of the remailer menu lines (see
658 <ref id="mix_entry_format"
659 name="&dollar;mix&lowbar;entry&lowbar;format">).  Most important is
660 the ``middleman'' capability, indicated by a capital ``M'': This
661 means that the remailer in question cannot be used as the final
662 element of a chain, but will only forward messages to other
663 mixmaster remailers.  For details on the other capabilities, please
664 have a look at the mixmaster documentation.
665
666 <sect1>Forwarding and Bouncing Mail<label id="forwarding_mail">
667 <p>
668
669 Bouncing and forwarding let you send an existing message to recipients
670 that you specify.  Bouncing a message uses the <ref id="sendmail"
671 name="sendmail"> command to send a copy to alternative addresses as if
672 they were the message's original recipients.  Forwarding a message, on
673 the other hand, allows you to modify the message before it is resent
674 (for example, by adding your own comments).
675
676 The following keys are bound by default:
677
678 <tscreen><verb>
679 f       forward         forward message
680 b       bounce          bounce (remail) message
681 </verb></tscreen>
682
683 Forwarding can be done by including the original message in the new
684 message's body (surrounded by indicating lines) or including it as a MIME
685 attachment, depending on the value of the <ref id="mime_forward"
686 name="&dollar;mime&lowbar;forward"> variable.  Decoding of attachments,
687 like in the pager, can be controlled by the <ref id="forward_decode"
688 name="&dollar;forward&lowbar;decode"> and <ref id="mime_forward_decode"
689 name="&dollar;mime&lowbar;forward&lowbar;decode"> variables,
690 respectively.  The desired forwarding format may depend on the content,
691 therefore <em/&dollar;mime&lowbar;forward/ is a quadoption which, for
692 example, can be set to ``ask-no''.
693
694 The inclusion of headers is controlled by the current setting of the
695 <ref id="weed" name="&dollar;weed"> variable, unless <ref
696 id="mime_forward" name="mime&lowbar;forward"> is set.
697
698 Editing the message to forward follows the same procedure as sending or
699 replying to a message does.
700
701 <sect1>Postponing Mail<label id="postponing_mail">
702 <p>
703
704 At times it is desirable to delay sending a message that you have
705 already begun to compose.  When the <em/postpone-message/ function is
706 used in the <em/compose/ menu, the body of your message and attachments
707 are stored in the mailbox specified by the <ref id="postponed"
708 name="&dollar;postponed"> variable.  This means that you can recall the
709 message even if you exit Mutt and then restart it at a later time.
710
711 Once a message is postponed, there are several ways to resume it.  From the
712 command line you can use the ``-p'' option, or if you <em/compose/ a new
713 message from the <em/index/ or <em/pager/ you will be prompted if postponed
714 messages exist.  If multiple messages are currently postponed, the
715 <em/postponed/ menu will pop up and you can select which message you would
716 like to resume.
717
718 <bf/Note:/ If you postpone a reply to a message, the reply setting of
719 the message is only updated when you actually finish the message and
720 send it.  Also, you must be in the same folder with the message you
721 replied to for the status of the message to be updated.
722
723 See also the <ref id="postpone" name="&dollar;postpone"> quad-option.
724
725 <sect1>Reading news via NNTP<label id="reading_news">
726 <p>
727
728 If compiled with ``--enable-nntp'' option, Mutt can read news from newsserver
729 via NNTP.  You can open a newsgroup with function ``change-newsgroup''
730 (default: i).  Default newsserver can be obtained from <em/NNTPSERVER/
731 environment variable.  Like other news readers, info about subscribed
732 newsgroups is saved in file by <ref id="newsrc" name="&dollar;newsrc">
733 variable.  Article headers are cached and can be loaded from file when
734 newsgroup entered instead loading from newsserver.
735
736 <sect>Configuration
737 <p>
738
739 While the default configuration (or ``preferences'') make Mutt
740 usable right out of the box, it is often desirable to tailor Mutt to
741 suit your own tastes. When Mutt is first invoked, it will attempt to
742 read the ``system'' configuration file (defaults set by your local
743 system administrator), unless the ``-n'' <ref id="commandline"
744 name="command line"> option is specified.  This file is typically
745 <tt>/usr/local/share/mutt/Muttrc</tt> or <tt>/etc/Muttrc</tt>. Mutt
746 will next look for a file named <tt>.muttrc</tt> in your home
747 directory.  If this file does not exist and your home directory has
748 a subdirectory named <tt/.mutt/, mutt try to load a file named
749 <tt>.mutt/muttrc</tt>. 
750
751 <tt>.muttrc</tt> is the file where you will usually place your <ref
752  id="commands" name="commands"> to configure Mutt.
753
754 In addition, mutt supports version specific configuration files that are
755 parsed instead of the default files as explained above.  For instance, if
756 your system has a <tt/Muttrc-0.88/ file in the system configuration
757 directory, and you are running version 0.88 of mutt, this file will be
758 sourced instead of the <tt/Muttrc/ file.  The same is true of the user
759 configuration file, if you have a file <tt/.muttrc-0.88.6/ in your home
760 directory, when you run mutt version 0.88.6, it will source this file
761 instead of the default <tt/.muttrc/ file.  The version number is the
762 same which is visible using the ``-v'' <ref id="commandline"
763 name="command line"> switch or using the <tt/show-version/ key (default:
764 V) from the index menu.
765
766 <sect1>Syntax of Initialization Files<label id="muttrc-syntax">
767 <p>
768
769 An initialization file consists of a series of <ref id="commands"
770 name="commands">.  Each line of the file may contain one or more commands.
771 When multiple commands are used, they must be separated by a semicolon (;).
772 <tscreen><verb>
773 set realname='Mutt user' ; ignore x-
774 </verb></tscreen>
775 The hash mark, or pound sign
776 (``&num;''), is used as a ``comment'' character. You can use it to
777 annotate your initialization file. All text after the comment character
778 to the end of the line is ignored. For example,
779
780 <tscreen><verb>
781 my_hdr X-Disclaimer: Why are you listening to me? &num; This is a comment
782 </verb></tscreen>
783
784 Single quotes (') and double quotes (&dquot;) can be used to quote strings
785 which contain spaces or other special characters.  The difference between
786 the two types of quotes is similar to that of many popular shell programs,
787 namely that a single quote is used to specify a literal string (one that is
788 not interpreted for shell variables or quoting with a backslash &lsqb;see
789 next paragraph&rsqb;), while double quotes indicate a string for which
790 should be evaluated.  For example, backtics are evaluated inside of double
791 quotes, but <bf/not/ for single quotes.
792
793 &bsol; quotes the next character, just as in shells such as bash and zsh.
794 For example, if want to put quotes ``&dquot;'' inside of a string, you can use
795 ``&bsol;'' to force the next character to be a literal instead of interpreted
796 character.
797 <tscreen><verb>
798 set realname="Michael \"MuttDude\" Elkins"
799 </verb></tscreen>
800
801 ``&bsol;&bsol;'' means to insert a literal ``&bsol;'' into the line.
802 ``&bsol;n'' and ``&bsol;r'' have their usual C meanings of linefeed and
803 carriage-return, respectively.
804
805 A &bsol; at the end of a line can be used to split commands over
806 multiple lines, provided that the split points don't appear in the
807 middle of command names.
808
809 It is also possible to substitute the output of a Unix command in an
810 initialization file.  This is accomplished by enclosing the command in
811 backquotes (``).  For example,
812 <tscreen><verb>
813 my_hdr X-Operating-System: `uname -a`
814 </verb></tscreen>
815 The output of the Unix command ``uname -a'' will be substituted before the
816 line is parsed.  Note that since initialization files are line oriented, only
817 the first line of output from the Unix command will be substituted.
818
819 UNIX environments can be accessed like the way it is done in shells like
820 sh and bash: Prepend the name of the environment by a ``&dollar;''.  For
821 example,
822 <tscreen><verb>
823 set record=+sent_on_$HOSTNAME
824 </verb></tscreen>
825
826 The commands understood by mutt are explained in the next paragraphs.
827 For a complete list, see the <ref id="commands" name="command reference">.
828
829 <sect1>Defining/Using aliases<label id="alias">
830 <p>
831
832 Usage: <tt/alias/ <em/key/ <em/address/ &lsqb; , <em/address/, ... &rsqb;
833
834 It's usually very cumbersome to remember or type out the address of someone
835 you are communicating with.  Mutt allows you to create ``aliases'' which map
836 a short string to a full address.
837
838 <bf/Note:/ if you want to create an alias for a group (by specifying more than
839 one address), you <bf/must/ separate the addresses with a comma (``,'').
840
841 To remove an alias or aliases (``*'' means all aliases):
842
843 <tt/unalias/ &lsqb; * | <em/key/ <em/.../ &rsqb;
844
845 <tscreen><verb>
846 alias muttdude me@cs.hmc.edu (Michael Elkins)
847 alias theguys manny, moe, jack
848 </verb></tscreen>
849
850 Unlike other mailers, Mutt doesn't require aliases to be defined
851 in a special file.  The <tt/alias/ command can appear anywhere in
852 a configuration file, as long as this file is <ref id="source"
853 name="sourced">.  Consequently, you can have multiple alias files, or
854 you can have all aliases defined in your muttrc.
855
856 On the other hand, the <ref id="create-alias" name="create-alias">
857 function can use only one file, the one pointed to by the <ref
858 id="alias_file" name="&dollar;alias&lowbar;file"> variable (which is
859 <tt>&tilde;/.muttrc</tt> by default). This file is not special either,
860 in the sense that Mutt will happily append aliases to any file, but in
861 order for the new aliases to take effect you need to explicitly <ref
862 id="source" name="source"> this file too.
863
864 For example:
865
866 <tscreen><verb>
867 source /usr/local/share/Mutt.aliases
868 source ~/.mail_aliases
869 set alias_file=~/.mail_aliases
870 </verb></tscreen>
871
872 To use aliases, you merely use the alias at any place in mutt where mutt
873 prompts for addresses, such as the <em/To:/ or <em/Cc:/ prompt.  You can
874 also enter aliases in your editor at the appropriate headers if you have the
875 <ref id="edit_headers" name="&dollar;edit&lowbar;headers"> variable set.
876
877 In addition, at the various address prompts, you can use the tab character
878 to expand a partial alias to the full alias.  If there are multiple matches,
879 mutt will bring up a menu with the matching aliases.  In order to be
880 presented with the full list of aliases, you must hit tab with out a partial
881 alias, such as at the beginning of the prompt or after a comma denoting
882 multiple addresses.
883
884 In the alias menu, you can select as many aliases as you want with the
885 <em/select-entry/ key (default: RET), and use the <em/exit/ key
886 (default: q) to return to the address prompt.
887
888 <sect1>Changing the default key bindings<label id="bind">
889 <p>
890 Usage: <tt/bind/ <em/map/ <em/key/ <em/function/
891
892 This command allows you to change the default key bindings (operation
893 invoked when pressing a key).
894
895 <em/map/ specifies in which menu the binding belongs.  The currently
896 defined maps are:
897
898 <descrip>
899 <tag/generic/
900 This is not a real menu, but is used as a fallback for all of the other
901 menus except for the pager and editor modes.  If a key is not defined in
902 another menu, Mutt will look for a binding to use in this menu.  This allows
903 you to bind a key to a certain function in multiple menus instead of having
904 multiple bind statements to accomplish the same task.
905 <tag/alias/
906 The alias menu is the list of your personal aliases as defined in your
907 muttrc.  It is the mapping from a short alias name to the full email
908 address(es) of the recipient(s).
909 <tag/attach/
910 The attachment menu is used to access the attachments on received messages.
911 <tag/browser/
912 The browser is used for both browsing the local directory structure, and for
913 listing all of your incoming mailboxes.
914 <tag/editor/
915 The editor is the line-based editor the user enters text data.
916 <tag/index/
917 The index is the list of messages contained in a mailbox.
918 <tag/compose/
919 The compose menu is the screen used when sending a new message.
920 <tag/pager/
921 The pager is the mode used to display message/attachment data, and help
922 listings.
923 <tag/pgp/
924 The pgp menu is used to select the OpenPGP keys used for encrypting outgoing
925 messages.
926 <tag/postpone/
927 The postpone menu is similar to the index menu, except is used when
928 recalling a message the user was composing, but saved until later.
929 </descrip>
930
931 <em/key/ is the key (or key sequence) you wish to bind.  To specify a
932 control character, use the sequence <em/&bsol;Cx/, where <em/x/ is the
933 letter of the control character (for example, to specify control-A use
934 ``&bsol;Ca'').  Note that the case of <em/x/ as well as <em/&bsol;C/ is
935 ignored, so that <em/&bsol;CA, &bsol;Ca, &bsol;cA/ and <em/&bsol;ca/ are all
936 equivalent.  An alternative form is to specify the key as a three digit
937 octal number prefixed with a ``&bsol;'' (for example <em/&bsol;177/ is
938 equivalent to <em/&bsol;c?/).
939
940 In addition, <em/key/ may consist of:
941
942 <tscreen><verb>
943 \t              tab
944 <tab>           tab
945 \r              carriage return
946 \n              newline
947 \e              escape
948 <esc>           escape
949 <up>            up arrow
950 <down>          down arrow
951 <left>          left arrow
952 <right>         right arrow
953 <pageup>        Page Up
954 <pagedown>      Page Down
955 <backspace>     Backspace
956 <delete>        Delete
957 <insert>        Insert
958 <enter>         Enter
959 <return>        Return
960 <home>          Home
961 <end>           End
962 <space>         Space bar
963 <f1>            function key 1
964 <f10>           function key 10
965 </verb></tscreen>
966
967 <em/key/ does not need to be enclosed in quotes unless it contains a
968 space (`` '').
969
970 <em/function/ specifies which action to take when <em/key/ is pressed.
971 For a complete list of functions, see the <ref id="functions"
972 name="reference">.  The special function <tt/noop/ unbinds the specified key
973 sequence.
974
975 <sect1>Defining aliases for character sets <label id="charset-hook">
976 <p>
977 Usage: <tt/charset-hook/ <em/alias/ <em/charset/<newline>
978 Usage: <tt/iconv-hook/ <em/charset/ <em/local-charset/
979
980 The <tt/charset-hook/ command defines an alias for a character set.
981 This is useful to properly display messages which are tagged with a
982 character set name not known to mutt.
983
984 The <tt/iconv-hook/ command defines a system-specific name for a
985 character set.  This is helpful when your systems character
986 conversion library insists on using strange, system-specific names
987 for character sets.
988
989
990 <sect1>Setting variables based upon mailbox<label id="folder-hook">
991 <p>
992 Usage: <tt/folder-hook/ &lsqb;!&rsqb;<em/regexp/ <em/command/
993
994 It is often desirable to change settings based on which mailbox you are
995 reading.  The folder-hook command provides a method by which you can execute
996 any configuration command.  <em/regexp/ is a regular expression specifying
997 in which mailboxes to execute <em/command/ before loading.  If a mailbox
998 matches multiple folder-hook's, they are executed in the order given in the
999 muttrc.
1000
1001 <bf/Note:/ if you use the ``!'' shortcut for <ref id="spoolfile"
1002 name="&dollar;spoolfile"> at the beginning of the pattern, you must place it
1003 inside of double or single quotes in order to distinguish it from the
1004 logical <em/not/ operator for the expression.
1005
1006 Note that the settings are <em/not/ restored when you leave the mailbox.
1007 For example, a command action to perform is to change the sorting method
1008 based upon the mailbox being read:
1009
1010 <tscreen><verb>
1011 folder-hook mutt set sort=threads
1012 </verb></tscreen>
1013
1014 However, the sorting method is not restored to its previous value when
1015 reading a different mailbox.  To specify a <em/default/ command, use the
1016 pattern ``.'':
1017
1018 <p>
1019 <tscreen><verb>
1020 folder-hook . set sort=date-sent
1021 </verb></tscreen>
1022
1023 <sect1>Keyboard macros<label id="macro">
1024 <p>
1025 Usage: <tt/macro/ <em/menu/ <em/key/ <em/sequence/ &lsqb; <em/description/ &rsqb;
1026
1027 Macros are useful when you would like a single key to perform a series of
1028 actions.  When you press <em/key/ in menu <em/menu/, Mutt will behave as if
1029 you had typed <em/sequence/.  So if you have a common sequence of commands
1030 you type, you can create a macro to execute those commands with a single
1031 key.
1032
1033 <em/key/ and <em/sequence/ are expanded by the same rules as the <ref
1034 id="bind" name="key bindings">.  There are some additions however.  The
1035 first is that control characters in <em/sequence/ can also be specified
1036 as <em/&circ;x/.  In order to get a caret (`&circ;'') you need to use
1037 <em/&circ;&circ;/.  Secondly, to specify a certain key such as <em/up/
1038 or to invoke a function directly, you can use the format
1039 <em/&lt;key name&gt;/ and <em/&lt;function name&gt;/.  For a listing of key
1040 names see the section on <ref id="bind" name="key bindings">.  Functions
1041 are listed in the <ref id="functions" name="function reference">.
1042
1043 The advantage with using function names directly is that the macros will
1044 work regardless of the current key bindings, so they are not dependent on
1045 the user having particular key definitions.  This makes them more robust
1046 and portable, and also facilitates defining of macros in files used by more
1047 than one user (eg. the system Muttrc).
1048
1049 Optionally you can specify a descriptive text after <em/sequence/,
1050 which is shown in the help screens.
1051
1052 <bf/Note:/ Macro definitions (if any) listed in the help screen(s), are
1053 silently truncated at the screen width, and are not wrapped.   
1054
1055 <sect1>Using color and mono video attributes<label id="color">
1056 <p>
1057 Usage: <tt/color/ <em/object/ <em/foreground/ <em/background/ &lsqb; <em/regexp/ &rsqb;<newline>
1058 Usage: <tt/color/ index <em/foreground/ <em/background/ <em/pattern/<newline>
1059 Usage: <tt/uncolor/ index <em/pattern/ &lsqb; <em/pattern/ ...  &rsqb;<newline>
1060
1061 If your terminal supports color, you can spice up Mutt by creating your own
1062 color scheme.  To define the color of an object (type of information), you
1063 must specify both a foreground color <bf/and/ a background color (it is not
1064 possible to only specify one or the other).
1065
1066 <em/object/ can be one of:
1067
1068 <itemize>
1069 <item>attachment
1070 <item>body (match <em/regexp/ in the body of messages)
1071 <item>bold (hiliting bold patterns in the body of messages)
1072 <item>error (error messages printed by Mutt)
1073 <item>header (match <em/regexp/ in the message header)
1074 <item>hdrdefault (default color of the message header in the pager)
1075 <item>index (match <em/pattern/ in the message index)
1076 <item>indicator (arrow or bar used to indicate the current item in a menu)
1077 <item>markers (the ``+'' markers at the beginning of wrapped lines in the pager)
1078 <item>message (informational messages)
1079 <item>normal
1080 <item>quoted (text matching <ref id="quote_regexp"
1081 name="&dollar;quote&lowbar;regexp"> in the body of a message)
1082 <item>quoted1, quoted2, ..., quoted<bf/N/ (higher levels of quoting)
1083 <item>search (hiliting of words in the pager)
1084 <item>signature
1085 <item>status (mode lines used to display info about the mailbox or message)
1086 <item>tilde (the ``&tilde;'' used to pad blank lines in the pager)
1087 <item>tree (thread tree drawn in the message index and attachment menu)
1088 <item>underline (hiliting underlined patterns in the body of messages)
1089 </itemize>
1090
1091 <em/foreground/ and <em/background/ can be one of the following:
1092
1093 <itemize>
1094 <item>white
1095 <item>black
1096 <item>green
1097 <item>magenta
1098 <item>blue
1099 <item>cyan
1100 <item>yellow
1101 <item>red
1102 <item>default
1103 <item>color<em/x/
1104 </itemize>
1105
1106 <em/foreground/ can optionally be prefixed with the keyword <tt/bright/ to make
1107 the foreground color boldfaced (e.g., <tt/brightred/).
1108
1109 If your terminal supports it, the special keyword <em/default/ can be
1110 used as a transparent color.  The value <em/brightdefault/ is also valid.
1111 If Mutt is linked against the <em/S-Lang/ library, you also need to set
1112 the <em/COLORFGBG/ environment variable to the default colors of your
1113 terminal for this to work; for example (for Bourne-like shells):
1114
1115 <tscreen><verb>
1116 set COLORFGBG="green;black"
1117 export COLORFGBG
1118 </verb></tscreen>
1119
1120 <bf/Note:/ The <em/S-Lang/ library requires you to use the <em/lightgray/
1121 and <em/brown/ keywords instead of <em/white/ and <em/yellow/ when
1122 setting this variable.
1123
1124 <bf/Note:/ The uncolor command can be applied to the index object only.  It
1125 removes entries from the list. You <bf/must/ specify the same pattern
1126 specified in the color command for it to be removed.  The pattern ``*'' is
1127 a special token which means to clear the color index list of all entries.
1128
1129 Mutt also recognizes the keywords <em/color0/, <em/color1/, &hellip;,
1130 <em/color/<bf/N-1/ (<bf/N/ being the number of colors supported
1131 by your terminal).  This is useful when you remap the colors for your
1132 display (for example by changing the color associated with <em/color2/
1133 for your xterm), since color names may then lose their normal meaning.
1134
1135 If your terminal does not support color, it is still possible change the video
1136 attributes through the use of the ``mono'' command:
1137
1138 Usage: <tt/mono/ <em/&lt;object&gt; &lt;attribute&gt;/ &lsqb; <em/regexp/ &rsqb;<newline>
1139 Usage: <tt/mono/ index <em/attribute/ <em/pattern/<newline>
1140 Usage: <tt/unmono/ index <em/pattern/ &lsqb; <em/pattern/ ...  &rsqb;<newline>
1141
1142 where <em/attribute/ is one of the following:
1143
1144 <itemize>
1145 <item>none
1146 <item>bold
1147 <item>underline
1148 <item>reverse
1149 <item>standout
1150 </itemize>
1151
1152 <sect1>Ignoring (weeding) unwanted message headers<label id="ignore">
1153 <p>
1154 Usage: <tt/&lsqb;un&rsqb;ignore/ <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
1155
1156 Messages often have many header fields added by automatic processing systems,
1157 or which may not seem useful to display on the screen.  This command allows
1158 you to specify header fields which you don't normally want to see.
1159
1160 You do not need to specify the full header field name.  For example,
1161 ``ignore content-'' will ignore all header fields that begin with the pattern
1162 ``content-''. ``ignore *'' will ignore all headers.
1163
1164 To remove a previously added token from the list, use the ``unignore'' command.
1165 The ``unignore'' command will make Mutt display headers with the given pattern.
1166 For example, if you do ``ignore x-'' it is possible to ``unignore x-mailer''.
1167
1168 ``unignore *'' will remove all tokens from the ignore list.
1169
1170 For example:
1171 <tscreen><verb>
1172 # Sven's draconian header weeding
1173 ignore *
1174 unignore from date subject to cc
1175 unignore organization organisation x-mailer: x-newsreader: x-mailing-list:
1176 unignore posted-to:
1177 </verb></tscreen>
1178
1179 <sect1>Alternative addresses<label id="alternates">
1180 <p>
1181 Usage: <tt/&lsqb;un&rsqb;alternates/ <em/regexp/ &lsqb; <em/regexp/ ... &rsqb;<newline>
1182
1183 With various functions, mutt will treat messages differently,
1184 depending on whether you sent them or whether you received them from
1185 someone else.  For instance, when replying to a message that you
1186 sent to a different party, mutt will automatically suggest to send
1187 the response to the original message's recipients -- responding to
1188 yourself won't make much sense in many cases.  (See <ref
1189 id="reply_to" name="&dollar;reply_to">.)
1190
1191 Many users receive e-mail under a number of different addresses. To
1192 fully use mutt's features here, the program must be able to
1193 recognize what e-mail addresses you receive mail under. That's the
1194 purpose of the <tt/alternates/ command: It takes a list of regular
1195 expressions, each of which can identify an address under which you
1196 receive e-mail.
1197
1198 To remove a regular expression from this list, use the
1199 <tt/unalternates/ command.
1200
1201 <sect1>Mailing lists<label id="lists">
1202 <p>
1203 Usage: <tt/&lsqb;un&rsqb;lists/ <em/regexp/ &lsqb; <em/regexp/ ... &rsqb;<newline>
1204 Usage: <tt/&lsqb;un&rsqb;subscribe/ <em/regexp/ &lsqb; <em/regexp/ ... &rsqb;
1205
1206 Mutt has a few nice features for <ref id="using_lists" name="handling
1207 mailing lists">.  In order to take advantage of them, you must
1208 specify which addresses belong to mailing lists, and which mailing
1209 lists you are subscribed to.  Once you have done this, the <ref
1210 id="list-reply" name="list-reply"> function will work for all known lists.
1211 Additionally, when you send a message to a subscribed list, mutt will
1212 add a Mail-Followup-To header to tell other users' mail user agents
1213 not to send copies of replies to your personal address.   Note that
1214 the Mail-Followup-To header is a non-standard extension which is not
1215 supported by all mail user agents.  Adding it is not bullet-proof against
1216 receiving personal CCs of list messages.  Also note that the generation
1217 of the Mail-Followup-To header is controlled by the <ref id="followup_to"
1218 name="&dollar;followup_to"> configuration variable.
1219
1220 More precisely, Mutt maintains lists of patterns for the addresses
1221 of known and subscribed mailing lists.  Every subscribed mailing
1222 list is known. To mark a mailing list as known, use the ``lists''
1223 command.  To mark it as subscribed, use ``subscribe''.
1224
1225 You can use regular expressions with both commands.  To mark all
1226 messages sent to a specific bug report's address on mutt's bug
1227 tracking system as list mail, for instance, you could say
1228 ``subscribe [0-9]*@bugs.guug.de''.  Often, it's sufficient to just
1229 give a portion of the list's e-mail address.
1230
1231 Specify as much of the address as you need to to remove ambiguity.  For
1232 example, if you've subscribed to the Mutt mailing list, you will receive mail
1233 addresssed to <em/mutt-users@mutt.org/.  So, to tell Mutt that this is a
1234 mailing list, you could add ``lists mutt-users'' to your
1235 initialization file.  To tell mutt that you are subscribed to it,
1236 add ``subscribe mutt-users'' to your initialization file instead.
1237 If you also happen to get mail from someone whose address is
1238 <em/mutt-users@example.com/, you could use ``lists mutt-users@mutt.org'' 
1239 or ``subscribe mutt-users@mutt.org'' to
1240 match only mail from the actual list.
1241
1242 The ``unlists'' command is used to remove a token from the list of
1243 known and subscribed mailing-lists. Use ``unlists *'' to remove all
1244 tokens.
1245
1246 To remove a mailing list from the list of subscribed mailing lists,
1247 but keep it on the list of known mailing lists, use ``unsubscribe''.
1248
1249 <sect1>Using Multiple spool mailboxes<label id="mbox-hook">
1250 <p>
1251 Usage: <tt/mbox-hook/ &lsqb;!&rsqb;<em/pattern/ <em/mailbox/
1252
1253 This command is used to move read messages from a specified mailbox to a
1254 different mailbox automatically when you quit or change folders.
1255 <em/pattern/ is a regular expression specifying the mailbox to treat as a
1256 ``spool'' mailbox and <em/mailbox/ specifies where mail should be saved when
1257 read.
1258
1259 Unlike some of the other <em/hook/ commands, only the <em/first/ matching
1260 pattern is used (it is not possible to save read mail in more than a single
1261 mailbox).
1262
1263 <sect1>Defining mailboxes which receive mail<label id="mailboxes">
1264 <p>
1265 Usage: <tt/&lsqb;un&rsqb;mailboxes/ &lsqb;!&rsqb;<em/filename/ &lsqb; <em/filename/ ... &rsqb;
1266
1267 This command specifies folders which can receive mail and
1268 which will be checked for new messages.  By default, the
1269 main menu status bar displays how many of these folders have
1270 new messages.
1271 <p>
1272 When changing folders, pressing <em/space/ will cycle
1273 through folders with new mail.
1274 <p>
1275 Pressing TAB in the directory browser will bring up a menu showing the files
1276 specified by the <tt/mailboxes/ command, and indicate which contain new
1277 messages.  Mutt will automatically enter this mode when invoked from the
1278 command line with the <tt/-y/ option.
1279
1280 The ``unmailboxes'' command is used to remove a token from the list
1281 of folders which receive mail. Use ``unmailboxes *'' to remove all
1282 tokens.
1283
1284 <p>
1285 <bf/Note:/ new mail is detected by comparing the last modification time to
1286 the last access time.  Utilities like <tt/biff/ or <tt/frm/ or any other
1287 program which accesses the mailbox might cause Mutt to never detect new mail
1288 for that mailbox if they do not properly reset the access time.  Backup
1289 tools are another common reason for updated access times.
1290 <p>
1291
1292 <bf/Note:/ the filenames in the <tt/mailboxes/ command are resolved when
1293 the command is executed, so if these names contain <ref id="shortcuts"
1294 name="shortcut characters"> (such as ``='' and ``!''), any variable
1295 definition that affect these characters (like <ref id="folder"
1296 name="&dollar;folder"> and <ref id="spoolfile" name="&dollar;spoolfile">)
1297 should be executed before the <tt/mailboxes/ command.
1298
1299 <sect1>User defined headers<label id="my_hdr">
1300 <p>
1301 Usage:<newline>
1302 <tt/my_hdr/ <em/string/<newline>
1303 <tt/unmy_hdr/ <em/field/ &lsqb; <em/field/ ... &rsqb;
1304
1305 The ``my&lowbar;hdr'' command allows you to create your own header
1306 fields which will be added to every message you send.
1307
1308 For example, if you would like to add an ``Organization:'' header field to
1309 all of your outgoing messages, you can put the command
1310
1311 <quote>
1312 my_hdr Organization: A Really Big Company, Anytown, USA
1313 </quote>
1314
1315 in your <tt/.muttrc/.
1316
1317 <bf/Note:/  space characters are <em/not/ allowed between the keyword and
1318 the colon (``:'').  The standard for electronic mail (RFC822) says that
1319 space is illegal there, so Mutt enforces the rule.
1320
1321 If you would like to add a header field to a single message, you should
1322 either set the <ref id="edit_headers" name="edit&lowbar;headers"> variable,
1323 or use the <em/edit-headers/ function (default: ``E'') in the send-menu so
1324 that you can edit the header of your message along with the body.
1325
1326 To remove user defined header fields, use the ``unmy&lowbar;hdr''
1327 command.  You may specify an asterisk (``*'') to remove all header
1328 fields, or the fields to remove.  For example, to remove all ``To'' and
1329 ``Cc'' header fields, you could use:
1330
1331 <quote>
1332 unmy_hdr to cc
1333 </quote>
1334
1335 <sect1>Defining the order of headers when viewing messages<label id="hdr_order">
1336 <p>
1337 Usage: <tt/hdr&lowbar;order/ <em/header1/ <em/header2/ <em/header3/
1338
1339 With this command, you can specify an order in which mutt will attempt
1340 to present headers to you when viewing messages.
1341
1342 ``unhdr_order *'' will clear all previous headers from the order list,
1343 thus removing the header order effects set by the system-wide startup
1344 file.
1345
1346 <tscreen><verb>
1347 hdr&lowbar;order From Date: From: To: Cc: Subject:
1348 </verb></tscreen>
1349
1350 <sect1>Specify default save filename<label id="save-hook">
1351 <p>
1352 Usage: <tt/save-hook/ &lsqb;!&rsqb;<em/pattern/ <em/filename/
1353
1354 This command is used to override the default filename used when saving
1355 messages.  <em/filename/ will be used as the default filename if the message is
1356 <em/From:/ an address matching <em/regexp/ or if you are the author and the
1357 message is addressed <em/to:/ something matching <em/regexp/.
1358
1359 See <ref id="pattern_hook" name="Message Matching in Hooks"> for information on the exact format of <em/pattern/.
1360
1361 Examples:
1362
1363 <tscreen><verb>
1364 save-hook me@(turing\\.)?cs\\.hmc\\.edu$ +elkins
1365 save-hook aol\\.com$ +spam
1366 </verb></tscreen>
1367
1368 Also see the <ref id="fcc-save-hook" name="fcc-save-hook"> command.
1369
1370 <sect1>Specify default Fcc: mailbox when composing<label id="fcc-hook">
1371 <p>
1372 Usage: <tt/fcc-hook/ &lsqb;!&rsqb;<em/pattern/ <em/mailbox/
1373
1374 This command is used to save outgoing mail in a mailbox other than
1375 <ref id="record" name="&dollar;record">.  Mutt searches the initial list of
1376 message recipients for the first matching <em/regexp/ and uses <em/mailbox/
1377 as the default Fcc: mailbox.  If no match is found the message will be saved
1378 to <ref id="record" name="&dollar;record"> mailbox.
1379
1380 See <ref id="pattern_hook" name="Message Matching in Hooks"> for information on the exact format of <em/pattern/.
1381
1382 Example: <tt/fcc-hook aol.com&dollar; +spammers/
1383
1384 The above will save a copy of all messages going to the aol.com domain to
1385 the `+spammers' mailbox by default.  Also see the <ref id="fcc-save-hook" 
1386 name="fcc-save-hook"> command.
1387
1388 <sect1>Specify default save filename and default Fcc: mailbox at once<label
1389 id="fcc-save-hook">
1390 <p>
1391 Usage: <tt/fcc-save-hook/ &lsqb;!&rsqb;<em/pattern/ <em/mailbox/
1392
1393 This command is a shortcut, equivalent to doing both a <ref id="fcc-hook" name="fcc-hook">
1394 and a <ref id="save-hook" name="save-hook"> with its arguments.
1395
1396 <sect1>Change settings based upon message recipients<label id="send-hook"><label id="reply-hook">
1397 <p>
1398 Usage: <tt/reply-hook/ &lsqb;!&rsqb;<em/pattern/ <em/command/<newline>
1399 Usage: <tt/send-hook/ &lsqb;!&rsqb;<em/pattern/ <em/command/
1400
1401 These commands can be used to execute arbitrary configuration commands based
1402 upon recipients of the message.  <em/pattern/ is a regular expression
1403 matching the desired address.  <em/command/ is executed when <em/regexp/
1404 matches recipients of the message.
1405
1406 <tt/reply-hook/ is matched against the message you are <em/replying/
1407 <bf/to/, instead of the message you are <em/sending/.  <tt/send-hook/ is
1408 matched against all messages, both <em/new/ and <em/replies/.  <bf/Note:/
1409 <tt/reply-hook/s are matched <bf/before/ the <tt/send-hook/, <bf/regardless/
1410 of the order specified in the users's configuration file.
1411
1412 For each type of <tt/send-hook/ or <tt/reply-hook/, When multiple matches
1413 occur, commands are executed in the order they are specified in the muttrc
1414 (for that type of hook).
1415
1416 See <ref id="pattern_hook" name="Message Matching in Hooks"> for information on the exact format of <em/pattern/.
1417
1418 Example: <tt/send-hook mutt &dquot;set mime&lowbar;forward signature=''&dquot;/
1419
1420 Another typical use for this command is to change the values of the
1421 <ref id="attribution" name="&dollar;attribution">, <ref id="signature"
1422 name="&dollar;signature"> and <ref id="locale" name="&dollar;locale">
1423 variables in order to change the language of the attributions and
1424 signatures based upon the recipients.
1425
1426 <bf/Note:/ the send-hook's are only executed ONCE after getting the initial
1427 list of recipients.  Adding a recipient after replying or editing the
1428 message will NOT cause any send-hook to be executed.  Also note that
1429 my_hdr commands which modify recipient headers, or the message's
1430 subject, don't have any effect on the current message when executed
1431 from a send-hook.
1432
1433 <sect1>Change settings before formatting a message<label id="message-hook">
1434 <p>
1435 Usage: <tt/message-hook/ &lsqb;!&rsqb;<em/pattern/ <em/command/
1436
1437 This command can be used to execute arbitrary configuration commands
1438 before viewing or formatting a message based upon information about the message.
1439 <em/command/ is executed if the <em/pattern/ matches the message to be
1440 displayed. When multiple matches occur, commands are executed in the order
1441 they are specified in the muttrc.
1442
1443 See <ref id="pattern_hook" name="Message Matching in Hooks"> for
1444 information on the exact format of <em/pattern/.
1445
1446 Example:
1447 <tscreen><verb>
1448 message-hook ~A 'set pager=builtin'
1449 message-hook '~f freshmeat-news' 'set pager="less \"+/^  subject: .*\""'
1450 </verb></tscreen>
1451
1452 <sect1>Choosing the cryptographic key of the recipient<label id="crypt-hook">
1453 <p>
1454 Usage: <tt/crypt-hook/ <em/pattern/ <em/keyid/
1455
1456 When encrypting messages with PGP or OpenSSL, you may want to associate a certain
1457 key with a given e-mail address automatically, either because the
1458 recipient's public key can't be deduced from the destination address,
1459 or because, for some reasons, you need to override the key Mutt would
1460 normally use.  The crypt-hook command provides a method by which you can
1461 specify the ID of the public key to be used when encrypting messages to
1462 a certain recipient.
1463
1464 The meaning of "key id" is to be taken broadly in this context:  You
1465 can either put a numerical key ID here, an e-mail address, or even
1466 just a real name.
1467
1468 <sect1>Adding key sequences to the keyboard buffer<label id="push">
1469 <p>
1470 Usage: <tt/push/ <em/string/
1471
1472 This command adds the named string to the keyboard buffer. The string may
1473 contain control characters, key names and function names like the sequence
1474 string in the <ref id="macro" name="macro"> command. You may use it to
1475 automatically run a sequence of commands at startup, or when entering
1476 certain folders.
1477
1478 <sect1>Executing functions<label id="exec">
1479 <p>
1480 Usage: <tt/exec/ <em/function/ &lsqb; <em/function/ ... &rsqb;
1481
1482 This command can be used to execute any function. Functions are
1483 listed in the <ref id="functions" name="function reference">.
1484 ``exec function'' is equivalent to ``push &lt;function&gt;''.
1485
1486 <sect1>Message Scoring<label id="score-command">
1487 <p>
1488 Usage: <tt/score/ <em/pattern/ <em/value/<newline>
1489 Usage: <tt/unscore/ <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
1490
1491 The <tt/score/ commands adds <em/value/ to a message's score if <em/pattern/
1492 matches it.  <em/pattern/ is a string in the format described in the <ref
1493 id="patterns" name="patterns"> section (note: For efficiency reasons, patterns
1494 which scan information not available in the index, such as <tt>&tilde;b</tt>,
1495 <tt>&tilde;B</tt> or <tt>&tilde;h</tt>, may not be used).  <em/value/ is a
1496 positive or negative integer.  A message's final score is the sum total of all
1497 matching <tt/score/ entries.  However, you may optionally prefix <em/value/ with
1498 an equal sign (=) to cause evaluation to stop at a particular entry if there is
1499 a match.  Negative final scores are rounded up to 0.
1500
1501 The <tt/unscore/ command removes score entries from the list.  You <bf/must/
1502 specify the same pattern specified in the <tt/score/ command for it to be
1503 removed.  The pattern ``*'' is a special token which means to clear the list
1504 of all score entries.
1505
1506 <sect1>Setting variables<label id="set">
1507 <p>
1508 Usage: <tt/set/ &lsqb;no|inv&rsqb;<em/variable/&lsqb;=<em/value/&rsqb; &lsqb; <em/variable/ ... &rsqb;<newline>
1509 Usage: <tt/toggle/ <em/variable/ &lsqb;<em/variable/ ... &rsqb;<newline>
1510 Usage: <tt/unset/ <em/variable/ &lsqb;<em/variable/ ... &rsqb;<newline>
1511 Usage: <tt/reset/ <em/variable/ &lsqb;<em/variable/ ... &rsqb;
1512
1513 This command is used to set (and unset) <ref id="variables"
1514 name="configuration variables">.  There are four basic types of variables:
1515 boolean, number, string and quadoption.  <em/boolean/ variables can be
1516 <em/set/ (true) or <em/unset/ (false).  <em/number/ variables can be
1517 assigned a positive integer value.
1518
1519 <em/string/ variables consist of any number of printable characters.
1520 <em/strings/ must be enclosed in quotes if they contain spaces or tabs.  You
1521 may also use the ``C'' escape sequences <bf/&bsol;n/ and <bf/&bsol;t/ for
1522 newline and tab, respectively.
1523
1524 <em/quadoption/ variables are used to control whether or not to be prompted
1525 for certain actions, or to specify a default action.  A value of <em/yes/
1526 will cause the action to be carried out automatically as if you had answered
1527 yes to the question.  Similarly, a value of <em/no/ will cause the the
1528 action to be carried out as if you had answered ``no.''  A value of
1529 <em/ask-yes/ will cause a prompt with a default answer of ``yes'' and
1530 <em/ask-no/ will provide a default answer of ``no.''
1531
1532 Prefixing a variable with ``no'' will unset it.  Example: <tt/set noaskbcc/.
1533
1534 For <em/boolean/ variables, you may optionally prefix the variable name with
1535 <tt/inv/ to toggle the value (on or off).  This is useful when writing
1536 macros.  Example: <tt/set invsmart&lowbar;wrap/.
1537
1538 The <tt/toggle/ command automatically prepends the <tt/inv/ prefix to all
1539 specified variables.
1540
1541 The <tt/unset/ command automatically prepends the <tt/no/ prefix to all
1542 specified variables.
1543
1544 Using the enter-command function in the <em/index/ menu, you can query the
1545 value of a variable by prefixing the name of the variable with a question
1546 mark:
1547
1548 <tscreen><verb>
1549 set ?allow_8bit
1550 </verb></tscreen>
1551
1552 The question mark is actually only required for boolean and quadoption 
1553 variables.
1554
1555 The <tt/reset/ command resets all given variables to the compile time
1556 defaults (hopefully mentioned in this manual). If you use the command
1557 <tt/set/ and prefix the variable with ``&amp;'' this has the same
1558 behavior as the reset command.
1559
1560 With the <tt/reset/ command there exists the special variable ``all'',
1561 which allows you to reset all variables to their system defaults.
1562
1563 <sect1>Reading initialization commands from another file<label id="source">
1564 <p>
1565 Usage: <tt/source/ <em/filename/ &lsqb; <em/filename/ ... &rsqb;
1566
1567 This command allows the inclusion of initialization commands
1568 from other files.  For example, I place all of my aliases in
1569 <tt>&tilde;/.mail&lowbar;aliases</tt> so that I can make my
1570 <tt>&tilde;/.muttrc</tt> readable and keep my aliases private.
1571
1572 If the filename begins with a tilde (``&tilde;''), it will be expanded to the
1573 path of your home directory.
1574
1575 If the filename ends with a vertical bar (|), then <em/filename/ is
1576 considered to be an executable program from which to read input (eg.
1577 <tt/source ~/bin/myscript|/).
1578
1579 <sect1>Removing hooks<label id="unhook">
1580 <p>
1581 Usage: <tt/unhook/ &lsqb; * | <em/hook-type/ &rsqb;
1582
1583 This command permits you to flush hooks you have previously defined.
1584 You can either remove all hooks by giving the ``*'' character as an
1585 argument, or you can remove all hooks of a specific type by saying
1586 something like <tt/unhook send-hook/.
1587
1588 <sect>Advanced Usage
1589
1590 <sect1>Regular Expressions<label id="regexp">
1591 <p>
1592 All string patterns in Mutt including those in more complex
1593 <ref id="patterns" name="patterns"> must be specified
1594 using regular expressions (regexp) in the ``POSIX extended'' syntax (which
1595 is more or less the syntax used by egrep and GNU awk).  For your
1596 convenience, we have included below a brief description of this syntax.
1597
1598 The search is case sensitive if the pattern contains at least one upper
1599 case letter, and case insensitive otherwise. Note that ``&bsol;''
1600 must be quoted if used for a regular expression in an initialization
1601 command: ``&bsol;&bsol;''.
1602
1603 A regular expression is a pattern that describes a set of strings.
1604 Regular expressions are constructed analogously to arithmetic
1605 expressions, by using various operators to combine smaller expressions.
1606
1607 Note that the regular expression can be enclosed/delimited by either &dquot;
1608 or ' which is useful if the regular expression includes a white-space
1609 character.  See <ref id="muttrc-syntax" name="Syntax of Initialization Files">
1610 for more information on &dquot; and ' delimiter processing.  To match a
1611 literal &dquot; or ' you must preface it with \ (backslash).
1612
1613 The fundamental building blocks are the regular expressions that match
1614 a single character.  Most characters, including all letters and digits,
1615 are regular expressions that match themselves.  Any metacharacter with
1616 special meaning may be quoted by preceding it with a backslash.
1617
1618 The period ``.'' matches any single character.  The caret ``&circ;'' and
1619 the dollar sign ``&dollar'' are metacharacters that respectively match
1620 the empty string at the beginning and end of a line.
1621
1622 A list of characters enclosed by ``&lsqb;'' and ``&rsqb;'' matches any
1623 single character in that list; if the first character of the list
1624 is a caret ``&circ;'' then it matches any character <bf/not/ in the
1625 list.  For example, the regular expression <bf/&lsqb;0123456789&rsqb;/
1626 matches any single digit.  A range of ASCII characters may be specified
1627 by giving the first and last characters, separated by a hyphen
1628 ``&hyphen;''.  Most metacharacters lose their special meaning inside
1629 lists.  To include a literal ``&rsqb;'' place it first in the list.
1630 Similarly, to include a literal ``&circ;'' place it anywhere but first.
1631 Finally, to include a literal hyphen ``&hyphen;'' place it last.
1632
1633 Certain named classes of characters are predefined.  Character classes
1634 consist of ``&lsqb;:'', a keyword denoting the class, and ``:&rsqb;''.
1635 The following classes are defined by the POSIX standard:
1636
1637 <descrip>
1638 <tag/&lsqb;:alnum:&rsqb;/
1639 Alphanumeric characters.
1640 <tag/&lsqb;:alpha:&rsqb;/
1641 Alphabetic characters.
1642 <tag/&lsqb;:blank:&rsqb;/
1643 Space or tab characters.
1644 <tag/&lsqb;:cntrl:&rsqb;/
1645 Control characters.
1646 <tag/&lsqb;:digit:&rsqb;/
1647 Numeric characters.
1648 <tag/&lsqb;:graph:&rsqb;/
1649 Characters that are both printable and visible.  (A space is printable,
1650 but not visible, while an ``a'' is both.)
1651 <tag/&lsqb;:lower:&rsqb;/
1652 Lower-case alphabetic characters.
1653 <tag/&lsqb;:print:&rsqb;/
1654 Printable characters (characters that are not control characters.)
1655 <tag/&lsqb;:punct:&rsqb;/
1656 Punctuation characters (characters that are not letter, digits, control
1657 characters, or space characters).
1658 <tag/&lsqb;:space:&rsqb;/
1659 Space characters (such as space, tab and formfeed, to name a few).
1660 <tag/&lsqb;:upper:&rsqb;/
1661 Upper-case alphabetic characters.
1662 <tag/&lsqb;:xdigit:&rsqb;/
1663 Characters that are hexadecimal digits.
1664 </descrip>
1665
1666 A character class is only valid in a regular expression inside the
1667 brackets of a character list.  Note that the brackets in these
1668 class names are part of the symbolic names, and must be included
1669 in addition to the brackets delimiting the bracket list.  For
1670 example, <bf/&lsqb;&lsqb;:digit:&rsqb;&rsqb;/ is equivalent to
1671 <bf/&lsqb;0-9&rsqb;/.
1672
1673 Two additional special sequences can appear in character lists.  These
1674 apply to non-ASCII character sets, which can have single symbols (called
1675 collating elements) that are represented with more than one character,
1676 as well as several characters that are equivalent for collating or
1677 sorting purposes:
1678
1679 <descrip>
1680 <tag/Collating Symbols/
1681 A collating symbol is a multi-character collating element enclosed in
1682 ``&lsqb;.'' and ``.&rsqb;''.  For example, if ``ch'' is a collating
1683 element, then <bf/&lsqb;&lsqb;.ch.&rsqb;&rsqb;/ is a regexp that matches
1684 this collating element, while <bf/&lsqb;ch&rsqb;/ is a regexp that
1685 matches either ``c'' or ``h''.
1686 <tag/Equivalence Classes/
1687 An equivalence class is a locale-specific name for a list of
1688 characters that are equivalent. The name is enclosed in ``&lsqb;=''
1689 and ``=&rsqb;''.  For example, the name ``e'' might be used to
1690 represent all of ``&egrave;'' ``&eacute;'' and ``e''.  In this case,
1691 <bf/&lsqb;&lsqb;=e=&rsqb;&rsqb;/ is a regexp that matches any of
1692 ``&egrave;'', ``&eacute;'' and ``e''.
1693 </descrip>
1694
1695 A regular expression matching a single character may be followed by one
1696 of several repetition operators:
1697
1698 <descrip>
1699 <tag/?/
1700 The preceding item is optional and matched at most once.
1701 <tag/*/
1702 The preceding item will be matched zero or more times.
1703 <tag/+/
1704 The preceding item will be matched one or more times.
1705 <tag/&lcub;n&rcub;/
1706 The preceding item is matched exactly <em/n/ times.
1707 <tag/&lcub;n,&rcub;/
1708 The preceding item is matched <em/n/ or more times.
1709 <tag/&lcub;,m&rcub;/
1710 The preceding item is matched at most <em/m/ times.
1711 <tag/&lcub;n,m&rcub;/
1712 The preceding item is matched at least <em/n/ times, but no more than
1713 <em/m/ times.
1714 </descrip>
1715
1716 Two regular expressions may be concatenated; the resulting regular
1717 expression matches any string formed by concatenating two substrings
1718 that respectively match the concatenated subexpressions.
1719
1720 Two regular expressions may be joined by the infix operator ``|'';
1721 the resulting regular expression matches any string matching either
1722 subexpression.
1723
1724 Repetition takes precedence over concatenation, which in turn takes
1725 precedence over alternation.  A whole subexpression may be enclosed in
1726 parentheses to override these precedence rules.
1727
1728 <bf/Note:/ If you compile Mutt with the GNU <em/rx/ package, the
1729 following operators may also be used in regular expressions:
1730
1731 <descrip>
1732 <tag/&bsol;&bsol;y/
1733 Matches the empty string at either the beginning or the end of a word.
1734 <tag/&bsol;&bsol;B/
1735 Matches the empty string within a word.
1736 <tag/&bsol;&bsol;&lt;/
1737 Matches the empty string at the beginning of a word.
1738 <tag/&bsol;&bsol;&gt;/
1739 Matches the empty string at the end of a word.
1740 <tag/&bsol;&bsol;w/
1741 Matches any word-constituent character (letter, digit, or underscore).
1742 <tag/&bsol;&bsol;W/
1743 Matches any character that is not word-constituent.
1744 <tag/&bsol;&bsol;`/
1745 Matches the empty string at the beginning of a buffer (string).
1746 <tag/&bsol;&bsol;'/
1747 Matches the empty string at the end of a buffer.
1748 </descrip>
1749
1750 Please note however that these operators are not defined by POSIX, so
1751 they may or may not be available in stock libraries on various systems.
1752
1753 <sect1>Patterns<label id="patterns">
1754 <p>
1755 Many of Mutt's commands allow you to specify a pattern to match
1756 (limit, tag-pattern, delete-pattern, etc.).  There are several ways to select
1757 messages:
1758
1759 <tscreen><verb>
1760 ~A              all messages
1761 ~b EXPR         messages which contain EXPR in the message body
1762 ~B EXPR         messages which contain EXPR in the whole message
1763 ~c USER         messages carbon-copied to USER
1764 ~C EXPR         message is either to: or cc: EXPR
1765 ~D              deleted messages
1766 ~d [MIN]-[MAX]  messages with ``date-sent'' in a Date range
1767 ~E              expired messages
1768 ~e EXPR         message which contains EXPR in the ``Sender'' field
1769 ~F              flagged messages
1770 ~f USER         messages originating from USER
1771 ~g              cryptographically signed messages
1772 ~G              cryptographically encrypted messages
1773 ~h EXPR         messages which contain EXPR in the message header
1774 ~k              message contains PGP key material
1775 ~i ID           message which match ID in the ``Message-ID'' field
1776 ~L EXPR         message is either originated or received by EXPR
1777 ~l              message is addressed to a known mailing list
1778 ~m [MIN]-[MAX]  message in the range MIN to MAX *)
1779 ~n [MIN]-[MAX]  messages with a score in the range MIN to MAX *)
1780 ~N              new messages
1781 ~O              old messages
1782 ~p              message is addressed to you (consults alternates)
1783 ~P              message is from you (consults alternates)
1784 ~Q              messages which have been replied to
1785 ~R              read messages
1786 ~r [MIN]-[MAX]  messages with ``date-received'' in a Date range
1787 ~S              superseded messages
1788 ~s SUBJECT      messages having SUBJECT in the ``Subject'' field.
1789 ~T              tagged messages
1790 ~t USER         messages addressed to USER
1791 ~U              unread messages
1792 ~v              message is part of a collapsed thread.
1793 ~V              cryptographically verified messages
1794 ~x EXPR         messages which contain EXPR in the `References' field
1795 ~y EXPR         messages which contain EXPR in the `X-Label' field
1796 ~z [MIN]-[MAX]  messages with a size in the range MIN to MAX *)
1797 ~=              duplicated messages (see $duplicate_threads)
1798 </verb></tscreen>
1799
1800 Where EXPR, USER, ID, and SUBJECT are 
1801 <ref id="regexp" name="regular expressions">.  Special attention has to be
1802 made when using regular expressions inside of patterns.  Specifically,
1803 Mutt's parser for these patterns will strip one level of backslash (\),
1804 which is normally used for quoting.  If it is your intention to use a
1805 backslash in the regular expression, you will need to use two backslashes
1806 instead (\\).
1807
1808 *) The forms <tt/&lt;&lsqb;MAX&rsqb;/, <tt/&gt;&lsqb;MIN&rsqb;/,
1809 <tt/&lsqb;MIN&rsqb;-/ and <tt/-&lsqb;MAX&rsqb;/
1810 are allowed, too.
1811
1812 <sect2>Pattern Modifier
1813 <p>
1814
1815 Note that patterns matching 'lists' of addresses (notably c,C,p,P and t)
1816 match if there is at least one match in the whole list. If you want to
1817 make sure that all elements of that list match, you need to prefix your
1818 pattern with ^.
1819 This example matches all mails which only has recipients from Germany.
1820
1821 <tscreen><verb>
1822 ^~C \.de$
1823 </verb></tscreen>
1824
1825 <sect2>Complex Patterns
1826 <p>
1827
1828 Logical AND is performed by specifying more than one criterion.  For
1829 example:
1830
1831 <tscreen><verb>
1832 ~t mutt ~f elkins
1833 </verb></tscreen>
1834
1835 would select messages which contain the word ``mutt'' in the list of
1836 recipients <bf/and/ that have the word ``elkins'' in the ``From'' header
1837 field.
1838
1839 Mutt also recognizes the following operators to create more complex search
1840 patterns:
1841
1842 <itemize>
1843 <item>! -- logical NOT operator
1844 <item>| -- logical OR operator
1845 <item>() -- logical grouping operator
1846 </itemize>
1847
1848 Here is an example illustrating a complex search pattern.  This pattern will
1849 select all messages which do not contain ``mutt'' in the ``To'' or ``Cc''
1850 field and which are from ``elkins''.
1851
1852 <tscreen><verb>
1853 !(~t mutt|~c mutt) ~f elkins
1854 </verb></tscreen>
1855
1856 Here is an example using white space in the regular expression (note
1857 the ' and &dquot; delimiters).  For this to match, the mail's subject must
1858 match the ``^Junk +From +Me$'' and it must be from either ``Jim +Somebody''
1859 or ``Ed +SomeoneElse'':
1860
1861 <tscreen><verb>
1862  '~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")'
1863 </verb></tscreen>
1864
1865 Note that if a regular expression contains parenthesis, or a veritical bar
1866 ("|"), you <bf/must/ enclose the expression in double or single quotes since
1867 those characters are also used to separate different parts of Mutt's
1868 pattern language.  For example,
1869
1870 <tscreen><verb>
1871 ~f "me@(mutt\.org|cs\.hmc\.edu)"
1872 </verb></tscreen>
1873
1874 Without the quotes, the parenthesis would truncate the regular expression
1875 to simply <em/me@/, which is probably not what you want.
1876
1877 <sect2>Searching by Date
1878 <p>
1879 Mutt supports two types of dates, <em/absolute/ and <em/relative/.
1880
1881 <bf/Absolute/.  Dates <bf/must/ be in DD/MM/YY format (month and year are
1882 optional, defaulting to the current month and year).  An example of a valid
1883 range of dates is:
1884
1885 <tscreen><verb>
1886 Limit to messages matching: ~d 20/1/95-31/10
1887 </verb></tscreen>
1888
1889 If you omit the minimum (first) date, and just specify ``-DD/MM/YY'', all
1890 messages <em/before/ the given date will be selected.  If you omit the maximum
1891 (second) date, and specify ``DD/MM/YY-'', all messages <em/after/ the given
1892 date will be selected.  If you specify a single date with no dash (``-''),
1893 only messages sent on the given date will be selected. 
1894
1895 <bf/Error Margins/.  You can add error margins to absolute dates.
1896 An error margin is a sign (+ or -), followed by a digit, followed by
1897 one of the following units:
1898 <verb>
1899 y       years
1900 m       months
1901 w       weeks
1902 d       days
1903 </verb>
1904 As a special case, you can replace the sign by a ``*'' character,
1905 which is equivalent to giving identical plus and minus error margins.
1906
1907 Example: To select any messages two weeks around January 15, 2001,
1908 you'd use the following pattern: 
1909 <tscreen><verb> 
1910 Limit to messages matching: ~d 15/1/2001*2w
1911 </verb></tscreen>
1912
1913
1914 <bf/Relative/.  This type of date is relative to the current date, and may
1915 be specified as:
1916 <itemize>
1917 <item>&gt;<em/offset/ (messages older than <em/offset/ units)
1918 <item>&lt;<em/offset/ (messages newer than <em/offset/ units)
1919 <item>=<em/offset/ (messages exactly <em/offset/ units old)
1920 </itemize>
1921
1922 <em/offset/ is specified as a positive number with one of the following
1923 units:
1924 <verb>
1925 y       years
1926 m       months
1927 w       weeks
1928 d       days
1929 </verb>
1930
1931 Example: to select messages less than 1 month old, you would use
1932 <tscreen><verb>
1933 Limit to messages matching: ~d <1m
1934 </verb></tscreen>
1935
1936
1937
1938 <bf/Note:/ all dates used when searching are relative to the
1939 <bf/local/ time zone, so unless you change the setting of your <ref
1940 id="index_format" name="&dollar;index&lowbar;format"> to include a
1941 <tt/&percnt;&lsqb;...&rsqb;/ format, these are <bf/not/ the dates shown
1942 in the main index.
1943
1944 <sect1>Using Tags
1945 <p>
1946
1947 Sometimes it is desirable to perform an operation on a group of
1948 messages all at once rather than one at a time.  An example might be
1949 to save messages to a mailing list to a separate folder, or to
1950 delete all messages with a given subject.  To tag all messages
1951 matching a pattern, use the tag-pattern function, which is bound to
1952 ``shift-T'' by default.  Or you can select individual messages by
1953 hand using the ``tag-message'' function, which is bound to ``t'' by
1954 default.  See <ref id="patterns" name="patterns"> for Mutt's pattern
1955 matching syntax.
1956
1957 Once you have tagged the desired messages, you can use the
1958 ``tag-prefix'' operator, which is the ``;'' (semicolon) key by default.
1959 When the ``tag-prefix'' operator is used, the <bf/next/ operation will
1960 be applied to all tagged messages if that operation can be used in that
1961 manner.  If the <ref id="auto_tag" name="&dollar;auto&lowbar;tag">
1962 variable is set, the next operation applies to the tagged messages
1963 automatically, without requiring the ``tag-prefix''.
1964
1965 <sect1>Using Hooks<label id="hooks">
1966 <p>
1967 A <em/hook/ is a concept borrowed from the EMACS editor which allows you to
1968 execute arbitrary commands before performing some operation.  For example,
1969 you may wish to tailor your configuration based upon which mailbox you are
1970 reading, or to whom you are sending mail.  In the Mutt world, a <em/hook/
1971 consists of a <ref id="regexp" name="regular expression"> or
1972 <ref id="patterns" name="pattern"> along with a
1973 configuration option/command.  See
1974 <itemize>
1975 <item><ref id="folder-hook" name="folder-hook">
1976 <item><ref id="send-hook" name="send-hook">
1977 <item><ref id="message-hook" name="message-hook">
1978 <item><ref id="save-hook" name="save-hook">
1979 <item><ref id="mbox-hook" name="mbox-hook">
1980 <item><ref id="fcc-hook" name="fcc-hook">
1981 <item><ref id="fcc-save-hook" name="fcc-save-hook">
1982 </itemize>
1983 for specific details on each type of <em/hook/ available.
1984
1985 <bf/Note:/ if a hook changes configuration settings, these changes remain
1986 effective until the end of the current mutt session. As this is generally
1987 not desired, a default hook needs to be added before all other hooks to
1988 restore configuration defaults. Here is an example with send-hook and the
1989 my_hdr directive:
1990
1991 <tscreen><verb>
1992 send-hook . 'unmy_hdr From:'
1993 send-hook ~Cb@b.b my_hdr from: c@c.c
1994 </verb></tscreen>
1995
1996 <sect2>Message Matching in Hooks<label id="pattern_hook">
1997 <p>
1998 Hooks that act upon messages (<tt/send-hook, save-hook, fcc-hook,
1999 message-hook/) are evaluated in a slightly different manner.  For the other
2000 types of hooks, a <ref id="regexp" name="regular expression"> is
2001 sufficient.  But in dealing with messages a finer grain of control is
2002 needed for matching since for different purposes you want to match
2003 different criteria.
2004
2005 Mutt allows the use of the <ref id="patterns" name="search pattern">
2006 language for matching messages in hook commands.  This works in
2007 exactly the same way as it would when <em/limiting/ or
2008 <em/searching/ the mailbox, except that you are restricted to those
2009 operators which match information mutt extracts from the header of
2010 the message (i.e.  from, to, cc, date, subject, etc.).
2011
2012 For example, if you wanted to set your return address based upon sending
2013 mail to a specific address, you could do something like:
2014 <tscreen><verb>
2015 send-hook '~t ^me@cs\.hmc\.edu$' 'my_hdr From: Mutt User <user@host>'
2016 </verb></tscreen>
2017 which would execute the given command when sending mail to
2018 <em/me@cs.hmc.edu/.
2019
2020 However, it is not required that you write the pattern to match using the
2021 full searching language.  You can still specify a simple <em/regular
2022 expression/ like the other hooks, in which case Mutt will translate your
2023 pattern into the full language, using the translation specified by the 
2024 <ref id="default_hook" name="&dollar;default&lowbar;hook"> variable.  The
2025 pattern is translated at the time the hook is declared, so the value of 
2026 <ref id="default_hook" name="&dollar;default&lowbar;hook"> that is in effect
2027 at that time will be used.
2028
2029 <sect1>External Address Queries<label id="query">
2030 <p>
2031 Mutt supports connecting to external directory databases such as LDAP,
2032 ph/qi, bbdb, or NIS through a wrapper script which connects to mutt
2033 using a simple interface.  Using the <ref id="query_command"
2034 name="&dollar;query&lowbar;command"> variable, you specify the wrapper
2035 command to use.  For example:
2036
2037 <tscreen><verb>
2038 set query_command = "mutt_ldap_query.pl '%s'"
2039 </verb></tscreen>
2040
2041 The wrapper script should accept the query on the command-line.  It
2042 should return a one line message, then each matching response on a
2043 single line, each line containing a tab separated address then name then
2044 some other optional information.  On error, or if there are no matching
2045 addresses, return a non-zero exit code and a one line error message.
2046
2047 An example multiple response output:
2048 <tscreen><verb>
2049 Searching database ... 20 entries ... 3 matching:
2050 me@cs.hmc.edu           Michael Elkins  mutt dude
2051 blong@fiction.net       Brandon Long    mutt and more
2052 roessler@guug.de        Thomas Roessler mutt pgp
2053 </verb></tscreen>
2054
2055 There are two mechanisms for accessing the query function of mutt.  One
2056 is to do a query from the index menu using the query function (default: Q).
2057 This will prompt for a query, then bring up the query menu which will
2058 list the matching responses.  From the query menu, you can select
2059 addresses to create aliases, or to mail.  You can tag multiple messages
2060 to mail, start a new query, or have a new query appended to the current
2061 responses.
2062
2063 The other mechanism for accessing the query function is for address
2064 completion, similar to the alias completion.  In any prompt for address
2065 entry, you can use the complete-query function (default: ^T) to run a
2066 query based on the current address you have typed.  Like aliases, mutt
2067 will look for what you have typed back to the last space or comma.  If
2068 there is a single response for that query, mutt will expand the address
2069 in place.  If there are multiple responses, mutt will activate the query
2070 menu.  At the query menu, you can select one or more addresses to be
2071 added to the prompt.
2072
2073 <sect1>Mailbox Formats
2074 <p>
2075 Mutt supports reading and writing of four different mailbox formats:
2076 mbox, MMDF, MH and Maildir.  The mailbox type is autodetected, so there
2077 is no need to use a flag for different mailbox types.  When creating new
2078 mailboxes, Mutt uses the default specified with the <ref id="mbox_type"
2079 name="&dollar;mbox&lowbar;type"> variable.
2080
2081 <bf/mbox/.  This is the most widely used mailbox format for UNIX.  All
2082 messages are stored in a single file.  Each message has a line of the form:
2083
2084 <tscreen><verb>
2085 From me@cs.hmc.edu Fri, 11 Apr 1997 11:44:56 PST
2086 </verb></tscreen>
2087
2088 to denote the start of a new message (this is often referred to as the
2089 ``From&lowbar;'' line).
2090
2091 <bf/MMDF/.  This is a variant of the <em/mbox/ format.  Each message is
2092 surrounded by lines containing ``^A^A^A^A'' (four control-A's).
2093
2094 <bf/MH/. A radical departure from <em/mbox/ and <em/MMDF/, a mailbox
2095 consists of a directory and each message is stored in a separate file.
2096 The filename indicates the message number (however, this is may not
2097 correspond to the message number Mutt displays). Deleted messages are
2098 renamed with a comma (,) prepended to the filename. <bf/Note:/ Mutt
2099 detects this type of mailbox by looking for either <tt/.mh&lowbar;sequences/
2100 or <tt/.xmhcache/ (needed to distinguish normal directories from MH
2101 mailboxes).
2102
2103 <bf/Maildir/.  The newest of the mailbox formats, used by the Qmail MTA (a
2104 replacement for sendmail).  Similar to <em/MH/, except that it adds three
2105 subdirectories of the mailbox: <em/tmp/, <em/new/ and <em/cur/.  Filenames
2106 for the messages are chosen in such a way they are unique, even when two
2107 programs are writing the mailbox over NFS, which means that no file locking
2108 is needed.
2109
2110 <sect1>Mailbox Shortcuts<label id="shortcuts">
2111 <p>
2112 There are a number of built in shortcuts which refer to specific mailboxes.
2113 These shortcuts can be used anywhere you are prompted for a file or mailbox
2114 path.
2115
2116 <itemize>
2117 <item>! -- refers to your <ref id="spoolfile" name="&dollar;spoolfile"> (incoming) mailbox
2118 <item>&gt; -- refers to your <ref id="mbox" name="&dollar;mbox"> file
2119 <item>&lt; -- refers to your <ref id="record" name="&dollar;record"> file
2120 <item>- or !! -- refers to the file you've last visited
2121 <item>&tilde; -- refers to your home directory
2122 <item>= or + -- refers to your <ref id="folder" name="&dollar;folder"> directory
2123 <item>@<em/alias/ -- refers to the <ref id="save-hook" 
2124 name="default save folder"> as determined by the address of the alias
2125 </itemize>
2126
2127 <sect1>Handling Mailing Lists<label id="using_lists">
2128 <p>
2129
2130 Mutt has a few configuration options that make dealing with large
2131 amounts of mail easier.  The first thing you must do is to let Mutt
2132 know what addresses you consider to be mailing lists (technically
2133 this does not have to be a mailing list, but that is what it is most
2134 often used for), and what lists you are subscribed to.  This is
2135 accomplished through the use of the <ref id="lists"
2136 name="lists and subscribe"> commands in your muttrc.
2137
2138 Now that Mutt knows what your mailing lists are, it can do several
2139 things, the first of which is the ability to show the name of a list
2140 through which you received a message (i.e., of a subscribed list) in
2141 the <em/index/ menu display.  This is useful to distinguish between
2142 personal and list mail in the same mailbox.  In the <ref id="index_format"
2143 name="&dollar;index&lowbar;format"> variable, the escape ``&percnt;L''
2144 will return the string ``To &lt;list&gt;'' when ``list'' appears in the
2145 ``To'' field, and ``Cc &lt;list&gt;'' when it appears in the ``Cc''
2146 field (otherwise it returns the name of the author).
2147
2148 Often times the ``To'' and ``Cc'' fields in mailing list messages
2149 tend to get quite large. Most people do not bother to remove the
2150 author of the message they are reply to from the list, resulting in
2151 two or more copies being sent to that person.  The ``list-reply''
2152 function, which by default is bound to ``L'' in the <em/index/ menu
2153 and <em/pager/, helps reduce the clutter by only replying to the
2154 known mailing list addresses instead of all recipients (except as
2155 specified by <tt/Mail-Followup-To/, see below).
2156
2157 Mutt also supports the <tt/Mail-Followup-To/ header.  When you send
2158 a message to a list of recipients which includes one or several
2159 subscribed mailing lists, and if the <ref id="followup_to"
2160 name="&dollar;followup&lowbar;to"> option is set, mutt will generate
2161 a Mail-Followup-To header which contains all the recipients to whom
2162 you send this message, but not your address. This indicates that
2163 group-replies or list-replies (also known as ``followups'') to this
2164 message should only be sent to the original recipients of the
2165 message, and not separately to you - you'll receive your copy through
2166 one of the mailing lists you are subscribed to.
2167
2168 Conversely, when group-replying or list-replying to a message which
2169 has a <tt/Mail-Followup-To/ header, mutt will respect this header if
2170 the <ref id="honor_followup_to"
2171 name="&dollar;honor&lowbar;followup&lowbar;to"> configuration
2172 variable is set.  Using list-reply will in this case also make sure
2173 that the reply goes to the mailing list, even if it's not specified
2174 in the list of recipients in the <tt/Mail-Followup-To/.
2175
2176 Note that, when header editing is enabled, you can create a
2177 <tt/Mail-Followup-To/ header manually.  Mutt will only auto-generate
2178 this header if it doesn't exist when you send the message.
2179
2180
2181 The other method some mailing list admins use is to generate a
2182 ``Reply-To'' field which points back to the mailing list address rather
2183 than the author of the message.  This can create problems when trying
2184 to reply directly to the author in private, since most mail clients
2185 will automatically reply to the address given in the ``Reply-To''
2186 field.  Mutt uses the <ref id="reply_to" name="&dollar;reply&lowbar;to">
2187 variable to help decide which address to use.  If set, you will be
2188 prompted as to whether or not you would like to use the address given in
2189 the ``Reply-To'' field, or reply directly to the address given in the
2190 ``From'' field.  When unset, the ``Reply-To'' field will be used when
2191 present.
2192
2193 The ``X-Label:'' header field can be used to further identify mailing
2194 lists or list subject matter (or just to annotate messages
2195 individually).  The <ref id="index_format"
2196 name="&dollar;index&lowbar;format"> variable's ``&percnt;y'' and
2197 ``&percnt;Y'' escapes can be used to expand ``X-Label:'' fields in the
2198 index, and Mutt's pattern-matcher can match regular expressions to
2199 ``X-Label:'' fields with the ``~y'' selector.  ``X-Label:'' is not a
2200 standard message header field, but it can easily be inserted by procmail
2201 and other mail filtering agents.
2202
2203 Lastly, Mutt has the ability to <ref id="sort" name="sort"> the mailbox into
2204 <ref id="threads" name="threads">.  A thread is a group of messages which all relate to the same
2205 subject.  This is usually organized into a tree-like structure where a
2206 message and all of its replies are represented graphically.  If you've ever
2207 used a threaded news client, this is the same concept.  It makes dealing
2208 with large volume mailing lists easier because you can easily delete
2209 uninteresting threads and quickly find topics of value.
2210
2211 <sect1>Delivery Status Notification (DSN) Support
2212 <p>
2213 RFC1894 defines a set of MIME content types for relaying information
2214 about the status of electronic mail messages.  These can be thought of as
2215 ``return receipts.'' Berkeley sendmail 8.8.x currently has some command
2216 line options in which the mail client can make requests as to what type
2217 of status messages should be returned.
2218
2219 To support this, there are two variables. <ref id="dsn_notify"
2220 name="&dollar;dsn&lowbar;notify"> is used to request receipts for
2221 different results (such as failed message, message delivered, etc.).
2222 <ref id="dsn_return" name="&dollar;dsn&lowbar;return"> requests how much
2223 of your message should be returned with the receipt (headers or full
2224 message).  Refer to the man page on sendmail for more details on DSN.
2225
2226 <sect1>POP3 Support (OPTIONAL)
2227 <p>
2228
2229 If Mutt was compiled with POP3 support (by running the <em/configure/
2230 script with the <em/--enable-pop/ flag), it has the ability to work
2231 with mailboxes located on a remote POP3 server and fetch mail for local
2232 browsing.
2233
2234 You can access the remote POP3 mailbox by selecting the folder
2235 <tt>pop://popserver/</tt>.
2236
2237 You can select an alternative port by specifying it with the server, ie:
2238 <tt>pop://popserver:port/</tt>.
2239
2240 You can also specify different username for each folder, ie:
2241 <tt>pop://username@popserver[:port]/</tt>.
2242
2243 Polling for new mail is more expensive over POP3 than locally. For this
2244 reason the frequency at which Mutt will check for mail remotely can be
2245 controlled by the
2246 <ref id="pop&lowbar;checkinterval" name="&dollar;pop&lowbar;checkinterval">
2247 variable, which defaults to every 60 seconds.
2248
2249 If Mutt was compiled with SSL support (by running the <em/configure/
2250 script with the <em/--with-ssl/ flag), connections to POP3 servers
2251 can be encrypted. This naturally requires that the server supports
2252 SSL encrypted connections. To access a folder with POP3/SSL, you should
2253 use pops: prefix, ie:
2254 <tt>pops://[username@]popserver[:port]/</tt>.
2255
2256 Another way to access your POP3 mail is the <em/fetch-mail/ function
2257 (default: G).  It allows to connect to <ref id="pop_host"
2258 name="pop&lowbar;host">, fetch all your new mail and place it in the
2259 local <ref id="spoolfile" name="spoolfile">.  After this
2260 point, Mutt runs exactly as if the mail had always been local.
2261
2262 <bf/Note:/ If you only need to fetch all messages to local mailbox
2263 you should consider using a specialized program, such as <htmlurl
2264 url="http://www.ccil.org/~esr/fetchmail" name="fetchmail">
2265
2266 <sect1>IMAP Support (OPTIONAL)
2267 <p>
2268
2269 If Mutt was compiled with IMAP support (by running the <em/configure/
2270 script with the <em/--enable-imap/ flag), it has the ability to work
2271 with folders located on a remote IMAP server.
2272
2273 You can access the remote inbox by selecting the folder
2274 <tt>imap://imapserver/INBOX</tt>, where <tt/imapserver/ is the name of the
2275 IMAP server and <tt/INBOX/ is the special name for your spool mailbox on
2276 the IMAP server. If you want to access another mail folder at the IMAP
2277 server, you should use <tt>imap://imapserver/path/to/folder</tt> where
2278 <tt>path/to/folder</tt> is the path of the folder you want to access.
2279
2280 You can select an alternative port by specifying it with the server, ie:
2281 <tt>imap://imapserver:port/INBOX</tt>.
2282
2283 You can also specify different username for each folder, ie:
2284 <tt>imap://username@imapserver[:port]/INBOX</tt>.
2285
2286 If Mutt was compiled with SSL support (by running the <em/configure/
2287 script with the <em/--with-ssl/ flag), connections to IMAP servers
2288 can be encrypted. This naturally requires that the server supports
2289 SSL encrypted connections. To access a folder with IMAP/SSL, you should
2290 use <tt>imaps://[username@]imapserver[:port]/path/to/folder</tt> as your 
2291 folder path.
2292
2293 Pine-compatible notation is also supported, ie
2294 <tt>{[username@]imapserver[:port][/ssl]}path/to/folder</tt>
2295
2296 Note that not all servers use / as the hierarchy separator.  Mutt should
2297 correctly notice which separator is being used by the server and convert
2298 paths accordingly.
2299
2300 When browsing folders on an IMAP server, you can toggle whether to look
2301 at only the folders you are subscribed to, or all folders with the
2302 <em/toggle-subscribed/ command.  See also the 
2303 <ref id="imap&lowbar;list&lowbar;subscribed"
2304 name="&dollar;imap&lowbar;list&lowbar;subscribed"> variable.
2305
2306 Polling for new mail on an IMAP server can cause noticeable delays. So, you'll
2307 want to carefully tune the
2308 <ref id="mail&lowbar;check" name="&dollar;mail&lowbar;check">
2309 and
2310 <ref id="timeout" name="&dollar;timeout">
2311 variables. Personally I use
2312 <tscreen><verb>
2313 set mail_check=90
2314 set timeout=15
2315 </verb></tscreen>
2316 with relatively good results over my slow modem line.
2317
2318 Note that if you are using mbox as the mail store on UW servers prior to
2319 v12.250, the server has been reported to disconnect a client if another client
2320 selects the same folder.
2321
2322 <sect2>The Folder Browser
2323 <p>
2324
2325 As of version 1.2, mutt supports browsing mailboxes on an IMAP
2326 server. This is mostly the same as the local file browser, with the
2327 following differences:
2328 <itemize>
2329 <item>In lieu of file permissions, mutt displays the string "IMAP",
2330   possibly followed by the symbol "+", indicating
2331   that the entry contains both messages and subfolders. On
2332   Cyrus-like servers folders will often contain both messages and
2333   subfolders. 
2334 <item>For the case where an entry can contain both messages and
2335   subfolders, the selection key (bound to <tt>enter</tt> by default)
2336   will choose to descend into the subfolder view. If you wish to view
2337   the messages in that folder, you must use <tt>view-file</tt> instead
2338   (bound to <tt>space</tt> by default).
2339 <item>You can delete mailboxes with the <tt>delete-mailbox</tt>
2340   command (bound to <tt>d</tt> by default. You may also
2341   <tt>subscribe</tt> and <tt>unsubscribe</tt> to mailboxes (normally
2342   these are bound to <tt>s</tt> and <tt>u</tt>, respectively).
2343 </itemize>
2344
2345 <sect2>Authentication
2346 <p>
2347
2348 Mutt supports four authentication methods with IMAP servers: SASL,
2349 GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
2350 NTLM authentication for you poor exchange users out there, but it has
2351 yet to be integrated into the main tree). There is also support for
2352 the pseudo-protocol ANONYMOUS, which allows you to log in to a public
2353 IMAP server without having an account. To use ANONYMOUS, simply make
2354 your username blank or "anonymous".
2355 <p>
2356 SASL is a special super-authenticator, which selects among several protocols
2357 (including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure
2358 method available on your host and the server. Using some of these methods
2359 (including DIGEST-MD5 and possibly GSSAPI), your entire session will be
2360 encrypted and invisible to those teeming network snoops. It is the best
2361 option if you have it. To use it, you must have the Cyrus SASL library
2362 installed on your system and compile mutt with the <em/--with-sasl/ flag.
2363 <p>
2364 Mutt will try whichever methods are compiled in and available on the server,
2365 in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.
2366
2367 There are a few variables which control authentication: 
2368 <itemize>
2369 <item><ref id="imap&lowbar;user" name="&dollar;imap&lowbar;user"> - controls
2370   the username under which you request authentication on the IMAP server,
2371   for all authenticators. This is overridden by an explicit username in
2372   the mailbox path (ie by using a mailbox name of the form
2373   <tt/{user@host}/).
2374 <item><ref id="imap&lowbar;pass" name="&dollar;imap&lowbar;pass"> - a
2375   password which you may preset, used by all authentication methods where
2376   a password is needed.
2377 <item><ref id="imap&lowbar;authenticators"
2378   name="&dollar;imap&lowbar;authenticators"> - a colon-delimited list of IMAP
2379   authentication methods to try, in the order you wish to try them. If
2380   specified, this overrides mutt's default (attempt everything, in the order
2381   listed above).
2382 </itemize>
2383
2384 <sect1>Managing multiple IMAP/POP accounts (OPTIONAL)<label id="account-hook">
2385 <p>
2386
2387 If you happen to have accounts on multiple IMAP and/or POP servers,
2388 you may find managing all the authentication settings inconvenient and
2389 error-prone.  The account-hook command may help. This hook works like
2390 folder-hook but is invoked whenever you access a remote mailbox
2391 (including inside the folder browser), not just when you open the
2392 mailbox.
2393 <p>
2394 Some examples:
2395
2396 <tscreen><verb>
2397 account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
2398 account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
2399 account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
2400 </verb></tscreen>
2401
2402 <sect1>Start a WWW Browser on URLs (EXTERNAL)<label id="urlview">
2403 <p>
2404 If a message contains URLs (<em/unified ressource locator/ = address in the
2405 WWW space like <em>http://www.mutt.org/</em>), it is efficient to get
2406 a menu with all the URLs and start a WWW browser on one of them.  This
2407 functionality is provided by the external urlview program which can be
2408 retrieved at <htmlurl url="ftp://ftp.mutt.org/mutt/contrib/"
2409 name="ftp://ftp.mutt.org/mutt/contrib/"> and the configuration commands:
2410 <tscreen><verb>
2411 macro index \cb |urlview\n
2412 macro pager \cb |urlview\n
2413 </verb></tscreen>
2414
2415 <sect>Mutt's MIME Support
2416 <p>
2417 Quite a bit of effort has been made to make Mutt the premier text-mode
2418 MIME MUA.  Every effort has been made to provide the functionality that
2419 the discerning MIME user requires, and the conformance to the standards
2420 wherever possible.  When configuring Mutt for MIME, there are two extra
2421 types of configuration files which Mutt uses.  One is the
2422 <tt/mime.types/ file, which contains the mapping of file extensions to 
2423 IANA MIME types.  The other is the <tt/mailcap/ file, which specifies
2424 the external commands to use for handling specific MIME types.
2425
2426 <sect1>Using MIME in Mutt
2427 <p>
2428 There are three areas/menus in Mutt which deal with MIME, they are the
2429 pager (while viewing a message), the attachment menu and the compose
2430 menu.
2431
2432 <sect2>Viewing MIME messages in the pager
2433 <p>
2434 When you select a message from the index and view it in the pager, Mutt
2435 decodes the message to a text representation.  Mutt internally supports
2436 a number of MIME types, including <tt>text/plain, text/enriched,
2437 message/rfc822, and message/news</tt>.  In addition, the export
2438 controlled version of Mutt recognizes a variety of PGP MIME types,
2439 including PGP/MIME and application/pgp.
2440
2441 Mutt will denote attachments with a couple lines describing them.
2442 These lines are of the form:
2443 <tscreen><verb>
2444 [-- Attachment #1: Description --]
2445 [-- Type: text/plain, Encoding: 7bit, Size: 10000 --]
2446 </verb></tscreen>
2447 Where the <tt/Description/ is the description or filename given for the
2448 attachment, and the <tt/Encoding/ is one of
2449 <tt>7bit/8bit/quoted-printable/base64/binary</tt>.
2450
2451 If Mutt cannot deal with a MIME type, it will display a message like:
2452 <tscreen><verb>
2453 [-- image/gif is unsupported (use 'v' to view this part) --]
2454 </verb></tscreen>
2455
2456 <sect2>The Attachment Menu<label id="attach_menu">
2457 <p>
2458 The default binding for <tt/view-attachments/ is `v', which displays the
2459 attachment menu for a message.  The attachment menu displays a list of
2460 the attachments in a message.  From the attachment menu, you can save,
2461 print, pipe, delete, and view attachments.  You can apply these
2462 operations to a group of attachments at once, by tagging the attachments
2463 and by using the ``tag-prefix'' operator.  You can also reply to the
2464 current message from this menu, and only the current attachment (or the
2465 attachments tagged) will be quoted in your reply.  You can view
2466 attachments as text, or view them using the mailcap viewer definition.
2467
2468 Finally, you can apply the usual message-related functions (like 
2469 <ref id="resend-message" name="resend-message">, and the reply
2470 and forward functions) to attachments of type <tt>message/rfc822</tt>.
2471
2472 See the help on the attachment menu for more information.
2473
2474 <sect2>The Compose Menu<label id="compose_menu">
2475 <p>
2476 The compose menu is the menu you see before you send a message.  It
2477 allows you to edit the recipient list, the subject, and other aspects
2478 of your message.  It also contains a list of the attachments of your
2479 message, including the main body.  From this menu, you can print, copy,
2480 filter, pipe, edit, compose, review, and rename an attachment or a
2481 list of tagged attachments.  You can also modifying the attachment
2482 information, notably the type, encoding and description.
2483
2484 Attachments appear as follows:
2485 <verb>
2486 -   1 [text/plain, 7bit, 1K]             /tmp/mutt-euler-8082-0 <no description>
2487     2 [applica/x-gunzip, base64, 422K]   ~/src/mutt-0.85.tar.gz <no description>
2488 </verb>
2489
2490 The '-' denotes that Mutt will delete the file after sending (or
2491 postponing, or cancelling) the message.  It can be toggled with the
2492 <tt/toggle-unlink/ command (default: u).  The next field is the MIME
2493 content-type, and can be changed with the <tt/edit-type/ command
2494 (default: ^T).  The next field is the encoding for the attachment,
2495 which allows a binary message to be encoded for transmission on 7bit
2496 links.  It can be changed with the <tt/edit-encoding/ command
2497 (default: ^E).  The next field is the size of the attachment,
2498 rounded to kilobytes or megabytes.  The next field is the filename,
2499 which can be changed with the <tt/rename-file/ command (default: R).
2500 The final field is the description of the attachment, and can be
2501 changed with the <tt/edit-description/ command (default: d).
2502
2503 <sect1>MIME Type configuration with <tt/mime.types/
2504 <p>
2505 When you add an attachment to your mail message, Mutt searches your
2506 personal mime.types file at <tt>&dollar;{HOME}/.mime.types</tt>, and then
2507 the system mime.types file at <tt>/usr/local/share/mutt/mime.types</tt> or
2508 <tt>/etc/mime.types</tt>
2509
2510 The mime.types file consist of lines containing a MIME type and a space
2511 separated list of extensions.  For example:
2512 <tscreen><verb>
2513 application/postscript          ps eps
2514 application/pgp                 pgp
2515 audio/x-aiff                    aif aifc aiff
2516 </verb></tscreen>
2517 A sample <tt/mime.types/ file comes with the Mutt distribution, and
2518 should contain most of the MIME types you are likely to use.  
2519
2520 If Mutt can not determine the mime type by the extension of the file you
2521 attach, it will look at the file.  If the file is free of binary
2522 information, Mutt will assume that the file is plain text, and mark it
2523 as <tt>text/plain</tt>.  If the file contains binary information, then Mutt will
2524 mark it as <tt>application/octet-stream</tt>.  You can change the MIME
2525 type that Mutt assigns to an attachment by using the <tt/edit-type/
2526 command from the compose menu (default: ^T). The MIME type is actually a
2527 major mime type followed by the sub-type, separated by a '/'. 6 major
2528 types: application, text, image, video, audio, and model have been approved
2529 after various internet discussions. Mutt recognises all of these if the 
2530 appropriate entry is found in the mime.types file. It also recognises other
2531 major mime types, such as the chemical type that is widely used in the 
2532 molecular modelling community to pass molecular data in various forms to 
2533 various molecular viewers. Non-recognised mime types should only be used 
2534 if the recipient of the message is likely to be expecting such attachments.
2535
2536 <sect1>MIME Viewer configuration with <tt/mailcap/
2537 <p>
2538 Mutt supports RFC 1524 MIME Configuration, in particular the Unix
2539 specific format specified in Appendix A of RFC 1524.  This file format
2540 is commonly referred to as the mailcap format.  Many MIME compliant
2541 programs utilize the mailcap format, allowing you to specify handling
2542 for all MIME types in one place for all programs.  Programs known to
2543 use this format include Netscape, XMosaic, lynx and metamail.
2544
2545 In order to handle various MIME types that Mutt can not handle
2546 internally, Mutt parses a series of external configuration files to
2547 find an external handler.  The default search string for these files
2548 is a colon delimited list set to
2549 <tscreen><verb>
2550 ${HOME}/.mailcap:/usr/local/share/mutt/mailcap:/etc/mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
2551 </verb></tscreen>
2552 where <tt/&dollar;HOME/ is your home directory.
2553
2554 In particular, the metamail distribution will install a mailcap file,
2555 usually as <tt>/usr/local/etc/mailcap</tt>, which contains some baseline
2556 entries.
2557
2558 <sect2>The Basics of the mailcap file
2559 <p>
2560 A mailcap file consists of a series of lines which are comments, blank,
2561 or definitions.
2562
2563 A comment line consists of a &num; character followed by anything you want.
2564
2565 A blank line is blank.
2566
2567 A definition line consists of a content type, a view command, and any
2568 number of optional fields.  Each field of a definition line is divided
2569 by a semicolon ';' character.
2570
2571 The content type is specified in the MIME standard type/subtype method.
2572 For example,
2573 <tt>text/plain, text/html, image/gif, </tt>
2574 etc.  In addition, the mailcap format includes two formats for
2575 wildcards, one using the special '*' subtype, the other is the implicit
2576 wild, where you only include the major type.  For example, <tt>image/*</tt>, or
2577 <tt>video,</tt> will match all image types and video types,
2578 respectively.
2579
2580 The view command is a Unix command for viewing the type specified. There
2581 are two different types of commands supported. The default is to send
2582 the body of the MIME message to the command on stdin. You can change
2583 this behaviour by using &percnt;s as a parameter to your view command.
2584 This will cause Mutt to save the body of the MIME message to a temporary
2585 file, and then call the view command with the &percnt;s replaced by
2586 the name of the temporary file. In both cases, Mutt will turn over the
2587 terminal to the view program until the program quits, at which time Mutt
2588 will remove the temporary file if it exists.
2589
2590 So, in the simplest form, you can send a text/plain message to the
2591 external pager more on stdin:
2592 <tscreen><verb>
2593 text/plain; more
2594 </verb></tscreen>
2595 Or, you could send the message as a file:
2596 <tscreen><verb>
2597 text/plain; more %s
2598 </verb></tscreen>
2599 Perhaps you would like to use lynx to interactively view a text/html 
2600 message:
2601 <tscreen><verb>
2602 text/html; lynx %s
2603 </verb></tscreen>
2604 In this case, lynx does not support viewing a file from stdin, so you
2605 must use the &percnt;s syntax.
2606 <bf/Note:/ <em>Some older versions of lynx contain a bug where they
2607 will check the mailcap file for a viewer for text/html.  They will find
2608 the line which calls lynx, and run it.  This causes lynx to continuously
2609 spawn itself to view the object.</em>
2610
2611 On the other hand, maybe you don't want to use lynx interactively, you
2612 just want to have it convert the text/html to text/plain, then you can
2613 use:
2614 <tscreen><verb>
2615 text/html; lynx -dump %s | more
2616 </verb></tscreen>
2617
2618 Perhaps you wish to use lynx to view text/html files, and a pager on
2619 all other text formats, then you would use the following:
2620 <tscreen><verb>
2621 text/html; lynx %s
2622 text/*; more
2623 </verb></tscreen>
2624 This is the simplest form of a mailcap file.
2625
2626 <sect2>Secure use of mailcap
2627 <p>
2628 The interpretion of shell meta-characters embedded in MIME parameters
2629 can lead to security problems in general.  Mutt tries to quote parameters
2630 in expansion of %s syntaxes properly, and avoids risky characters by
2631 substituting them, see the <ref id="mailcap_sanitize"
2632 name="mailcap&lowbar;sanitize"> variable.
2633
2634 Although mutt's procedures to invoke programs with mailcap seem to be
2635 safe, there are other applications parsing mailcap, maybe taking less care
2636 of it.  Therefore you should pay attention to the following rules:
2637
2638 <em/Keep the %-expandos away from shell quoting./
2639 Don't quote them with single or double quotes.  Mutt does this for
2640 you, the right way, as should any other program which interprets
2641 mailcap.  Don't put them into backtick expansions.  Be highly careful
2642 with eval statements, and avoid them if possible at all.  Trying to fix
2643 broken behaviour with quotes introduces new leaks - there is no
2644 alternative to correct quoting in the first place.
2645
2646 If you have to use the %-expandos' values in context where you need
2647 quoting or backtick expansions, put that value into a shell variable
2648 and reference the shell variable where necessary, as in the following
2649 example (using <tt/&dollar;charset/ inside the backtick expansion is safe,
2650 since it is not itself subject to any further expansion):
2651
2652 <tscreen><verb>
2653 text/test-mailcap-bug; cat %s; copiousoutput; test=charset=%{charset} \
2654         && test "`echo $charset | tr '[A-Z]' '[a-z]'`" != iso-8859-1
2655 </verb></tscreen>
2656
2657 <sect2>Advanced mailcap Usage
2658 <p>
2659
2660 <sect3>Optional Fields
2661 <p>
2662 In addition to the required content-type and view command fields, you
2663 can add semi-colon ';' separated fields to set flags and other options.
2664 Mutt recognizes the following optional fields:
2665 <descrip>
2666 <tag/copiousoutput/
2667 This flag tells Mutt that the command passes possibly large amounts of
2668 text on stdout.  This causes Mutt to invoke a pager (either the internal
2669 pager or the external pager defined by the pager variable) on the output
2670 of the view command.  Without this flag, Mutt assumes that the command
2671 is interactive.  One could use this to replace the pipe to <tt>more</tt>
2672 in the <tt>lynx -dump</tt> example in the Basic section:
2673 <tscreen><verb>
2674 text/html; lynx -dump %s ; copiousoutput
2675 </verb></tscreen>
2676 This will cause lynx to format the text/html output as text/plain
2677 and Mutt will use your standard pager to display the results.
2678 <tag/needsterminal/
2679 Mutt uses this flag when viewing attachments with <ref id="auto_view"
2680 name="autoview">, in order to decide whether it should honor the setting
2681 of the <ref id="wait_key" name="&dollar;wait&lowbar;key"> variable or
2682 not.  When an attachment is viewed using an interactive program, and the
2683 corresponding mailcap entry has a <em/needsterminal/ flag, Mutt will use
2684 <ref id="wait_key" name="&dollar;wait&lowbar;key"> and the exit status
2685 of the program to decide if it will ask you to press a key after the
2686 external program has exited.  In all other situations it will not prompt
2687 you for a key.
2688 <tag>compose=&lt;command&gt;</tag>
2689 This flag specifies the command to use to create a new attachment of a
2690 specific MIME type.  Mutt supports this from the compose menu.
2691 <tag>composetyped=&lt;command&gt;</tag>
2692 This flag specifies the command to use to create a new attachment of a
2693 specific MIME type.  This command differs from the compose command in
2694 that mutt will expect standard MIME headers on the data.  This can be
2695 used to specify parameters, filename, description, etc. for a new
2696 attachment.   Mutt supports this from the compose menu.
2697 <tag>print=&lt;command&gt;</tag>
2698 This flag specifies the command to use to print a specific MIME type.
2699 Mutt supports this from the attachment and compose menus.
2700 <tag>edit=&lt;command&gt;</tag>
2701 This flag specifies the command to use to edit a specific MIME type.  
2702 Mutt supports this from the compose menu, and also uses it to compose
2703 new attachments.  Mutt will default to the defined editor for text
2704 attachments.
2705 <tag>nametemplate=&lt;template&gt;</tag>
2706 This field specifies the format for the file denoted by &percnt;s in the
2707 command fields.  Certain programs will require a certain file extension,
2708 for instance, to correctly view a file.  For instance, lynx will only
2709 interpret a file as <tt>text/html</tt> if the file ends in <tt/.html/.
2710 So, you would specify lynx as a <tt>text/html</tt> viewer with a line in
2711 the mailcap file like:
2712 <tscreen><verb>
2713 text/html; lynx %s; nametemplate=%s.html
2714 </verb></tscreen>
2715 <tag>test=&lt;command&gt;</tag>
2716 This field specifies a command to run to test whether this mailcap
2717 entry should be used.  The command is defined with the command expansion
2718 rules defined in the next section.  If the command returns 0, then the
2719 test passed, and Mutt uses this entry.  If the command returns non-zero,
2720 then the test failed, and Mutt continues searching for the right entry.
2721 <bf/Note:/ <em>the content-type must match before Mutt performs the test.</em>
2722 For example:
2723 <tscreen><verb>
2724 text/html; netscape -remote 'openURL(%s)' ; test=RunningX
2725 text/html; lynx %s
2726 </verb></tscreen>
2727 In this example, Mutt will run the program RunningX which will return 0
2728 if the X Window manager is running, and non-zero if it isn't.  If
2729 RunningX returns 0, then Mutt will call netscape to display the
2730 text/html object.  If RunningX doesn't return 0, then Mutt will go on
2731 to the next entry and use lynx to display the text/html object.
2732 </descrip>
2733
2734 <sect3>Search Order
2735 <p>
2736 When searching for an entry in the mailcap file, Mutt will search for
2737 the most useful entry for its purpose.  For instance, if you are
2738 attempting to print an <tt>image/gif</tt>, and you have the following
2739 entries in your mailcap file, Mutt will search for an entry with the
2740 print command:
2741 <tscreen><verb>
2742 image/*;        xv %s
2743 image/gif;      ; print= anytopnm %s | pnmtops | lpr; \
2744                 nametemplate=%s.gif
2745 </verb></tscreen>
2746 Mutt will skip the <tt>image/*</tt> entry and use the <tt>image/gif</tt>
2747 entry with the print command.
2748
2749 In addition, you can use this with <ref id="auto_view" name="Autoview"> 
2750 to denote two commands for viewing an attachment, one to be viewed
2751 automatically, the other to be viewed interactively from the attachment
2752 menu.  In addition, you can then use the test feature to determine which
2753 viewer to use interactively depending on your environment.
2754 <tscreen><verb>
2755 text/html;      netscape -remote 'openURL(%s)' ; test=RunningX
2756 text/html;      lynx %s; nametemplate=%s.html
2757 text/html;      lynx -dump %s; nametemplate=%s.html; copiousoutput
2758 </verb></tscreen>
2759 For <ref id="auto_view" name="Autoview">, Mutt will choose the third
2760 entry because of the copiousoutput tag.  For interactive viewing, Mutt
2761 will run the program RunningX to determine if it should use the first
2762 entry.  If the program returns non-zero, Mutt will use the second entry
2763 for interactive viewing.
2764
2765 <sect3>Command Expansion
2766 <p>
2767 The various commands defined in the mailcap files are passed to the
2768 <tt>/bin/sh</tt> shell using the system() function.  Before the
2769 command is passed to <tt>/bin/sh -c</tt>, it is parsed to expand
2770 various special parameters with information from Mutt.  The keywords
2771 Mutt expands are:
2772 <descrip>
2773 <tag/&percnt;s/
2774 As seen in the basic mailcap section, this variable is expanded
2775 to a filename specified by the calling program.  This file contains
2776 the body of the message to view/print/edit or where the composing
2777 program should place the results of composition.  In addition, the
2778 use of this keyword causes Mutt to not pass the body of the message
2779 to the view/print/edit program on stdin.
2780 <tag/&percnt;t/
2781 Mutt will expand &percnt;t to the text representation of the content
2782 type of the message in the same form as the first parameter of the
2783 mailcap definition line, ie <tt>text/html</tt> or
2784 <tt>image/gif</tt>.
2785 <tag>&percnt;{&lt;parameter&gt;}</tag>
2786 Mutt will expand this to the value of the specified parameter
2787 from the Content-Type: line of the mail message.  For instance, if
2788 Your mail message contains:
2789 <tscreen><verb>
2790 Content-Type: text/plain; charset=iso-8859-1
2791 </verb></tscreen>
2792 then Mutt will expand &percnt;{charset} to iso-8859-1.  The default metamail
2793 mailcap file uses this feature to test the charset to spawn an xterm
2794 using the right charset to view the message.
2795 <tag>&bsol;&percnt;</tag>
2796 This will be replaced by a &percnt;
2797 </descrip>
2798 Mutt does not currently support the &percnt;F and &percnt;n keywords
2799 specified in RFC 1524.  The main purpose of these parameters is for
2800 multipart messages, which is handled internally by Mutt.
2801
2802 <sect2>Example mailcap files
2803 <p>
2804 This mailcap file is fairly simple and standard:
2805 <code>
2806 # I'm always running X :)
2807 video/*;        xanim %s > /dev/null
2808 image/*;        xv %s > /dev/null
2809
2810 # I'm always running netscape (if my computer had more memory, maybe)
2811 text/html;      netscape -remote 'openURL(%s)'
2812 </code>
2813
2814 This mailcap file shows quite a number of examples:
2815
2816 <code>
2817 # Use xanim to view all videos   Xanim produces a header on startup,
2818 # send that to /dev/null so I don't see it
2819 video/*;        xanim %s > /dev/null
2820
2821 # Send html to a running netscape by remote
2822 text/html;      netscape -remote 'openURL(%s)'; test=RunningNetscape
2823
2824 # If I'm not running netscape but I am running X, start netscape on the
2825 # object
2826 text/html;      netscape %s; test=RunningX
2827
2828 # Else use lynx to view it as text
2829 text/html;      lynx %s
2830
2831 # This version would convert the text/html to text/plain
2832 text/html;      lynx -dump %s; copiousoutput
2833
2834 # I use enscript to print text in two columns to a page
2835 text/*;         more %s; print=enscript -2Gr %s
2836
2837 # Netscape adds a flag to tell itself to view jpegs internally
2838 image/jpeg;xv %s; x-mozilla-flags=internal
2839
2840 # Use xv to view images if I'm running X
2841 # In addition, this uses the \ to extend the line and set my editor
2842 # for images
2843 image/*;xv %s; test=RunningX; \
2844         edit=xpaint %s
2845
2846 # Convert images to text using the netpbm tools
2847 image/*;  (anytopnm %s | pnmscale -xysize 80 46 | ppmtopgm | pgmtopbm |
2848 pbmtoascii -1x2 ) 2>&1 ; copiousoutput
2849
2850 # Send excel spreadsheets to my NT box
2851 application/ms-excel; open.pl %s
2852 </code>
2853
2854 <sect1>MIME Autoview<label id="auto_view">
2855 <p>
2856 In addition to explicitly telling Mutt to view an attachment with the
2857 MIME viewer defined in the mailcap file, Mutt has support for
2858 automatically viewing MIME attachments while in the pager.
2859
2860 To work, you must define a viewer in the mailcap file which uses the 
2861 <tt/copiousoutput/ option to denote that it is non-interactive.
2862 Usually, you also use the entry to convert the attachment to a text
2863 representation which you can view in the pager.
2864
2865 You then use the <tt/auto&lowbar;view/ muttrc command to list the
2866 content-types that you wish to view automatically.
2867
2868 For instance, if you set auto&lowbar;view to:
2869 <tscreen><verb>
2870 auto_view text/html application/x-gunzip application/postscript image/gif application/x-tar-gz
2871 </verb></tscreen>
2872
2873 Mutt could use the following mailcap entries to automatically view
2874 attachments of these types.
2875 <tscreen><verb>
2876 text/html;      lynx -dump %s; copiousoutput; nametemplate=%s.html
2877 image/*;        anytopnm %s | pnmscale -xsize 80 -ysize 50 | ppmtopgm | pgmtopbm | pbmtoascii ; copiousoutput
2878 application/x-gunzip;   gzcat; copiousoutput
2879 application/x-tar-gz; gunzip -c %s | tar -tf - ; copiousoutput
2880 application/postscript; ps2ascii %s; copiousoutput
2881 </verb></tscreen>
2882
2883 ``unauto_view'' can be used to remove previous entries from the autoview list.
2884 This can be used with message-hook to autoview messages based on size, etc.
2885 ``unauto_view *'' will remove all previous entries.
2886
2887 <sect1>MIME Multipart/Alternative<label id="alternative_order">
2888 <p>
2889 Mutt has some heuristics for determining which attachment of a
2890 multipart/alternative type to display.  First, mutt will check the 
2891 alternative&lowbar;order list to determine if one of the available types
2892 is preferred.  The alternative&lowbar;order list consists of a number of
2893 mimetypes in order, including support for implicit and explicit
2894 wildcards, for example:
2895 <tscreen><verb>
2896 alternative_order text/enriched text/plain text application/postscript image/*
2897 </verb></tscreen>
2898
2899 Next, mutt will check if any of the types have a defined 
2900 <ref id="auto_view" name="auto&lowbar;view">, and use that.  Failing
2901 that, Mutt will look for any text type.  As a last attempt, mutt will
2902 look for any type it knows how to handle.
2903
2904 To remove a MIME type from the <tt/alternative_order/ list, use the
2905 <tt/unalternative_order/ command.
2906
2907 <sect1>MIME Lookup<label id="mime_lookup">
2908 <p>
2909 Mutt's mime&lowbar;lookup list specifies a list of mime-types that should not
2910 be treated according to their mailcap entry.  This option is designed to
2911 deal with binary types such as application/octet-stream.  When an attachment's
2912 mime-type is listed in mime&lowbar;lookup, then the extension of the filename will
2913 be compared to the list of extensions in the mime.types file.  The mime-type
2914 associated with this extension will then be used to process the attachment
2915 according to the rules in the mailcap file and according to any other configuration
2916 options (such as auto&lowbar;view) specified.  Common usage would be:
2917 <tscreen><verb>
2918 mime-lookup application/octet-stream application/X-Lotus-Manuscript
2919 </verb></tscreen>
2920
2921 In addition, the unmime&lowbar;lookup command may be used to disable this feature
2922 for any particular mime-type if it had been set, for example, in a global
2923 muttrc.
2924
2925 <sect>Reference
2926 <sect1>Command line options<label id="commandline">
2927 <p>
2928 Running <tt/mutt/ with no arguments will make Mutt attempt to read your spool
2929 mailbox.  However, it is possible to read other mailboxes and
2930 to send messages from the command line as well.
2931
2932 <tscreen><verb>
2933 -A      expand an alias
2934 -a      attach a file to a message
2935 -b      specify a blind carbon-copy (BCC) address
2936 -c      specify a carbon-copy (Cc) address
2937 -e      specify a config command to be run after initilization files are read
2938 -f      specify a mailbox to load
2939 -F      specify an alternate file to read initialization commands
2940 -h      print help on command line options
2941 -H      specify a draft file from which to read a header and body
2942 -i      specify a file to include in a message composition
2943 -m      specify a default mailbox type
2944 -n      do not read the system Muttrc
2945 -p      recall a postponed message
2946 -Q      query a configuration variable
2947 -R      open mailbox in read-only mode
2948 -s      specify a subject (enclose in quotes if it contains spaces)
2949 -v      show version number and compile-time definitions
2950 -x      simulate the mailx(1) compose mode
2951 -y      show a menu containing the files specified by the mailboxes command
2952 -z      exit immediately if there are no messages in the mailbox
2953 -Z      open the first folder with new message,exit immediately if none
2954 </verb></tscreen>
2955
2956 To read messages in a mailbox
2957
2958 <tt/mutt/ &lsqb; -nz &rsqb; &lsqb; -F <em/muttrc/ &rsqb; &lsqb; -m <em/type/ &rsqb; &lsqb; -f <em/mailbox/ &rsqb; 
2959
2960 To compose a new message
2961
2962 <tt/mutt/ &lsqb; -n &rsqb; &lsqb; -F <em/muttrc/ &rsqb; &lsqb; -a <em/file/ &rsqb; &lsqb; -c <em/address/ &rsqb; &lsqb; -i <em/filename/ &rsqb; &lsqb; -s <em/subject/ &rsqb; <em/address/ &lsqb; <em/address/ ... &rsqb; 
2963
2964 Mutt also supports a ``batch'' mode to send prepared messages.  Simply redirect
2965 input from the file you wish to send.  For example,
2966
2967 <tt>mutt -s &dquot;data set for run &num;2&dquot; professor@bigschool.edu
2968 &lt; &tilde;/run2.dat</tt>
2969
2970 This command will send a message to ``professor@bigschool.edu'' with a subject
2971 of ``data set for run &num;2''.  In the body of the message will be the contents
2972 of the file ``&tilde;/run2.dat''.
2973
2974 <sect1>Configuration Commands<label id="commands">
2975 <p>
2976 The following are the commands understood by mutt.
2977
2978 <itemize>
2979 <item>
2980 <tt><ref id="account-hook" name="account-hook"></tt> <em/pattern/ <em/command/
2981 <item>
2982 <tt><ref id="alias" name="alias"></tt> <em/key/ <em/address/ &lsqb; , <em/address/, ... &rsqb;
2983 <item>
2984 <tt><ref id="alias" name="unalias"></tt> &lsqb; * | <em/key/ ... &rsqb;
2985 <item>
2986 <tt><ref id="alternates" name="alternates"></tt> <em/regexp/ &lsqb; <em/regexp/ ... &rsqb;
2987 <item>
2988 <tt><ref id="alternates" name="unalternates"></tt> &lsqb; * | <em/regexp/ ... &rsqb;
2989 <item>
2990 <tt><ref id="alternative_order" name="alternative&lowbar;order"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
2991 <item>
2992 <tt><ref id="alternative_order" name="unalternative&lowbar;order"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
2993 <item>
2994 <tt><ref id="auto_view" name="auto&lowbar;view"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
2995 <item>
2996 <tt><ref id="auto_view" name="unauto&lowbar;view"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
2997 <item>
2998 <tt><ref id="bind" name="bind"></tt> <em/map/ <em/key/ <em/function/
2999 <item>
3000 <tt><ref id="charset-hook" name="charset-hook"></tt> <em/alias/ <em/charset/
3001 <item>
3002 <tt><ref id="color" name="color"></tt> <em/object/ <em/foreground/ <em/background/ &lsqb; <em/regexp/ &rsqb;
3003 <item>
3004 <tt><ref id="color" name="uncolor"></tt> <em/index/ <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
3005 <item>
3006 <tt><ref id="exec" name="exec"></tt> <em/function/ &lsqb; <em/function/ ... &rsqb;
3007 <item>
3008 <tt><ref id="fcc-hook" name="fcc-hook"></tt> <em/pattern/ <em/mailbox/
3009 <item>
3010 <tt><ref id="fcc-save-hook" name="fcc-save-hook"></tt> <em/pattern/ <em/mailbox/
3011 <item>
3012 <tt><ref id="folder-hook" name="folder-hook"></tt> <em/pattern/ <em/command/
3013 <item>
3014 <tt><ref id="hdr_order" name="hdr&lowbar;order"></tt> <em/header/ &lsqb; <em/header/ ... &rsqb;
3015 <item>
3016 <tt><ref id="hdr_order" name="unhdr&lowbar;order"></tt> <em/header/ &lsqb; <em/header/ ... &rsqb;
3017 <item>
3018 <tt><ref id="charset-hook" name="iconv-hook"></tt> <em/charset/ <em/local-charset/
3019 <item>
3020 <tt><ref id="ignore" name="ignore"></tt> <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
3021 <item>
3022 <tt><ref id="ignore" name="unignore"></tt> <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
3023 <item>
3024 <tt><ref id="lists" name="lists"></tt> <em/address/ &lsqb; <em/address/ ... &rsqb; 
3025 <item>
3026 <tt><ref id="lists" name="unlists"></tt> <em/address/ &lsqb; <em/address/ ... &rsqb; 
3027 <item>
3028 <tt><ref id="macro" name="macro"></tt> <em/menu/ <em/key/ <em/sequence/ &lsqb; <em/description/ &rsqb; 
3029 <item>
3030 <tt><ref id="mailboxes" name="mailboxes"></tt> <em/filename/ &lsqb; <em/filename/ ... &rsqb;
3031 <item>
3032 <tt><ref id="mbox-hook" name="mbox-hook"></tt> <em/pattern/ <em/mailbox/
3033 <item>
3034 <tt><ref id="message-hook" name="message-hook"></tt> <em/pattern/ <em/command/
3035 <item>
3036 <tt><ref id="mime_lookup" name="mime&lowbar;lookup"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
3037 <item>
3038 <tt><ref id="mime_lookup" name="unmime&lowbar;lookup"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
3039 <item>
3040 <tt><ref id="color" name="mono"></tt> <em/object attribute/ &lsqb; <em/regexp/ &rsqb;
3041 <item>
3042 <tt><ref id="color" name="unmono"></tt> <em/index/ <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
3043 <item>
3044 <tt><ref id="my_hdr" name="my&lowbar;hdr"></tt> <em/string/
3045 <item>
3046 <tt><ref id="my_hdr" name="unmy&lowbar;hdr"></tt> <em/field/ &lsqb; <em/field/ ... &rsqb;
3047 <item>
3048 <tt><ref id="crypt-hook" name="crypt-hook"></tt> <em/pattern/ <em/key-id/
3049 <item>
3050 <tt><ref id="push" name="push"></tt> <em/string/
3051 <item>
3052 <tt><ref id="set" name="reset"></tt> <em/variable/ &lsqb;<em/variable/ ... &rsqb;
3053 <item>
3054 <tt><ref id="save-hook" name="save-hook"></tt> <em/regexp/ <em/filename/
3055 <item>
3056 <tt><ref id="score-command" name="score"></tt> <em/pattern/ <em/value/
3057 <item>
3058 <tt><ref id="score-command" name="unscore"></tt> <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
3059 <item>
3060 <tt><ref id="send-hook" name="send-hook"></tt> <em/regexp/ <em/command/
3061 <item>
3062 <tt><ref id="set" name="set"></tt> &lsqb;no|inv&rsqb;<em/variable/&lsqb;=<em/value/&rsqb; &lsqb; <em/variable/ ... &rsqb;
3063 <item>
3064 <tt><ref id="set" name="unset"></tt> <em/variable/ &lsqb;<em/variable/ ... &rsqb;
3065 <item>
3066 <tt><ref id="source" name="source"></tt> <em/filename/
3067 <item>
3068 <tt><ref id="lists" name="subscribe"></tt> <em/address/ &lsqb; <em/address/ ... &rsqb; 
3069 <item>
3070 <tt><ref id="lists" name="unsubscribe"></tt> <em/address/ &lsqb; <em/address/ ... &rsqb; 
3071 <item>
3072 <tt><ref id="set" name="toggle"></tt> <em/variable/ &lsqb;<em/variable/ ... &rsqb;
3073 <item>
3074 <tt><ref id="unhook" name="unhook"></tt> <em/hook-type/
3075 </itemize>
3076
3077 <sect1>Configuration variables<label id="variables">
3078 <p>
3079
3080
3081 <sect2>abort&lowbar;nosubject<label id="abort_nosubject">
3082 <p>
3083 Type: quadoption<newline>
3084 Default: ask-yes
3085
3086 <p>
3087 If set to <em>yes</em>, when composing messages and no subject is given
3088 at the subject prompt, composition will be aborted.  If set to
3089 <em>no</em>, composing messages with no subject given at the subject
3090 prompt will never be aborted.
3091
3092
3093 <sect2>abort&lowbar;unmodified<label id="abort_unmodified">
3094 <p>
3095 Type: quadoption<newline>
3096 Default: yes
3097
3098 <p>
3099 If set to <em>yes</em>, composition will automatically abort after
3100 editing the message body if no changes are made to the file (this
3101 check only happens after the <em>first</em> edit of the file).  When set
3102 to <em>no</em>, composition will never be aborted.
3103
3104
3105 <sect2>alias&lowbar;file<label id="alias_file">
3106 <p>
3107 Type: path<newline>
3108 Default: &dquot;&tilde;/.muttrc&dquot;
3109
3110 <p>
3111 The default file in which to save aliases created by the 
3112 ``<ref id="create-alias" name="create-alias">'' function.
3113 <p>
3114 <bf>Note:</bf> Mutt will not automatically source this file; you must
3115 explicitly use the ``<ref id="source" name="source">'' command for it to be executed.
3116
3117
3118 <sect2>alias&lowbar;format<label id="alias_format">
3119 <p>
3120 Type: string<newline>
3121 Default: &dquot;&percnt;4n &percnt;2f &percnt;t &percnt;-10a   &percnt;r&dquot;
3122
3123 <p>
3124 Specifies the format of the data displayed for the `alias' menu.  The
3125 following printf(3)-style sequences are available:
3126 <p>
3127
3128 <descrip>
3129 <tag>&percnt;a </tag>alias name
3130 <tag>&percnt;f </tag>flags - currently, a &dquot;d&dquot; for an alias marked for deletion
3131 <tag>&percnt;n </tag>index number
3132 <tag>&percnt;r </tag>address which alias expands to
3133 <tag>&percnt;t </tag>character which indicates if the alias is tagged for inclusion
3134 </descrip>
3135
3136
3137 <sect2>allow&lowbar;8bit<label id="allow_8bit">
3138 <p>
3139 Type: boolean<newline>
3140 Default: yes
3141
3142 <p>
3143 Controls whether 8-bit data is converted to 7-bit using either Quoted-
3144 Printable or Base64 encoding when sending mail.
3145
3146
3147 <sect2>allow&lowbar;ansi<label id="allow_ansi">
3148 <p>
3149 Type: boolean<newline>
3150 Default: no
3151
3152 <p>
3153 Controls whether ANSI color codes in messages (and color tags in 
3154 rich text messages) are to be interpreted.
3155 Messages containing these codes are rare, but if this option is set,
3156 their text will be colored accordingly. Note that this may override
3157 your color choices, and even present a security problem, since a
3158 message could include a line like &dquot;&lsqb;-- PGP output follows ...&dquot; and
3159 give it the same color as your attachment color.
3160
3161
3162 <sect2>arrow&lowbar;cursor<label id="arrow_cursor">
3163 <p>
3164 Type: boolean<newline>
3165 Default: no
3166
3167 <p>
3168 When set, an arrow (``-&gt;'') will be used to indicate the current entry
3169 in menus instead of highlighting the whole line.  On slow network or modem
3170 links this will make response faster because there is less that has to
3171 be redrawn on the screen when moving to the next or previous entries
3172 in the menu.
3173
3174
3175 <sect2>ascii&lowbar;chars<label id="ascii_chars">
3176 <p>
3177 Type: boolean<newline>
3178 Default: no
3179
3180 <p>
3181 If set, Mutt will use plain ASCII characters when displaying thread
3182 and attachment trees, instead of the default <em>ACS</em> characters.
3183
3184
3185 <sect2>askbcc<label id="askbcc">
3186 <p>
3187 Type: boolean<newline>
3188 Default: no
3189
3190 <p>
3191 If set, Mutt will prompt you for blind-carbon-copy (Bcc) recipients
3192 before editing an outgoing message.
3193
3194
3195 <sect2>askcc<label id="askcc">
3196 <p>
3197 Type: boolean<newline>
3198 Default: no
3199
3200 <p>
3201 If set, Mutt will prompt you for carbon-copy (Cc) recipients before
3202 editing the body of an outgoing message.
3203
3204
3205 <sect2>ask&lowbar;follow&lowbar;up<label id="ask_follow_up">
3206 <p>
3207 Type: boolean<newline>
3208 Default: no
3209
3210 <p>
3211 If set, Mutt will prompt you for follow-up groups before editing
3212 the body of an outgoing message.
3213
3214
3215 <sect2>ask&lowbar;x&lowbar;comment&lowbar;to<label id="ask_x_comment_to">
3216 <p>
3217 Type: boolean<newline>
3218 Default: no
3219
3220 <p>
3221 If set, Mutt will prompt you for x-comment-to field before editing
3222 the body of an outgoing message.
3223
3224
3225 <sect2>attach&lowbar;format<label id="attach_format">
3226 <p>
3227 Type: string<newline>
3228 Default: &dquot;&percnt;u&percnt;D&percnt;I &percnt;t&percnt;4n &percnt;T&percnt;.40d&percnt;&gt; &lsqb;&percnt;.7m/&percnt;.10M, &percnt;.6e&percnt;?C?, &percnt;C?, &percnt;s&rsqb; &dquot;
3229
3230 <p>
3231 This variable describes the format of the `attachment' menu.  The
3232 following printf-style sequences are understood:
3233 <p>
3234
3235 <descrip>
3236 <tag>&percnt;C  </tag>charset
3237 <tag>&percnt;c  </tag>reqiures charset conversion (n or c)
3238 <tag>&percnt;D  </tag>deleted flag
3239 <tag>&percnt;d  </tag>description
3240 <tag>&percnt;e  </tag>MIME content-transfer-encoding
3241 <tag>&percnt;f  </tag>filename
3242 <tag>&percnt;I  </tag>disposition (I=inline, A=attachment)
3243 <tag>&percnt;m  </tag>major MIME type
3244 <tag>&percnt;M  </tag>MIME subtype
3245 <tag>&percnt;n  </tag>attachment number
3246 <tag>&percnt;s  </tag>size
3247 <tag>&percnt;t  </tag>tagged flag
3248 <tag>&percnt;T  </tag>graphic tree characters
3249 <tag>&percnt;u  </tag>unlink (=to delete) flag
3250 <tag>&percnt;&gt;X </tag>right justify the rest of the string and pad with character &dquot;X&dquot;
3251 <tag>&percnt;|X </tag>pad to the end of the line with character &dquot;X&dquot;
3252 </descrip>
3253
3254
3255 <sect2>attach&lowbar;sep<label id="attach_sep">
3256 <p>
3257 Type: string<newline>
3258 Default: &dquot;&bsol;n&dquot;
3259
3260 <p>
3261 The separator to add between attachments when operating (saving,
3262 printing, piping, etc) on a list of tagged attachments.
3263
3264
3265 <sect2>attach&lowbar;split<label id="attach_split">
3266 <p>
3267 Type: boolean<newline>
3268 Default: yes
3269
3270 <p>
3271 If this variable is unset, when operating (saving, printing, piping,
3272 etc) on a list of tagged attachments, Mutt will concatenate the
3273 attachments and will operate on them as a single attachment. The
3274 ``<ref id="attach_sep" name="&dollar;attach&lowbar;sep">'' separator is added after each attachment. When set,
3275 Mutt will operate on the attachments one by one.
3276
3277
3278 <sect2>attribution<label id="attribution">
3279 <p>
3280 Type: string<newline>
3281 Default: &dquot;On &percnt;d, &percnt;n wrote:&dquot;
3282
3283 <p>
3284 This is the string that will precede a message which has been included
3285 in a reply.  For a full listing of defined printf()-like sequences see
3286 the section on ``<ref id="index_format" name="&dollar;index&lowbar;format">''.
3287
3288
3289 <sect2>autoedit<label id="autoedit">
3290 <p>
3291 Type: boolean<newline>
3292 Default: no
3293
3294 <p>
3295 When set along with ``<ref id="edit_headers" name="&dollar;edit&lowbar;headers">'', Mutt will skip the initial
3296 send-menu and allow you to immediately begin editing the body of your
3297 message.  The send-menu may still be accessed once you have finished
3298 editing the body of your message.
3299 <p>
3300 Also see ``<ref id="fast_reply" name="&dollar;fast&lowbar;reply">''.
3301
3302
3303 <sect2>auto&lowbar;tag<label id="auto_tag">
3304 <p>
3305 Type: boolean<newline>
3306 Default: no
3307
3308 <p>
3309 When set, functions in the <em>index</em> menu which affect a message
3310 will be applied to all tagged messages (if there are any).  When
3311 unset, you must first use the tag-prefix function (default: &dquot;;&dquot;) to
3312 make the next function apply to all tagged messages.
3313
3314
3315 <sect2>beep<label id="beep">
3316 <p>
3317 Type: boolean<newline>
3318 Default: yes
3319
3320 <p>
3321 When this variable is set, mutt will beep when an error occurs.
3322
3323
3324 <sect2>beep&lowbar;new<label id="beep_new">
3325 <p>
3326 Type: boolean<newline>
3327 Default: no
3328
3329 <p>
3330 When this variable is set, mutt will beep whenever it prints a message
3331 notifying you of new mail.  This is independent of the setting of the
3332 ``<ref id="beep" name="&dollar;beep">'' variable.
3333
3334
3335 <sect2>bounce<label id="bounce">
3336 <p>
3337 Type: quadoption<newline>
3338 Default: ask-yes
3339
3340 <p>
3341 Controls whether you will be asked to confirm bouncing messages.
3342 If set to <em>yes</em> you don't get asked if you want to bounce a
3343 message. Setting this variable to <em>no</em> is not generally useful,
3344 and thus not recommended, because you are unable to bounce messages.
3345
3346
3347 <sect2>bounce&lowbar;delivered<label id="bounce_delivered">
3348 <p>
3349 Type: boolean<newline>
3350 Default: yes
3351
3352 <p>
3353 When this variable is set, mutt will include Delivered-To headers when
3354 bouncing messages.  Postfix users may wish to unset this variable.
3355
3356
3357 <sect2>catchup&lowbar;newsgroup<label id="catchup_newsgroup">
3358 <p>
3359 Type: quadoption<newline>
3360 Default: ask-yes
3361
3362 <p>
3363 If this variable is <em>set</em>, Mutt will mark all articles in newsgroup
3364 as read when you quit the newsgroup (catchup newsgroup).
3365
3366
3367 <sect2>charset<label id="charset">
3368 <p>
3369 Type: string<newline>
3370 Default: &dquot;&dquot;
3371
3372 <p>
3373 Character set your terminal uses to display and enter textual data.
3374
3375
3376 <sect2>check&lowbar;new<label id="check_new">
3377 <p>
3378 Type: boolean<newline>
3379 Default: yes
3380
3381 <p>
3382 <bf>Note:</bf> this option only affects <em>maildir</em> and <em>MH</em> style
3383 mailboxes.
3384 <p>
3385 When <em>set</em>, Mutt will check for new mail delivered while the
3386 mailbox is open.  Especially with MH mailboxes, this operation can
3387 take quite some time since it involves scanning the directory and
3388 checking each file to see if it has already been looked at.  If
3389 <em>check&lowbar;new</em> is <em>unset</em>, no check for new mail is performed
3390 while the mailbox is open.
3391
3392
3393 <sect2>collapse&lowbar;unread<label id="collapse_unread">
3394 <p>
3395 Type: boolean<newline>
3396 Default: yes
3397
3398 <p>
3399 When <em>unset</em>, Mutt will not collapse a thread if it contains any
3400 unread messages.
3401
3402
3403 <sect2>uncollapse&lowbar;jump<label id="uncollapse_jump">
3404 <p>
3405 Type: boolean<newline>
3406 Default: no
3407
3408 <p>
3409 When <em>set</em>, Mutt will jump to the next unread message, if any,
3410 when the current thread is <em>un</em>collapsed.
3411
3412
3413 <sect2>compose&lowbar;format<label id="compose_format">
3414 <p>
3415 Type: string<newline>
3416 Default: &dquot;-- Mutt: Compose  &lsqb;Approx. msg size: &percnt;l   Atts: &percnt;a&rsqb;&percnt;&gt;-&dquot;
3417
3418 <p>
3419 Controls the format of the status line displayed in the &bsol;fCompose
3420 menu.  This string is similar to ``<ref id="status_format" name="&dollar;status&lowbar;format">'', but has its own
3421 set of printf()-like sequences:
3422 <p>
3423
3424 <descrip>
3425 <tag>&percnt;a </tag>total number of attachments 
3426 <tag>&percnt;h </tag>local hostname
3427 <tag>&percnt;l </tag>approximate size (in bytes) of the current message
3428 <tag>&percnt;v </tag>Mutt version string
3429 </descrip>
3430
3431 <p>
3432 See the text describing the ``<ref id="status_format" name="&dollar;status&lowbar;format">'' option for more 
3433 information on how to set ``<ref id="compose_format" name="&dollar;compose&lowbar;format">''.
3434
3435
3436 <sect2>confirmappend<label id="confirmappend">
3437 <p>
3438 Type: boolean<newline>
3439 Default: yes
3440
3441 <p>
3442 When set, Mutt will prompt for confirmation when appending messages to
3443 an existing mailbox.
3444
3445
3446 <sect2>confirmcreate<label id="confirmcreate">
3447 <p>
3448 Type: boolean<newline>
3449 Default: yes
3450
3451 <p>
3452 When set, Mutt will prompt for confirmation when saving messages to a
3453 mailbox which does not yet exist before creating it.
3454
3455
3456 <sect2>connect&lowbar;timeout<label id="connect_timeout">
3457 <p>
3458 Type: number<newline>
3459 Default: 30
3460
3461 <p>
3462 Causes Mutt to timeout a network connection (for IMAP or POP) after this
3463 many seconds if the connection is not able to be established.  A negative
3464 value causes Mutt to wait indefinitely for the connection to succeed.
3465
3466
3467 <sect2>content&lowbar;type<label id="content_type">
3468 <p>
3469 Type: string<newline>
3470 Default: &dquot;text/plain&dquot;
3471
3472 <p>
3473 Sets the default Content-Type for the body of newly composed messages.
3474
3475
3476 <sect2>copy<label id="copy">
3477 <p>
3478 Type: quadoption<newline>
3479 Default: yes
3480
3481 <p>
3482 This variable controls whether or not copies of your outgoing messages
3483 will be saved for later references.  Also see ``<ref id="record" name="&dollar;record">'',
3484 ``<ref id="save_name" name="&dollar;save&lowbar;name">'', ``<ref id="force_name" name="&dollar;force&lowbar;name">'' and ``<ref id="fcc-hook" name="fcc-hook">''.
3485
3486
3487 <sect2>crypt&lowbar;autopgp<label id="crypt_autopgp">
3488 <p>
3489 Type: boolean<newline>
3490 Default: yes
3491
3492 <p>
3493 This variable controls whether or not mutt may automatically enable
3494 PGP encryption/signing for messages.  See also ``<ref id="crypt_autoencrypt" name="&dollar;crypt&lowbar;autoencrypt">'',
3495 ``<ref id="crypt_replyencrypt" name="&dollar;crypt&lowbar;replyencrypt">'',
3496 ``<ref id="crypt_autosign" name="&dollar;crypt&lowbar;autosign">'', ``<ref id="crypt_replysign" name="&dollar;crypt&lowbar;replysign">'' and ``<ref id="smime_is_default" name="&dollar;smime&lowbar;is&lowbar;default">''.
3497
3498
3499 <sect2>crypt&lowbar;autosmime<label id="crypt_autosmime">
3500 <p>
3501 Type: boolean<newline>
3502 Default: yes
3503
3504 <p>
3505 This variable controls whether or not mutt may automatically enable
3506 S/MIME encryption/signing for messages. See also ``<ref id="crypt_autoencrypt" name="&dollar;crypt&lowbar;autoencrypt">'',
3507 ``<ref id="crypt_replyencrypt" name="&dollar;crypt&lowbar;replyencrypt">'',
3508 ``<ref id="crypt_autosign" name="&dollar;crypt&lowbar;autosign">'', ``<ref id="crypt_replysign" name="&dollar;crypt&lowbar;replysign">'' and ``<ref id="smime_is_default" name="&dollar;smime&lowbar;is&lowbar;default">''.
3509
3510
3511 <sect2>date&lowbar;format<label id="date_format">
3512 <p>
3513 Type: string<newline>
3514 Default: &dquot;!&percnt;a, &percnt;b &percnt;d, &percnt;Y at &percnt;I:&percnt;M:&percnt;S&percnt;p &percnt;Z&dquot;
3515
3516 <p>
3517 This variable controls the format of the date printed by the ``&percnt;d''
3518 sequence in ``<ref id="index_format" name="&dollar;index&lowbar;format">''.  This is passed to the <em>strftime</em>
3519 call to process the date. See the man page for <em>strftime(3)</em> for
3520 the proper syntax.
3521 <p>
3522 Unless the first character in the string is a bang (``!''), the month
3523 and week day names are expanded according to the locale specified in
3524 the variable ``<ref id="locale" name="&dollar;locale">''. If the first character in the string is a
3525 bang, the bang is discarded, and the month and week day names in the
3526 rest of the string are expanded in the <em>C</em> locale (that is in US
3527 English).
3528
3529
3530 <sect2>default&lowbar;hook<label id="default_hook">
3531 <p>
3532 Type: string<newline>
3533 Default: &dquot;&tilde;f &percnt;s !&tilde;P | (&tilde;P &tilde;C &percnt;s)&dquot;
3534
3535 <p>
3536 This variable controls how send-hooks, message-hooks, save-hooks,
3537 and fcc-hooks will
3538 be interpreted if they are specified with only a simple regexp,
3539 instead of a matching pattern.  The hooks are expanded when they are
3540 declared, so a hook will be interpreted according to the value of this
3541 variable at the time the hook is declared.  The default value matches
3542 if the message is either from a user matching the regular expression
3543 given, or if it is from you (if the from address matches
3544 ``alternates'') and is to or cc'ed to a user matching the given
3545 regular expression.
3546
3547
3548 <sect2>delete<label id="delete">
3549 <p>
3550 Type: quadoption<newline>
3551 Default: ask-yes
3552
3553 <p>
3554 Controls whether or not messages are really deleted when closing or
3555 synchronizing a mailbox.  If set to <em>yes</em>, messages marked for
3556 deleting will automatically be purged without prompting.  If set to
3557 <em>no</em>, messages marked for deletion will be kept in the mailbox.
3558
3559
3560 <sect2>delete&lowbar;untag<label id="delete_untag">
3561 <p>
3562 Type: boolean<newline>
3563 Default: yes
3564
3565 <p>
3566 If this option is <em>set</em>, mutt will untag messages when marking them
3567 for deletion.  This applies when you either explicitly delete a message,
3568 or when you save it to another folder.
3569
3570
3571 <sect2>digest&lowbar;collapse<label id="digest_collapse">
3572 <p>
3573 Type: boolean<newline>
3574 Default: yes
3575
3576 <p>
3577 If this option is <em>set</em>, mutt's revattach menu will not show the subparts of
3578 individual messages in a digest.  To see these subparts, press 'v' on that menu.
3579
3580
3581 <sect2>display&lowbar;filter<label id="display_filter">
3582 <p>
3583 Type: path<newline>
3584 Default: &dquot;&dquot;
3585
3586 <p>
3587 When set, specifies a command used to filter messages.  When a message
3588 is viewed it is passed as standard input to <ref id="display_filter" name="&dollar;display&lowbar;filter">, and the
3589 filtered message is read from the standard output.
3590
3591
3592 <sect2>dotlock&lowbar;program<label id="dotlock_program">
3593 <p>
3594 Type: path<newline>
3595 Default: &dquot;/usr/local/bin/mutt&lowbar;dotlock&dquot;
3596
3597 <p>
3598 Contains the path of the mutt&lowbar;dotlock (8) binary to be used by
3599 mutt.
3600
3601
3602 <sect2>dsn&lowbar;notify<label id="dsn_notify">
3603 <p>
3604 Type: string<newline>
3605 Default: &dquot;&dquot;
3606
3607 <p>
3608 <bf>Note:</bf> you should not enable this unless you are using Sendmail
3609 8.8.x or greater.
3610 <p>
3611 This variable sets the request for when notification is returned.  The
3612 string consists of a comma separated list (no spaces!) of one or more
3613 of the following: <em>never</em>, to never request notification,
3614 <em>failure</em>, to request notification on transmission failure,
3615 <em>delay</em>, to be notified of message delays, <em>success</em>, to be
3616 notified of successful transmission.
3617 <p>
3618 Example: set dsn&lowbar;notify=&dquot;failure,delay&dquot;
3619
3620
3621 <sect2>dsn&lowbar;return<label id="dsn_return">
3622 <p>
3623 Type: string<newline>
3624 Default: &dquot;&dquot;
3625
3626 <p>
3627 <bf>Note:</bf> you should not enable this unless you are using Sendmail
3628 8.8.x or greater.
3629 <p>
3630 This variable controls how much of your message is returned in DSN
3631 messages.  It may be set to either <em>hdrs</em> to return just the
3632 message header, or <em>full</em> to return the full message.
3633 <p>
3634 Example: set dsn&lowbar;return=hdrs
3635
3636
3637 <sect2>duplicate&lowbar;threads<label id="duplicate_threads">
3638 <p>
3639 Type: boolean<newline>
3640 Default: yes
3641
3642 <p>
3643 This variable controls whether mutt, when sorting by threads, threads
3644 messages with the same message-id together.  If it is set, it will indicate
3645 that it thinks they are duplicates of each other with an equals sign
3646 in the thread diagram.
3647
3648
3649 <sect2>edit&lowbar;headers<label id="edit_headers">
3650 <p>
3651 Type: boolean<newline>
3652 Default: no
3653
3654 <p>
3655 This option allows you to edit the header of your outgoing messages
3656 along with the body of your message.
3657
3658
3659 <sect2>editor<label id="editor">
3660 <p>
3661 Type: path<newline>
3662 Default: &dquot;&dquot;
3663
3664 <p>
3665 This variable specifies which editor is used by mutt.
3666 It defaults to the value of the VISUAL, or EDITOR, environment
3667 variable, or to the string &dquot;vi&dquot; if neither of those are set.
3668
3669
3670 <sect2>encode&lowbar;from<label id="encode_from">
3671 <p>
3672 Type: boolean<newline>
3673 Default: no
3674
3675 <p>
3676 When <em>set</em>, mutt will quoted-printable encode messages when
3677 they contain the string &dquot;From &dquot; in the beginning of a line.
3678 Useful to avoid the tampering certain mail delivery and transport
3679 agents tend to do with messages.
3680
3681
3682 <sect2>envelope&lowbar;from<label id="envelope_from">
3683 <p>
3684 Type: boolean<newline>
3685 Default: no
3686
3687 <p>
3688 When <em>set</em>, mutt will try to derive the message's <em>envelope</em>
3689 sender from the &dquot;From:&dquot; header.  Note that this information is passed 
3690 to sendmail command using the &dquot;-f&dquot; command line switch, so don't set this
3691 option if you are using that switch in <ref id="sendmail" name="&dollar;sendmail"> yourself,
3692 or if the sendmail on your machine doesn't support that command
3693 line switch.
3694